Helm

Buildkite Package Registries provides Helm registry support for distributing Helm charts. While this page is for standard Helm source registry publishing instructions, you can alternatively publish to an Helm OCI-based source registry.

Once your Helm source registry has been created, you can publish/upload charts (generated from helm package to create the package) to this registry via the relevant curl command presented on your Helm registry's details page.

To view and copy this curl command:

  1. Select Package Registries in the global navigation to access the Registries page.
  2. Select your Helm source registry on this page.
  3. Select the Publish Instructions tab and on the resulting page, use the copy icon at the top-right of the relevant code box to copy this curl command and run it (with the appropriate values) to publish the chart to this source registry.

This command provides:

  • The specific URL to publish a chart to your specific Helm source registry in Buildkite.
  • The API access token required to publish charts to this source registry.
  • The Helm chart (.tgz) to be published.

Publish a chart

You can use two approaches to publish a chart to your Helm 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 chart to your Helm 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/helm/chart.tgz"

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 Helm (OCI) 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 Helm (OCI) source registry from the Registries page.
  • $REGISTRY_WRITE_TOKEN is your API access token used to publish/upload charts to your Helm source registry. Ensure this access token has the Read Packages and Write Packages REST API scopes, which allows this token to publish charts and other package types to any source registry your user account has access to within your Buildkite organization. Alternatively, you can use an OIDC token that meets your Helm source registry's OIDC policy. Learn more about these tokens in OIDC in Buildkite Package Registries.
  • path/to/helm/chart.tgz is the full path to the Helm .tgz chart, 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-helm-chart-0.1.2.tgz from the current directory to the My Helm Charts 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-helm-charts/packages \
  -H "Authorization: Bearer $REPLACE_WITH_YOUR_REGISTRY_WRITE_TOKEN" \
  -F "file=@my-helm-chart-0.1.2.tgz"

Using the Buildkite CLI

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

bk package push registry-slug path/to/helm/chart.tgz

where:

  • registry-slug is the slug of your Helm 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 Helm source registry from the Registries page.
  • path/to/helm/chart.tgz is the full path to the Helm .tgz chart, 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 chart's details

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

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

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

  • Installation (tab): the installation instructions.

  • Details: details about:

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

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

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

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

Downloading a chart

A Helm (tgz) chart can be downloaded from the chart's details page. To do this:

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

Registry configuration

If your Helm source registry is private (the default configuration for source registries), configure your Helm registry locally for repeated use:

helm repo add {registry.slug} https://packages.buildkite.com/{org.slug}/{registry.slug}/helm \
  --username buildkite \
  --password registry-read-token

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 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.
  • registry-read-token is your API access token or registry token used to download charts from your Helm registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download charts and other package types from any registry your user account has access to within your Buildkite organization.

This step is not required for public Helm registries.

Chart installation

Use the following helm install command to download the chart:

helm install "chart-release" "{registry.slug}/{chart-name}" --version {version}

where:

  • {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.

  • chart-release is the unique release name for the Helm chart—this value must contain no . and be in lowercase. Learn more about chat name naming conventions in the Chart Names section of the General Conventions page in the Helm documentation.

  • chart-name is the name of your chart.

  • version (optional) the version of the chart to download. Without this option, the latest chart version is downloaded.