Debian

Publish a package

You can use two approaches to publish a deb package to your Debian source registry—curl or the Buildkite CLI.

Using curl

The following curl command (which you'll need to modify as required before submitting) describes the process above to publish a deb package to your Debian source registry:

curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{registry.slug}/packages \
  -H "Authorization: Bearer $REGISTRY_WRITE_TOKEN" \
  -F "file=@path/to/debian/package.deb"

where:

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your Debian source registry, which is the kebab-case version of this registry's name, and can be obtained after accessing Package Registries in the global navigation > your Debian source registry from the Registries page.

• $REGISTRY_WRITE_TOKEN is your API access token used to publish/upload packages to your Debian source registry. Ensure this access token has the Read Packages and Write Packages REST API scopes, which allows this token to publish packages to any source registry your user account has access to within your Buildkite organization. Alternatively, you can use an OIDC token that meets your Debian source registry's OIDC policy. Learn more about these tokens in OIDC in Buildkite Package Registries.

• path/to/debian/package.deb is the full path to the deb package, including the file's name. If the file is located in the same directory that this command is running from, then no path is required.

For example, to upload the file my-deb-package_1.0-2_amd64.deb from the current directory to the My Debian packages source registry in the My organization Buildkite organization, run the curl command:

curl -X POST https://api.buildkite.com/v2/packages/organizations/my-organization/registries/my-debian-packages/packages \
  -H "Authorization: Bearer $REPLACE_WITH_YOUR_REGISTRY_WRITE_TOKEN" \
  -F "file=@my-deb-package_1.0-2_amd64.deb"

Using the Buildkite CLI

The following Buildkite CLI command can also be used to publish a deb package to your Debian source registry from your local environment, once it has been installed and configured with an appropriate token:

bk package push registry-slug path/to/debian/package.deb

where:

• registry-slug is the slug of your Debian source registry, which is the kebab-case version of this registry's name, and can be obtained after accessing Package Registries in the global navigation > your Debian source registry from the Registries page.

• path/to/debian/package.deb is the full path to the deb package, including the file's name. If the file is located in the same directory that this command is running from, then no path is required.

Token usage with the Buildkite CLI

When configuring the Buildkite CLI with an API access token, ensure it has the Read Packages and Write Packages REST API scopes, which allows this token to publish files to any source registry your user account has access to within your Buildkite organization.

You can also override this configured token by passing in a different token value using the BUILDKITE_API_TOKEN environment variable when running the bk command:

BUILDKITE_API_TOKEN=$another_token_value bk package push organization-slug/registry-slug ./path/to/my/file.ext

If you have installed the Buildkite CLI to your self-hosted agents, you can also do the following:

• Use the bk command from within your Buildkite pipelines.

• Using the BUILDKITE_API_TOKEN environment variable, pass in a Buildkite OIDC token value generated from your agents that meets your source registry's OIDC policy. Learn more about these tokens in OIDC in Buildkite Package Registries.

Access a package's details

A Debian (deb) package's details can be accessed from this registry through the Releases (tab) section of your Debian source registry page. To do this:

1. Select Package Registries in the global navigation to access the Registries page.
2. Select your Debian source registry on this page.
3. On your Debian source registry page, select the package to display its details page.

The package's details page provides the following information in the following sections:

• Installation (tab): the installation instructions.
• Contents (tab, where available): a list of directories and files contained within the package.
• Details (tab): a list of checksum values for this package—MD5, SHA1, SHA256, and SHA512.
• About this version: a brief (metadata) description about the package.

• Details: details about:

  • the name of the package (typically the file name excluding any version details and extension).
  • the package version.
  • the source registry the package is located in.
  • the package's visibility (based on its registry's visibility)—whether the package is Private and requires authentication to access, or is publicly accessible.
  • the distribution name / version.
  • additional optional metadata contained within the package, such as a homepage, licenses, etc.

• Pushed: the date when the last package was uploaded to the source registry.

• Total files: the total number of files (and directories) within the package.

• Dependencies: the number of dependency packages required by this package.

• Package size: the storage size (in bytes) of this package.

• Downloads: the number of times this package has been downloaded.

Downloading a package

A Debian (deb) package can be downloaded from the package's details page. To do this:

1. Access the package's details.
2. Select Download.

Installing a package

A Debian package can be installed using code snippet details provided on the package's details page. To do this:

1. Access the package's details.
2. Ensure the Installation > Instructions section is displayed.
3. For each required command set in the relevant code snippets, copy the relevant code snippet, paste it into your terminal, and run it.

The following set of code snippets are descriptions of what each code snippet does and where applicable, its format:

Registry configuration

Update the apt database and ensure curl or gpg, or both, is installed:

apt update && apt install curl gpg -y

Install the registry signing key:

curl -fsSL "https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/{registry.slug}/gpgkey" | gpg --dearmor -o /etc/apt/keyrings/{org.slug}_{registry.slug}-archive-keyring.gpg

where:

• {registry.read.token} is your API access token or registry token used to download packages from your Debian registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding buildkite: and @ components are not required for registries that are publicly accessible.

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your registry, which is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your registry from the Registries page.

If your Debian source registry is private (the default configuration for source registries), stash the private registry credentials into apt's auth.conf.d directory:

echo "machine https://packages.buildkite.com/{org.slug}/{registry.slug}/ login buildkite password ${registry.read.token}" > /etc/apt/auth.conf.d/{org.slug}_{registry.slug}.conf; chmod 600 /etc/apt/auth.conf.d/{org.slug}_{registry.slug}.conf

Configure the source using the installed registry signing key:

echo -e "deb [signed-by=/etc/apt/keyrings/{org.slug}_{registry.slug}-archive-keyring.gpg] https://packages.buildkite.com/{org.slug}/{registry.slug}/any/ any main\ndeb-src [signed-by=/etc/apt/keyrings/{org.slug}_{registry.slug}-archive-keyring.gpg] https://packages.buildkite.com/{org.slug}/{registry.slug}/any/ any main" > /etc/apt/sources.list.d/buildkite-{org.slug}-{registry.slug}.list

Package installation

Update the apt database and use apt to install the package:

apt update && apt install package-name

where package-name is the name of your package.