Helm charts in the package registry All tiers All offerings Beta
Introduced in GitLab 14.1.
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:
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
Once built, a chart can be uploaded to the desired channel with curl
or helm cm-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 (like42
) or the URL-encoded path of the project (likegroup%2Fproject
). -
<channel>
: the name of the channel (likestable
).
-
-
With the
helm cm-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 cm-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 (like42
). -
<channel>
: the name of the channel (likestable
).
-
Release channels
You can publish Helm charts to channels in GitLab. Channels are a method you can use to differentiate Helm chart repositories.
For example, you can use stable
and devel
as channels to allow users to add the stable
repository while devel
charts are isolated.
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 (likestable
).
Install a package
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 (like42
). -
<channel>
: the name of the channel (likestable
).
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.
Support for providing better error messages for package processing errors in the UI is proposed in issue 330515.
helm push
results in an error
Helm 3.7 introduced a breaking change for the helm-push
plugin. You can update the
Chart Museum plugin
to use helm cm-push
.