Tutorial: Automate runner creation and registration All tiers All offerings
This tutorial describes how to automate runner creation and registration.
To automate runner creation and registration:
- Create a personal access token.
- Create a runner configuration.
- Automate GitLab Runner installation and registration.
- View runners with the same configuration.
Before you begin
- GitLab Runner must be installed on your GitLab instance.
- To create shared runners, you must be an administrator.
- To create group runners, you must be an administrator or have the Owner role for the group.
- To create project runners, you must be an administrator or have the Maintainer role for the project.
Create an access token
Create an access token so that you can use the REST API to create runners.
You can create:
- A personal access token to use with shared, group, and project runners.
- A group or project access token to use with group and project runners.
The access token is only visible once in the GitLab UI. After you leave the page, you no longer have access to the token. You should use a secrets management solution to store the token, like HashiCorp Vault or the Keeper Secrets Manager Terraform plugin.
Create a personal access token
- On the left sidebar, select your avatar.
- Select Edit profile.
- On the left sidebar, select Access Tokens.
- Select Add new token.
- Enter a name and expiry date for the token.
- The token expires on that date at midnight UTC.
- If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date.
- By default, this date can be a maximum of 365 days later than the current date.
- In the Select scopes section, select the create_runner checkbox.
- Select Create personal access token.
Create a project or group access token
To create a project access token:
- On the left sidebar, select Search or go to and find your project or group.
- Select Settings > Access Tokens.
- Select Add new token
- Enter a name. The token name is visible to any user with permissions to view the group or project.
- Enter an expiry date for the token.
- The token expires on that date at midnight UTC.
- If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date.
- By default, this date can be a maximum of 365 days later than the current date.
- An instance-wide maximum lifetime setting can limit the maximum allowable lifetime on self-managed instances.
- From the Select a role dropdown list:
- For the project access token, select Maintainer.
- For the group access token, select Owner.
- In the Select scopes section, select the create_runner checkbox.
- Select Create project access token.
Create a runner configuration
A runner configuration is where you configure runners to your requirements.
After you create a runner configuration, you receive a runner authentication
to register the runner. One or many runners can be linked to the
same configuration when these runners are registered with the same runner authentication
token. The runner configuration is stored in the config.toml
file.
To create a runner configuration, you can use:
- The GitLab REST API.
- The
gitlab_user_runner
Terraform resource.
With the GitLab REST API
Before you begin, you need:
- The URL for your GitLab instance. For example, if your project is hosted on
gitlab.example.com/yourname/yourproject
, your GitLab instance URL ishttps://gitlab.example.com
. - For group or project runners, the ID number of the group or project. The ID number is displayed in the project or group overview page, under the project or group name.
Use the access token in the POST /user/runners
REST endpoint to create a runner:
-
Use
curl
to invoke the endpoint to create a runner:Projectcurl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners" --data "runner_type=project_type" --data "project_id=<project_id>" --data "description=<your_runner_description>" --data "tag_list=<your_comma_separated_job_tags>" --header "PRIVATE-TOKEN: <project_access_token>"
Groupcurl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners" --data "runner_type=group_type" --data "group_id=<group_id>" --data "description=<your_runner_description>" --data "tag_list=<your_comma_separated_job_tags>" --header "PRIVATE-TOKEN: <group_access_token>"
Sharedcurl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners" --data "runner_type=instance_type" --data "description=<your_runner_description>" --data "tag_list=<your_comma_separated_job_tags>" --header "PRIVATE-TOKEN: <personal_access_token>"
-
Save the returned
token
value in a secure location or your secrets management solution. Thetoken
value is returned only once in the API response.
With the gitlab_user_runner
Terraform resource
To create the runner configuration with Terraform, use the
gitlab_user_runner
Terraform resource
from the GitLab Terraform provider.
Here’s an example configuration block:
resource "gitlab_user_runner" "example_runner" {
runner_type = "instance_type"
description = "my-runner"
tag_list = ["shell", "docker"]
}
Automate runner installation and registration
If you host the runner on a virtual machine instance in a public cloud, you can automate runner installation and registration.
After you create a runner and its configuration, you can use the same runner
authentication token to register multiple runners with the same configuration.
For example, you can deploy multiple shared runners with the same executor type
and job tags to the target compute host. Each runner registered with the same runner
authentication token has a unique system_id
, which GitLab Runner
generates randomly and stores in your local file system.
Here’s an example of an automation workflow you can use to register and deploy your runners to Google Compute Engine:
- Use Terraform infrastructure as code to install the runner application to a virtual machine hosted on Google Cloud Platform (GCP).
- In the GCP Terraform provider,
use the
metadata
key to add the runner authentication token to the runner configuration file on the GCP virtual machine. -
To register the runner with the target GitLab instance, use a
cloud-init
script populated from the GCP Terraform provider. Here’s an example:#!/bin/bash apt update curl --location "https://packages.gitlab.com/install/repositories/runner/ gitlab-runner/script.deb.sh" | bash GL_NAME=$(curl 169.254.169.254/computeMetadata/v1/instance/name --header "Metadata-Flavor:Google") GL_EXECUTOR=$(curl 169.254.169.254/computeMetadata/v1/instance/attributes/ gl_executor --header "Metadata-Flavor:Google") apt update apt install -y gitlab-runner gitlab-runner register --non-interactive --name="$GL_NAME" --url="https://gitlab.com" --token="$RUNNER_TOKEN" --request-concurrency="12" --executor="$GL_EXECUTOR" --docker-image="alpine:latest" systemctl restart gitlab-runner
View runners with the same configuration
Now that you’ve automated your runner creation and automation, you can view the runners that use the same configuration in the GitLab UI.
- On the left sidebar, at the bottom, select Admin Area.
- Select CI/CD > Runners.
- In the search box, enter the runner description or search the list of runners.
- To view the runners that use the same configuration, in the Details tab, next to Runners, select Show details.