Helm

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

Once your Helm 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 registry on this page.
  3. Select Publish a Helm Chart and in the resulting dialog, use the copy icon at the top-right of the code box to copy this curl command and run it to publish your chart to your Helm registry.

This command provides:

  • The specific URL to publish a package to your specific Helm registry in Buildkite.
  • The API access token required to publish packages to your Helm registry.
  • The Helm package (.tgz) to be published.

Publish a chart

The following curl command (which you'll need to modify as required before submitting) describes the process above to publish a Helm 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_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 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.
  • <path_to_file> is the full path required to the package file. If the file is located in the same directory that this command is running from, then no path is required.
  • $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 packages to any source registry your user account has access to within your Buildkite organization.

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"

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 registry is private (that is, the default registry configuration), 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 packages 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.