- Configure GitLab Runner with the Helm chart
- Install GitLab Runner with the Helm chart
- Upgrade GitLab Runner with the Helm chart
- Uninstall GitLab Runner with the Helm chart
GitLab Runner Helm chart
The GitLab Runner Helm chart is the official way to deploy a GitLab Runner instance into your Kubernetes cluster. This chart configures GitLab Runner to:
- Run using the Kubernetes executor for GitLab Runner.
- Provision a new pod in the specified namespace for each new CI/CD job.
Configure GitLab Runner with the Helm chart
Store your GitLab Runner configuration changes in values.yaml
. For help configuring this file, see:
- The default
values.yaml
configuration in the chart repository. - The Helm documentation for Values Files, which explains how your values file overrides the default values.
For GitLab Runner to run properly, you must set these values in your configuration file:
-
gitlabUrl
: The full URL of the GitLab server (likehttps://gitlab.example.com
) to register the runner against. -
rbac: { create: true }
: Create RBAC (role-based access control) rules for the GitLab Runner to create pods to run jobs in.- Prefer to use an existing
serviceAccount
? You should also setrbac: { serviceAccountName: "SERVICE_ACCOUNT_NAME" }
. - To learn about the minimal permissions the
serviceAccount
requires, see Configure runner API permissions.
- Prefer to use an existing
-
runnerToken
: The authentication token obtained when you create a runner in the GitLab UI.- Set this token directly or store it in a secret.
More optional configuration settings are available.
You’re now ready to install GitLab Runner!
Install GitLab Runner with the Helm chart
Prerequisites:
- Your GitLab server’s API is reachable from the cluster.
- Kubernetes 1.4 or later, with beta APIs enabled.
- The
kubectl
CLI is installed locally, and authenticated for the cluster. - The Helm client is installed locally on your machine.
- You’ve set all required values in
values.yaml
.
To install GitLab Runner from the Helm chart:
-
Add the GitLab Helm repository:
helm repo add gitlab https://charts.gitlab.io
- If you use Helm 2, initialize Helm with
helm init
. -
Check which GitLab Runner versions you have access to:
helm search repo -l gitlab/gitlab-runner
-
If you can’t access the latest versions of GitLab Runner, update the chart with this command:
helm repo update gitlab
-
After you configure GitLab Runner in your
values.yaml
file, run this command, changing parameters as needed:# 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>
: The Kubernetes namespace where you want to install the GitLab Runner. -
<CONFIG_VALUES_FILE>
: The path to values file containing your custom configuration. To create it, see Configure GitLab Runner with the Helm chart. - To install a specific version of the GitLab Runner Helm chart, add
--version <RUNNER_HELM_CHART_VERSION>
to yourhelm install
command. You can install any version of the chart, but more recentvalues.yml
might be incompatible with older versions of the chart.
-
Check available GitLab Runner Helm chart versions
Helm charts and GitLab Runner do not follow the same versioning. To see version mappings between the two, run the command for your version of Helm:
# For Helm 2
helm search -l gitlab/gitlab-runner
# For Helm 3
helm search repo -l gitlab/gitlab-runner
An example of the output:
NAME CHART VERSION APP VERSION DESCRIPTION
gitlab/gitlab-runner 0.64.0 16.11.0 GitLab Runner
gitlab/gitlab-runner 0.63.0 16.10.0 GitLab Runner
gitlab/gitlab-runner 0.62.1 16.9.1 GitLab Runner
gitlab/gitlab-runner 0.62.0 16.9.0 GitLab Runner
gitlab/gitlab-runner 0.61.3 16.8.1 GitLab Runner
gitlab/gitlab-runner 0.61.2 16.8.0 GitLab Runner
...
Upgrade GitLab Runner with the Helm chart
Prerequisites:
- You’ve installed your GitLab Runner chart.
- You’ve paused the runner in GitLab. This prevents problems arising with the jobs, such as authorization errors when they complete.
- You’ve ensured all jobs have completed.
To change your configuration or update charts, use helm upgrade
, changing parameters as needed:
helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner
-
<NAMESPACE>
: The Kubernetes namespace where you’ve installed GitLab Runner. -
<CONFIG_VALUES_FILE>
: The path to the values file containing your custom configuration. To create it, see Configure GitLab Runner with the Helm chart. -
<RELEASE-NAME>
: The name you gave the chart when you installed it. In the installation section, the example named itgitlab-runner
. - To update to a specific version of the GitLab Runner Helm chart, rather than the latest one, add
--version <RUNNER_HELM_CHART_VERSION>
to yourhelm upgrade
command.
Uninstall GitLab Runner with the Helm chart
To uninstall GitLab Runner:
- Pause the runner in GitLab, and ensure any jobs have completed. This prevents job-related problems, such as authorization errors on completion.
-
Run, this command, modifying it as needed:
helm delete --namespace <NAMESPACE> <RELEASE-NAME>
-
<NAMESPACE>
is the Kubernetes namespace where GitLab Runner is installed. -
<RELEASE-NAME>
is the name you gave the chart when you installed it. In the installation section of this page, we called itgitlab-runner
.
-