Index · Automate runner creation · Tutorials · Help · GitLab (2024)

DETAILS:Tier: Free, Premium, UltimateOffering: GitLab.com, Self-managed, GitLab Dedicated

This tutorial describes how to automate runner creation and registration.

To automate runner creation and registration:

1. Create a personal access token.
2. Create a runner configuration.
3. Automate GitLab Runner installation and registration.
4. View runners with the same configuration.

NOTE:The instructions in this tutorial describe runner creation and registrationwith runner authentication tokens, which have replaced the deprecated registrationmethod that uses registration tokens. For more information, seeThe new runner registration workflow.

Before you begin

• GitLab Runner must be installed on your GitLab instance.
• To create instance 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 solutionto store the token, like HashiCorp Vault or the Keeper Secrets Manager Terraform plugin.

Create a personal access token

1. On the left sidebar, select your avatar.
2. Select Edit profile.
3. On the left sidebar, select Access Tokens.
4. Select Add new token.
5. 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.
6. In the Select scopes section, select the create_runner checkbox.
7. Select Create personal access token.

Create a project or group access token

WARNING:Project access tokens are treated as internal users.If an internal user creates a project access token, that token is able to accessall projects that have visibility level set to Internal.

To create a project access token:

1. On the left sidebar, select Search or go to and find your project or group.
2. Select Settings > Access Tokens.
3. Select Add new token
4. Enter a name. The token name is visible to any user with permissions to viewthe group or project.
5. 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 setto 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 lifetimesetting can limit the maximum allowable lifetime on self-managed instances.
6. From the Select a role dropdown list:
   • For the project access token, select Maintainer.
   • For the group access token, select Owner.
7. In the Select scopes section, select the create_runner checkbox.
8. 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 authenticationto register the runner. One or many runners can be linked to thesame configuration when these runners are registered with the same runner authenticationtoken. 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 ongitlab.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 numberis displayed in the project or group overview page, under the project or groupname.

Use the access token in the POST /user/runnersREST endpoint to create a runner:

1. Use curl to invoke the endpoint to create a runner:

   ::Tabs

   :::TabTitle Project

   curl --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>"

   See Also

   PETSc on the Research Computing Clusters

   :::TabTitle Group

   curl --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>"

   :::TabTitle Shared

   curl --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>"

   ::EndTabs

2. Save the returned token value in a secure location or your secrets managementsolution. The token value is returned only once in the API response.

With the gitlab_user_runner Terraform resource

To create the runner configuration with Terraform, use thegitlab_user_runner Terraform resourcefrom 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 automaterunner installation and registration.

After you create a runner and its configuration, you can use the same runnerauthentication token to register multiple runners with the same configuration.For example, you can deploy multiple instance runners with the same executor typeand job tags to the target compute host. Each runner registered with the same runnerauthentication token has a unique system_id, which GitLab Runnergenerates randomly and stores in your local file system.

Here's an example of an automation workflow you can use to register and deploy yourrunners to Google Compute Engine:

1. Use Terraform infrastructure as codeto install the runner application to a virtual machine hosted on Google CloudPlatform (GCP).

2. In the GCP Terraform provider,use the metadata key to add the runner authentication token to the runnerconfiguration file on the GCP virtual machine.

3. To register the runner with the target GitLab instance, use a cloud-init scriptpopulated from the GCP Terraform provider. Here's an example:

   #!/bin/bashapt updatecurl --location "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bashGL_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 updateapt install -y gitlab-runnergitlab-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 viewthe runners that use the same configuration in the GitLab UI.

1. On the left sidebar, at the bottom, select Admin Area.
2. Select CI/CD > Runners.
3. In the search box, enter the runner description or search the list of runners.
4. To view the runners that use the same configuration, in the Details tab,next to Runners, select Show details.