Graphic showing the GitLab logo, a stylised fox head

GitLab 14.1 added Helm charts to the software’s growing list of supported package repository formats. You can now store and share your charts using your GitLab projects, without a separate Helm registry.

Helm charts are a collection of Kubernetes YAML manifests distributed as a single package. They make it quicker and easier to deploy complex applications into your cluster. Using GitLab as a registry lets your team store charts alongside your code in an organization-managed repository.

Using the GitLab Helm Repository

Make sure your GitLab instance has been updated to version 14.1. If you’re using the hosted deployment, you’ll already have everything you need.

Prepare a simple Helm chart to push to your repository. Running helm create example will produce a new boilerplate chart called example if you’ve not got one available. The generated chart will be ready to push straight up to GitLab, without any modification.

image of enabling the GitLab package repositories for a project

Switch over to your GitLab instance. Either create a new project or find an existing one. Using the left sidebar, navigate to Packages & Registries > Package Registry within your project. If you don’t see these menus, head to Settings > General, expand the “Visibility, project features, permissions” heading, and enable the “Packages” toggle.

Adding the Repository to Helm

Now you’re ready to start using your package repository. You need to register it with your Helm client to begin with.

helm repo add 
    --username <username> 
    --password <token> 

The local repository will be named example-repo. Replace <username> with your GitLab username. The value of <token> should be a personal access token that’s got permission to push packages.

image of creating an API access token in GitLab

You can generate a new token by clicking your profile icon in the top-right of GitLab’s interface. Select “Preferences” from the menu, then “Access Tokens” from the left sidebar. Add a new access token with the api scope. The write_repository scope might look correct but won’t actually work; it only facilitates access using Git over HTTP, whereas Helm requires API integration.

image of finding the internal ID of a GitLab project

Substitute the <project> in your repository URL with the ID of the GitLab project you want to push to. You can find this on its homepage, underneath its name.

Pushing to the Repository

Once the repository’s been added, you can push any directory with a valid Helm chart up to your GitLab instance. It’s usually easiest to install the helm-push plugin which adds a native helm push command.

Package your chart if you haven’t already:

helm package example-chart

This will create a gzipped tar archive, example-chart.tgz, containing your chart.

Add the helm-push plugin:

helm plugin install

Finally, use the plugin to push your chart to your GitLab repository:

helm push example-chart.tgz example-repo

Back in the GitLab web interface, navigate to your project’s Packages & Registries > Package Registry screen. You should see your chart show up.

image of GitLab's Helm chart repository UI

Click the chart’s name to view its details. This screen lets you track the chart’s history, download package files, and view older releases. You can delete the chart with the “Delete” button situated in the top-right.

Using Charts in the Repository

With the chart in your repository, you can deploy it into your Kubernetes cluster. helm install commands should work straightaway:

# load the contents of repositories
helm repo update

# install the chart
helm install example-repo/example-chart

This will start a new chart deployment into your active cluster. Use the --kubeconfig and --namespace Helm flags if necessary to select an appropriate Kubernetes configuration file and specify the namespace to deploy into.

Accessing GitLab’s Repository in a CI Pipeline

As with its other package formats, GitLab’s Helm repository benefits from built-in integration with the software’s CI/CD system. Your pipelines will receive preset environment variables which simplify the chart publication process. You don’t need to set any custom CI variables to configure authentication.

Here’s an example pipeline which creates a chart and publishes it to your repository:

  - helm-publish

  stage: helm-publish
    name: alpine/helm:latest
    entrypoint: [""]
    - helm repo add --username $CI_REGISTRY_USER --password $CI_REGISTRY_PASSWORD my-repo $CI_REGISTRY
    - helm package my-chart
    - helm push my-chart.tgz my-repo

The $CI_REGISTRY variables are configured to let you push new packages into the registry. You can reuse them when authenticating to GitLab’s other repositories, such as npm, Composer, NuGet, and Maven.


GitLab now has an integrated Helm chart repository that lets you store your Kubernetes manifests alongside your code. Anyone with read access to the project’s repository will be able to add it to their Helm client and deploy charts into Kubernetes clusters.

When a new chart version is published, run helm repo update and then use helm upgrade to move deployed installations to the new release. You can manage chart versions from within GitLab and delete old releases which are wasting disk space.

Profile Photo for James Walker James Walker
James Walker is a contributor to How-To Geek DevOps. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes.
Read Full Bio »