debian-mirror-gitlab/doc/user/packages/helm_repository/index.md

stage	group	info
Package	Package	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Helm charts in the Package Registry (FREE)

Introduced in GitLab 14.1.

WARNING: The Helm chart registry for GitLab is under development and isn't ready for production use due to limited functionality. This epic details the remaining work and timelines to make it production ready.

Publish Helm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency.

For documentation of the specific API endpoints that Helm package manager clients use, see the Helm API documentation.

Build a Helm package

Read more in the Helm documentation about these topics:

• Create your own Helm charts
• Package a Helm chart into a chart archive

Authenticate to the Helm repository

To authenticate to the Helm repository, you need either:

• A personal access token with the scope set to api.
• A deploy token with the scope set to read_package_registry, write_package_registry, or both.
• A CI/CD job token.

Publish a package

WARNING: The helm-push command is broken in Helm 3.7. For more information, see the open issue in the Chart Museum project.

NOTE: You can publish Helm charts with duplicate names or versions. If duplicates exist, GitLab always returns the chart with the latest version.

Once built, a chart can be uploaded to the desired channel with curl or helm-push:

• With curl:

  curl --request POST \
       --form 'chart=@mychart-0.1.0.tgz' \
       --user <username>:<access_token> \
       https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/api/<channel>/charts
  

  • <username>: the GitLab username or the deploy token username.
  • <access_token>: the personal access token or the deploy token.
  • <project_id>: the project ID (like 42) or the URL-encoded path of the project (like group%2Fproject).
  • <channel>: the name of the channel (like stable).

• With the helm-push plugin:

  helm repo add --username <username> --password <access_token> project-1 https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel>
  helm push mychart-0.1.0.tgz project-1
  

  • <username>: the GitLab username or the deploy token username.
  • <access_token>: the personal access token or the deploy token.
  • <project_id>: the project ID (like 42).
  • <channel>: the name of the channel (like stable).

Use CI/CD to publish a Helm package

To publish a Helm package automated through GitLab CI/CD, you can use CI_JOB_TOKEN in place of the personal access token in your commands.

For example:

image: curlimages/curl:latest
 
stages:
  - upload
 
upload:
  stage: upload
  script:
    - 'curl --request POST --user gitlab-ci-token:$CI_JOB_TOKEN --form "chart=@mychart-0.1.0.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/<channel>/charts"'

• <username>: the GitLab username or the deploy token username.
• <access_token>: the personal access token or the deploy token.
• <channel>: the name of the channel (like stable).

Install a package

NOTE: When requesting a package, GitLab considers only the 300 most recent packages created. For each package, only the most recent package file is returned.

To install the latest version of a chart, use the following command:

helm repo add --username <username> --password <access_token> project-1 https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel>
helm install my-release project-1/mychart

• <username>: the GitLab username or the deploy token username.
• <access_token>: the personal access token or the deploy token.
• <project_id>: the project ID (like 42).
• <channel>: the name of the channel (like stable).

If the repository has previously been added, you may need to run:

helm repo update

To update the Helm client with the most currently available charts.

See Using Helm for more information.

Troubleshooting

The chart is not visible in the Package Registry after uploading

Check the Sidekiq log for any related errors. If you see Validation failed: Version is invalid, it means that the version in your Chart.yaml file does not follow Helm Chart versioning specifications. To fix the error, use the correct version syntax and upload the chart again.

helm push results in an error

The helm push plugin is not yet supported in Helm 3.7. If you try to push a chart using helm push, it produces the following error:

Error: this feature has been marked as experimental and is not enabled by default. Please set HELM_EXPERIMENTAL_OCI=1 in your environment to use this feature

To continue to use the plugin, you can push an image using curl or downgrade your version of Helm.