PKG Deploy

Docs

Releases

A release in PKG Deploy is a build triggered for a project which creates packages with your software at a specific version

Each release has the following steps:

  • Received - A new release has been received via a valid trigger. More info in triggering releases below.
  • Waiting for build slot - Each organisation has a certain number of slots. A package build will not start until there is a free slot
  • Checkout code - We grab the code from you git repository using the release version as the tag
  • Validate config - Configuration files within you git repository are parsed and checked for errors
  • Setup build - Placeholders for packages are created and fresh build locations created
  • Building - Your packages are created using the build files created above and other build tools
  • Uploading -Your packages are signed and uploaded to PKG deploy package repository based on the projects organisation and the format of the package
  • Uploaded - Everything is complete. You should be able to install you packages via APT or YUM

Triggering releases

To build packages for you we need to know when a new version of your code is ready to be released. This is known as a trigger.

The 2 different trigger types which you can read about in more detail below are

It is only possible to have one trigger type per project to ensure multiple releases are not created via different trigger types.

GitHub Webhook

This is the most simple trigger and requires no custom work.

GitHub Webhooks allows PKG Deploy to subscribe to certain events on GitHub.com. We register a webhook with GitHub to notify us whenever a new tag is pushed to GitHub.

New tags can be created in several ways:

git tag 1.0.0
git push origin 1.0.0

API endpoint

The API endpoint trigger allows you to trigger a release via an HTTP POST request. This is best used for CI/CD integrations as it allows for more flexibility when a new build is triggered.

The API Endpoint URL is:

http://app.pkdeploy.com/webhook/release

Each request must include:

  1. An API token header with the name api-token. The API token for each project can be found within the projects setting page
  2. The header content-type set to application/json
  3. A JSON request body which includes a JSON object with the keys organisation, repository and version
{
    "repository": "my-app",
    "organisation": "fakeorg",
    "version_tag": "1.0.0"
}

An example request in CURL:

curl -X POST \
    -H 'content-type: application/json' \
    -H 'api-token: bJ9F0yhHv9DqtLQvOPAbATduO1fakeqlITQaC9Ld3Rw' \
    -d '{
        "repository": "my-app",
        "organisation": "fakeorg",
        "version_tag": "1.0.0"
    }' \
    'http://app.pkdeploy.com/webhook/release' -v

This would trigger a build for version 1.0.0 of code repository/project my-app which is owned by fakeorg. The API token used must match the API token set in the projects settings.

Updating trigger type

The trigger type for a project can be updated any time from within project settings.

Release override

When a project is created by default, multiple packages can be created with the same version number. This can be turned off in project settings.

Making packages available

The last step of every release is to upload the package to a package repository.

Which package repository a package is uploaded to is based on the format set in the configuration file it's based on.

  • deb packages will be uploaded to a APT repository
  • rpm packages will be uploaded to a Yum repository

When you trigger a release the organisation for that project must have the correct type of package repository set up. If it does not the build will automatically fail on the Setup build step.

Version numbers

A large variety of version numbers are supported:

  • They may only contain alphanumeric and the characters . + - ~ (full stop, plus, hyphen, tilde)
  • As version numbers are taken from git tags, if a tag/version starts with a v, it will be removed from the version number. E.g. v1.0.0 will be read as version 1.0.0
  • All version numbers must start with a digit/number [0-9] E.g. 1.1.1 is valid but alpha.1 or a1.1 are not
  • Try to keep it simple, a more complex version number may not be understood by APT, YUM on DNF causing upgrade issues
  • We suggest using semantic versioning
  • The exact regex used to validate version numbers is ^[0-9]{1}[0-9a-zA-Z.+-~]+$