Files

Publish a file

You can use two approaches to publish a file to your file 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 file to your file 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/file"

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 file 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 file source registry from the Registries page.

• $REGISTRY_WRITE_TOKEN is your API access token used to publish/upload files to your file 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 file source registry's OIDC policy. Learn more about these tokens in OIDC in Buildkite Package Registries.

• path/to/file is the full path to the file, including the file's name and extension if present. 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-custom-app.ipa from the current directory to the My files 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-files/packages \
  -H "Authorization: Bearer $REPLACE_WITH_YOUR_REGISTRY_WRITE_TOKEN" \
  -F "file=@my-custom-app.ipa"

Using the Buildkite CLI

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

bk package push registry-slug path/to/file

where:

• registry-slug is the slug of your file 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 file source registry from the Registries page.

• path/to/file is the full path to the file, including the file's name and extension if present. 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 packages 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 file's details

The file's details can be accessed from its source registry through the Releases (tab) section of your file source registry page. To do this:

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

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

• Installation (tab): the installation instructions.
• Details (tab): a list of checksum values for this file—MD5, SHA1, SHA256, and SHA512.
• About this version: a brief (metadata) description about the file.

• Details: details about:

  • the name of the file (typically the file name excluding any version details and extension).
  • the registry the file is located in.
  • the file's visibility (based on its registry's visibility)—whether the file is Private and requires authentication to access, or is publicly accessible.

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

• File size: the storage size (in bytes) of this file.

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

Downloading a file

The file can be downloaded from the file's details page. To do this:

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

Alternatively, a file can be downloaded via the command line using code snippet details provided on the file details page. To do this:

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