PKG Deploy

Docs

Projects

A project is the PKG Deploy representation of a code repository in GitHub.

Adding a project to PKG Deploy lets us know you want to start building packages for this code repository

If a project has already been created for a code repository that you are interested in you can follow it. This will ensure you get all of the latest notifications such as when a release is successfully created.

Setting up a project

One of the first things you need to do to start building packages is to set up a project.

  1. Click on the Add project at the bottom of the left navigation or click on the projects navigation item and select Add project top right
  2. Select the code repository you want to set up and click Setup project
  3. On the Setup project page select if you would like to use a Github Webhook or API endpoint to trigger releases. See triggers for more info, but don't worry, this can be updated later
  4. (Optional) If you have not created a PKG Deploy package repository yet you will be asked to create one now as it is not possible to build packages without one. To skip this navigate to any other page.

Once a project has been set up we will add a read-only Deploy Key to the repository in Github. This key is needed so that we can read the code within your repository.

Release triggers

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

PKG Deploy supports 2 different trigger types:

  • Github webhook - Direct integration with Github. New releases are triggered when a release is created via the Github UI or when a new tag is pushed
  • API endpoint - A HTTP POST request with release details. A git tag must be created before the API call is made

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

Project access

It is only possible to add, view and follow projects for the repositories you have been granted access to in Github. Access to specific releases within a project is controlled in the same way.

There is currently no permissions to control which users can modify settings etc, we instead send notifications each time a setting is updated.

Please get in touch via the contact page if this is a problem.

Following a project

If a project that you are interested in has already been set up in PKG Deploy then you can select to follow it. Much like setting up the project yourself this will add the project of interest to your projects page and ensure you receive all notifications in relation to it.

To follow a project:

  1. Click on the Add project button bottom left of the left navigation or top right on the main projects page.
  2. Next to the project click the Follow project button

Unfollowing a project

If you are no longer interested in a project you can select to unfollow it. This will stop us from sending you any notifications about the project. The project will no longer appear in your projects list.

You will not lose access to the project as it will still be available directly via the URL.

To unfollow a project:

  1. Click on the Projects link in the left navigation
  2. In the project list select the project you want to unfollow
  3. Click on the settings cog top right just under the user and notification navigation items
  4. Click the 'Unsubscribe' button near the top of the page

Project settings

The settings page for a project can be found by going to the project's page and clicking on the settings cog top right, just under the user and notification navigation items

Updating trigger type

How a release is triggered for a project can be updated at any time. Simply select the trigger type you want in the settings page and click Update below.

Switching from Github webhook to API endpoint will cause the Github webhook to be deleted. If you switch to a Github webhook we will create a new webhook within Github.

Release version override

By default, multiple releases with the same version can be created per project as each version has a version count appended to it. This is supported by both APT and YUM.

For example, if release 1.0.0 is triggered the version of the package will be set to 1.0.0-1. If a second release for version 1.0.0 is triggered the package version will be set to 1.0.0-2

If both packages exist within the package repository and a user requests version 1.0.0 they will receive package 1.0.0-2

It is possible to stop this behaviour by setting Allow releases with the same version to be created? to No and clicking Update. This will cause the trigger endpoint to return a 409 Conflict HTTP error if a release already exists with the same version number.

Rolling API tokens

Both the GitHub and API trigger types are secured by API tokens to ensure requests are authorised on behalf of the projects owner.

As stated within the security documentation, if you believe an API token has been compromised you should update a projects API token.

Create new deploy key

Deploy keys are used to give us read access to your repository. If this key is removed we will no longer be able to read the code in your repository and create packages for you.

If for some reason the deploy key we create in Github is removed it can be recreated by clicking Create new deploy key.

Disabling a project

If you no longer want PKG Deploy to create packages for a project you can disable a project.

This will only stop new releases from getting created and remove our access to the Github repository via the deploy key. It will not remove old data or any packages from any package repositories.

To disable a project scroll to the bottom of the settings page and click on the Disable project button.