Install GitLab Runner with a cluster management project
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Assuming you already have a project created from a
management project template, to install GitLab Runner you should
uncomment this line from your helmfile.yaml
:
- path: applications/gitlab-runner/helmfile.yaml
GitLab Runner is installed by default into the gitlab-managed-apps
namespace of your cluster.
Required variables
For GitLab Runner to function, you must specify the following in your
applications/gitlab-runner/values.yaml.gotmpl
file:
gitlabUrl
: The GitLab server full URL (for example,https://gitlab.example.com
) to register the Runner against.Runner token: This must be retrieved from your GitLab instance. You can use either of the following tokens:
runnerToken
: The runner authentication token for the runner configuration created in the GitLab UI.runnerRegistrationToken
(deprecated in GitLab 15.6 and scheduled to be removed in GitLab 17.0): The registration token for used to add new runners to GitLab.
These values can be specified using CI/CD variables:
CI_SERVER_URL
is used forgitlabUrl
. If you are using GitLab.com, you don’t need to set this variable.GITLAB_RUNNER_TOKEN
is used forrunnerToken
.GITLAB_RUNNER_REGISTRATION_TOKEN
is used forrunnerRegistrationToken
(deprecated).
The methods of specifying these values are mutually exclusive. You can either:
- Specify the variables
GITLAB_RUNNER_TOKEN
andCI_SERVER_URL
as CI variables (recommended). - Provide values for
runnerToken:
andgitlabUrl:
inapplications/gitlab-runner/values.yaml.gotmpl
.
The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a protected variable and masked variable and do not commit them to the Git repository in the values.yaml.gotmpl
file.
You can customize the installation of GitLab Runner by defining
applications/gitlab-runner/values.yaml.gotmpl
file in your cluster
management project. Refer to the
chart for the
available configuration options.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support