GitLab Runner Helm Chart

This chart has been tested on Google Kubernetes Engine and Azure Kubernetes Service. Other Kubernetes installations may work as well, if not please open an issue.

The official way of deploying a GitLab Runner instance into your Kubernetes cluster is by using the gitlab-runner Helm chart.

This chart configures GitLab Runner to:

  • Run using the Kubernetes executor for GitLab Runner.
  • For each new job it receives from GitLab CI/CD, provision a new pod within the specified namespace to run it.


  • Your GitLab server’s API is reachable from the cluster.
  • Kubernetes 1.4+ with Beta APIs enabled.
  • The kubectl CLI installed locally and authenticated for the cluster.
  • The Helm client installed locally on your machine.

Installing GitLab Runner using the Helm Chart

Add the GitLab Helm repository:

helm repo add gitlab

If using Helm 2, you must also initialize Helm:

helm init

Once you have configured GitLab Runner in your values.yaml file, run the following:

# For Helm 2
helm install --namespace <NAMESPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner

# For Helm 3
helm install --namespace <NAMESPACE> gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner


  • <NAMESPACE> is the Kubernetes namespace where you want to install the GitLab Runner.
  • <CONFIG_VALUES_FILE> is the path to values file containing your custom configuration. See the Configuring GitLab Runner using the Helm Chart section to create it.

If you want to install a specific version of GitLab Runner Helm Chart, add --version <RUNNER_HELM_CHART_VERSION> to your helm install command.

Upgrading GitLab Runner using the Helm Chart

Before upgrading GitLab Runner, pause the runner in GitLab and ensure any jobs have completed. Pausing the runner prevents problems arising with the jobs, such as authorization errors when they complete.

Once your GitLab Runner Chart is installed, configuration changes and chart updates should be done using helm upgrade:

helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner


If you want to update to a specific version of GitLab Runner Helm Chart instead of the latest one, add --version <RUNNER_HELM_CHART_VERSION> to your helm upgrade command.

Check available GitLab Runner Helm Chart versions

Versions of Helm Chart and GitLab Runner do not follow the same versioning. Use the command below to get version mappings between Helm Chart and GitLab Runner:

# For Helm 2
helm search -l gitlab/gitlab-runner

# For Helm 3
helm search repo -l gitlab/gitlab-runner

Example of the output is shown below:

gitlab/gitlab-runner    0.14.0          12.8.0      GitLab Runner
gitlab/gitlab-runner    0.13.1          12.7.1      GitLab Runner
gitlab/gitlab-runner    0.13.0          12.7.0      GitLab Runner
gitlab/gitlab-runner    0.12.0          12.6.0      GitLab Runner
gitlab/gitlab-runner    0.11.0          12.5.0      GitLab Runner
gitlab/gitlab-runner    0.10.1          12.4.1      GitLab Runner
gitlab/gitlab-runner    0.10.0          12.4.0      GitLab Runner

Configuring GitLab Runner using the Helm Chart

Create a values.yaml file for your GitLab Runner configuration. See Helm docs for information on how your values file will override the defaults.

The default configuration can always be found in the values.yaml in the chart repository.

Required configuration

For GitLab Runner to function, your configuration file must specify the following:

  • gitlabUrl - the GitLab server full URL (e.g., to register the runner against.
  • runnerRegistrationToken - The registration token for adding new runners to GitLab. This must be retrieved from your GitLab instance. Set the token directly or store it in a secret.

Unless you need to specify any additional configuration, you are ready to install GitLab Runner.

Additional configuration

You can use a configuration template file to configure the runner. You can use the configuration template to configure any field on the runner, without having the Helm chart be aware of specific runner configuration options.

Here’s a snippet of the default settings found in the values.yaml file in the chart repository. It is important to note that, for the config: section, the format should be toml (<parameter> = <value> instead of <parameter>: <value>), as we are embedding config.toml in values.yaml.

  config: |
        image = "ubuntu:16.04"

The rest of the configuration is documented in the values.yaml.

Migrating to the new configuration template

Many of the fields accepted by the values.yaml file will be removed with the introduction of Helm Chart version 1.0. We recommend migrating away from them as soon as possible. These fields are marked with a DEPRECATED: comment above them.

All the configuration options supported by the Kubernetes executor are listed in the Kubernetes executor docs. For many of the fields, the old name in values.yaml is the same as the keyword. For some, you must rename them. For example, if you are using helpers to set CPU limits:

    cpuLimit: 200m

Now you can set them as helper_cpu_limit. Ensure you are using toml formatting (= rather than :) in the config: section:

  config: |
        image = "ubuntu:16.04"
        helper_cpu_limit = "200m"

## helpers:
##    cpuLimit: 200m
Make sure to comment or remove the old configuration values from your values.yaml file to avoid conflicts.

Using cache with configuration template

To use the cache with your configuration template, set the following variables in values.yaml:

  • runners.cache.secretName with the secret name for your object storage provider (s3access, gcsaccess, google-application-credentials, or azureaccess).
  • runners.config with the other settings for the cache. Use toml formatting.


For example, here is an example that configures S3 with static credentials:

  config: |
        image = "ubuntu:16.04"
          Type = "s3"
          Path = "runner"
          Shared = true
            ServerAddress = ""
            BucketName = "my_bucket_name"
            BucketLocation = "eu-west-1"
            Insecure = false
            AuthenticationType = "access-key"

      secretName: s3access

Next, create an s3access Kubernetes secret that contains accesskey and secretkey:

kubectl create secret generic s3access \
    --from-literal=accesskey="YourAccessKey" \

Google Cloud Storage (GCS)

Static credentials directly configured

The following example shows how to configure GCS with credentials with an access ID and a private key:

  config: |
        image = "ubuntu:16.04"
          Type = "gcs"
          Path = "runner"
          Shared = true
            BucketName = "runners-cache"

    secretName: gcsaccess

Next, create a gcsaccess Kubernetes secret that contains gcs-access-id and gcs-private-key:

kubectl create secret generic gcsaccess \
    --from-literal=gcs-access-id="YourAccessID" \