2021-09-30 23:02:18 +05:30
---
stage: Package
2023-01-13 00:05:48 +05:30
group: Package Registry
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-09-30 23:02:18 +05:30
---
# Helm charts in the Package Registry **(FREE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1.
2021-11-18 22:05:49 +05:30
WARNING:
The Helm chart registry for GitLab is under development and isn't ready for production use due to
limited functionality. This [epic ](https://gitlab.com/groups/gitlab-org/-/epics/6366 ) details the remaining
work and timelines to make it production ready.
2021-09-30 23:02:18 +05:30
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 ](../../../api/packages/helm.md ).
## Build a Helm package
2021-10-27 15:23:28 +05:30
Read more in the Helm documentation about these topics:
- [Create your own Helm charts ](https://helm.sh/docs/intro/using_helm/#creating-your-own-charts )
- [Package a Helm chart into a chart archive ](https://helm.sh/docs/helm/helm_package/#helm-package )
2021-09-30 23:02:18 +05:30
## Authenticate to the Helm repository
To authenticate to the Helm repository, you need either:
2023-04-23 21:23:45 +05:30
- A [personal access token ](../../../api/rest/index.md#personalprojectgroup-access-tokens ) with the scope set to `api` .
2021-11-11 11:23:49 +05:30
- A [deploy token ](../../project/deploy_tokens/index.md ) with the scope set to `read_package_registry` , `write_package_registry` , or both.
- A [CI/CD job token ](../../../ci/jobs/ci_job_token.md ).
2021-09-30 23:02:18 +05:30
## Publish a package
2021-10-27 15:23:28 +05:30
NOTE:
You can publish Helm charts with duplicate names or versions. If duplicates exist, GitLab always
returns the chart with the latest version.
2022-01-26 12:08:38 +05:30
Once built, a chart can be uploaded to the desired channel with `curl` or `helm cm-push` :
2021-09-30 23:02:18 +05:30
- With `curl` :
```shell
curl --request POST \
--form 'chart=@mychart-0.1.0.tgz' \
2021-11-11 11:23:49 +05:30
--user < username > :< access_token > \
https://gitlab.example.com/api/v4/projects/< project_id > /packages/helm/api/< channel > /charts
2021-09-30 23:02:18 +05:30
```
2021-11-11 11:23:49 +05:30
- `<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
2023-04-23 21:23:45 +05:30
[URL-encoded ](../../../api/rest/index.md#namespaced-path-encoding ) path of the project (like `group%2Fproject` ).
2021-11-11 11:23:49 +05:30
- `<channel>` : the name of the channel (like `stable` ).
2022-01-26 12:08:38 +05:30
- With the [`helm cm-push` ](https://github.com/chartmuseum/helm-push/#readme ) plugin:
2021-09-30 23:02:18 +05:30
```shell
2021-11-11 11:23:49 +05:30
helm repo add --username < username > --password < access_token > project-1 https://gitlab.example.com/api/v4/projects/< project_id > /packages/helm/< channel >
2022-01-26 12:08:38 +05:30
helm cm-push mychart-0.1.0.tgz project-1
2021-09-30 23:02:18 +05:30
```
2021-11-11 11:23:49 +05:30
- `<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` ).
2022-08-13 15:12:31 +05:30
### Release channels
2022-08-27 11:52:29 +05:30
You can publish Helm charts to channels in GitLab. Channels are a method you can use to differentiate Helm chart repositories.
2023-03-04 22:38:38 +05:30
For example, you can use `stable` and `devel` as channels to allow users to add the `stable` repository while `devel` charts are isolated.
2022-08-13 15:12:31 +05:30
2021-09-30 23:02:18 +05:30
## Use CI/CD to publish a Helm package
To publish a Helm package automated through [GitLab CI/CD ](../../../ci/index.md ), you can use
`CI_JOB_TOKEN` in place of the personal access token in your commands.
For example:
```yaml
image: curlimages/curl:latest
2022-07-23 23:45:48 +05:30
2021-09-30 23:02:18 +05:30
stages:
- upload
2022-07-23 23:45:48 +05:30
2021-09-30 23:02:18 +05:30
upload:
stage: upload
script:
2021-11-11 11:23:49 +05:30
- '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"'
2021-09-30 23:02:18 +05:30
```
2021-11-11 11:23:49 +05:30
- `<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` ).
2021-09-30 23:02:18 +05:30
## Install a package
2021-11-11 11:23:49 +05:30
NOTE:
2022-11-25 23:54:43 +05:30
When requesting a package, GitLab considers only the 1000 most recent packages created.
2021-11-11 11:23:49 +05:30
For each package, only the most recent package file is returned.
2021-09-30 23:02:18 +05:30
To install the latest version of a chart, use the following command:
```shell
2021-11-11 11:23:49 +05:30
helm repo add --username < username > --password < access_token > project-1 https://gitlab.example.com/api/v4/projects/< project_id > /packages/helm/< channel >
2021-09-30 23:02:18 +05:30
helm install my-release project-1/mychart
```
2021-11-11 11:23:49 +05:30
- `<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` ).
2021-11-18 22:05:49 +05:30
If the repository has previously been added, you may need to run:
2021-09-30 23:02:18 +05:30
```shell
helm repo update
```
To update the Helm client with the most currently available charts.
See [Using Helm ](https://helm.sh/docs/intro/using_helm/ ) for more information.
2021-10-27 15:23:28 +05:30
## Troubleshooting
### The chart is not visible in the Package Registry after uploading
2022-08-27 11:52:29 +05:30
Check the [Sidekiq log ](../../../administration/logs/index.md#sidekiqlog )
2021-10-27 15:23:28 +05:30
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 ](https://helm.sh/docs/topics/charts/#charts-and-versioning ).
To fix the error, use the correct version syntax and upload the chart again.
2021-11-18 22:05:49 +05:30
2023-01-13 00:05:48 +05:30
Support for providing better error messages for package processing errors in the UI is proposed in issue [330515 ](https://gitlab.com/gitlab-org/gitlab/-/issues/330515 ).
2021-11-18 22:05:49 +05:30
### `helm push` results in an error
2022-01-26 12:08:38 +05:30
Helm 3.7 introduced a breaking change for the `helm-push` plugin. You can update the
[Chart Museum plugin ](https://github.com/chartmuseum/helm-push/#readme )
to use `helm cm-push` .