1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
---
stage: none
group: Tutorials
info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
---
# Tutorial: Automate runner creation and registration **(FREE ALL)**
This tutorial describes how to automate runner creation and registration.
To automate runner creation and registration:
1. [Create a personal access token](#create-a-personal-access-token).
1. [Create a runner configuration](#create-a-runner-configuration).
1. [Automate GitLab Runner installation and registration](#automate-runner-installation-and-registration).
1. [View runners with the same configuration](#view-runners-with-the-same-configuration).
NOTE:
The instructions in this tutorial describe runner creation and registration
with runner authentication tokens, which have replaced the deprecated registration
method that uses registration tokens. For more information, see
[The new runner registration workflow](../../ci/runners/new_creation_workflow.md#the-new-runner-registration-workflow).
## Prerequisites
- 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
1. On the left sidebar, select your avatar.
1. Select **Edit profile**.
1. On the left sidebar, select **Access Tokens**.
1. Select **Add new token**.
1. 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.
1. In the **Select scopes** section, select the **create_runner** checkbox.
1. Select **Create personal access token**.
### Create a project or group access token
WARNING:
Project access tokens are treated as [internal users](../../development/internal_users.md).
If an internal user creates a project access token, that token is able to access
all projects that have visibility level set to [Internal](../../user/public_access.md).
To create a project access token:
1. On the left sidebar, select **Search or go to** and find your project or group.
1. Select **Settings > Access Tokens**.
1. Select **Add new token**
1. Enter a name. The token name is visible to any user with permissions to view
the group or project.
1. 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](../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens)
setting can limit the maximum allowable lifetime on self-managed instances.
1. From the **Select a role** dropdown list:
- For the project access token, select **Maintainer**.
- For the group access token, select **Owner**.
1. In the **Select scopes** section, select the **create_runner** checkbox.
1. 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
Prerequisites:
- The URL for your GitLab instance. For example, if your project is hosted on
`gitlab.example.com/yourname/yourproject`, your GitLab instance URL is
`https://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`](../../api/users.md#create-a-runner)
REST endpoint to create a runner:
1. Use `curl` to invoke the endpoint to create a runner:
::Tabs
:::TabTitle Project
```shell
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>"
```
:::TabTitle Group
```shell
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
```shell
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
1. Save the returned `token` value in a secure location or your secrets management
solution. 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 the
[`gitlab_user_runner` Terraform resource](https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/blob/main/docs/resources/user_runner.md?ref_type=heads)
from the [GitLab Terraform provider](https://gitlab.com/gitlab-org/terraform-provider-gitlab).
Here's an example configuration block:
```terraform
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:
1. Use [Terraform infrastructure as code](../../user/infrastructure/iac/index.md)
to install the runner application to a virtual machine hosted on Google Cloud
Platform (GCP).
1. In the [GCP Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance),
use the `metadata` key to add the runner authentication token to the runner
configuration file on the GCP virtual machine.
1. To register the runner with the target GitLab instance, use a `cloud-init` script
populated from the GCP Terraform provider. Here's an example:
```shell
#!/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.
1. On the left sidebar, select **Search or go to**.
1. Select **Admin Area**.
1. On the left sidebar, select **CI/CD > Runners**.
1. In the search box, enter the runner description or search the list of runners.
1. To view the runners that use the same configuration, in the **Details** tab,
next to **Runners**, select **Show details**.
|
