README.md 15.2 KB
Newer Older
1
# Configuring GitLab Runners
2

3 4 5
In GitLab CI, Runners run the code defined in [`.gitlab-ci.yml`](../yaml/README.md).
They are isolated (virtual) machines that pick up jobs through the coordinator
API of GitLab CI.
6

7 8
A Runner can be specific to a certain project or serve any project
in GitLab CI. A Runner that serves all projects is called a shared Runner.
9

10
Ideally, the GitLab Runner should not be installed on the same machine as GitLab.
11
Read the [requirements documentation](../../install/requirements.md#gitlab-runner)
12 13
for more information.

14
## Shared, specific and group Runners
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

After [installing the Runner][install], you can either register it as shared or
specific. You can only register a shared Runner if you have admin access to
the GitLab instance. The main differences between a shared and a specific Runner
are:

- **Shared Runners** are useful for jobs that have similar requirements,
  between multiple projects. Rather than having multiple Runners idling for
  many projects, you can have a single or a small number of Runners that handle
  multiple projects. This makes it easier to maintain and update them.
  Shared Runners process jobs using a [fair usage queue](#how-shared-runners-pick-jobs).
  In contrast to specific Runners that use a FIFO queue, this prevents
  cases where projects create hundreds of jobs which can lead to eating all
  available shared Runners resources.
- **Specific Runners** are useful for jobs that have special requirements or for
  projects with a specific demand. If a job has certain requirements, you can set
  up the specific Runner with this in mind, while not having to do this for all
  Runners. For example, if you want to deploy a certain project, you can setup
  a specific Runner to have the right credentials for this. The [usage of tags](#using-tags)
  may be useful in this case. Specific Runners process jobs using a [FIFO] queue.
35
- **Group Runners** are useful when you have multiple projects under one group
36
  and would like all projects to have access to a set of Runners. Group Runners
37
  process jobs using a [FIFO] queue.
38 39 40

A Runner that is specific only runs for the specified project(s). A shared Runner
can run jobs for every project that has enabled the option **Allow shared Runners**
41
under **Settings > CI/CD**.
42 43 44 45

Projects with high demand of CI activity can also benefit from using specific
Runners. By having dedicated Runners you are guaranteed that the Runner is not
being held up by another project's jobs.
46

47 48 49
You can set up a specific Runner to be used by multiple projects. The difference
with a shared Runner is that you have to enable each project explicitly for
the Runner to be able to run its jobs.
50

51
Specific Runners do not get shared with forked projects automatically.
52 53
A fork does copy the CI settings (jobs, allow shared, etc) of the cloned
repository.
54

55
## Registering a shared Runner
56

57
You can only register a shared Runner if you are an admin of the GitLab instance.
58

59
1. Grab the shared-Runner token on the `admin/runners` page
60

61
    ![Shared Runners admin area](img/shared_runners_admin.png)
62

63
1. [Register the Runner][register]
64

65 66
Shared Runners are enabled by default as of GitLab 8.2, but can be disabled
with the **Disable shared Runners** button which is present under each project's
67
**Settings ➔ CI/CD** page. Previous versions of GitLab defaulted shared
68
Runners to disabled.
69

70
## Registering a specific Runner
71

Dylan Griffith's avatar
Dylan Griffith committed
72
Registering a specific Runner can be done in two ways:
73

74 75
1. Creating a Runner with the project registration token
1. Converting a shared Runner into a specific Runner (one-way, admin only)
76

77
### Registering a specific Runner with a project registration token
78

79
To create a specific Runner without having admin rights to the GitLab instance,
80
visit the project you want to make the Runner work for in GitLab:
81

82
1. Go to **Settings > CI/CD** to obtain the token
83
1. [Register the Runner][register]
84

85 86
## Registering a group Runner

Mark Chao's avatar
Mark Chao committed
87
Creating a group Runner requires Maintainer permissions for the group. To create a
88 89 90 91 92
group Runner visit the group you want to make the Runner work for in GitLab:

1. Go to **Settings > CI/CD** to obtain the token
1. [Register the Runner][register]

93
### Making an existing shared Runner specific
94

95 96 97
If you are an admin on your GitLab instance, you can turn any shared Runner into
a specific one, but not the other way around. Keep in mind that this is a one
way transition.
98

99
1. Go to the Runners in the admin area **Overview > Runners** (`/admin/runners`)
100 101 102
   and find your Runner
1. Enable any projects under **Restrict projects for this Runner** to be used
   with the Runner
103

104 105 106
From now on, the shared Runner will be specific to those projects.

## Locking a specific Runner from being enabled for other projects
107

108 109
You can configure a Runner to assign it exclusively to a project. When a
Runner is locked this way, it can no longer be enabled for other projects.
110 111 112 113 114
This setting can be enabled the first time you [register a Runner][register] and
can be changed afterwards under each Runner's settings.

To lock/unlock a Runner:

115
1. Visit your project's **Settings > CI/CD**
116 117 118 119
1. Find the Runner you wish to lock/unlock and make sure it's enabled
1. Click the pencil button
1. Check the **Lock to current projects** option
1. Click **Save changes** for the changes to take effect
120

121 122
## Assigning a Runner to another project

Mark Chao's avatar
Mark Chao committed
123
If you are Maintainer on a project where a specific Runner is assigned to, and the
124
Runner is not [locked only to that project](#locking-a-specific-runner-from-being-enabled-for-other-projects),
Mark Chao's avatar
Mark Chao committed
125
you can enable the Runner also on any other project where you have Maintainer permissions.
126 127 128

To enable/disable a Runner in your project:

129
1. Visit your project's **Settings > CI/CD**
130 131 132 133 134
1. Find the Runner you wish to enable/disable
1. Click **Enable for this project** or **Disable for this project**

> **Note**:
Consider that if you don't lock your specific Runner to a specific project, any
Mark Chao's avatar
Mark Chao committed
135
user with Maintainer role in you project can assign your Runner to another arbitrary
136 137
project without requiring your authorization, so use it with caution.

138 139 140 141 142 143 144
An admin can enable/disable a specific Runner for projects:

1. Navigate to **Admin > Runners**
2. Find the Runner you wish to enable/disable
3. Click edit on the Runner
4. Click **Enable** or **Disable** on the project

Shinya Maeda's avatar
Shinya Maeda committed
145
## Protected Runners
Shinya Maeda's avatar
Shinya Maeda committed
146

147
>
Shinya Maeda's avatar
Shinya Maeda committed
148 149
[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194)
in GitLab 10.0.
Shinya Maeda's avatar
Shinya Maeda committed
150

Shinya Maeda's avatar
Shinya Maeda committed
151 152 153
You can protect Runners from revealing sensitive information.
Whenever a Runner is protected, the Runner picks only jobs created on
[protected branches] or [protected tags], and ignores other jobs.
Shinya Maeda's avatar
Shinya Maeda committed
154

Shinya Maeda's avatar
Shinya Maeda committed
155
To protect/unprotect Runners:
Shinya Maeda's avatar
Shinya Maeda committed
156

157
1. Visit your project's **Settings > CI/CD**
Shinya Maeda's avatar
Shinya Maeda committed
158 159
1. Find a Runner you want to protect/unprotect and make sure it's enabled
1. Click the pencil button besides the Runner name
Shinya Maeda's avatar
Shinya Maeda committed
160 161 162
1. Check the **Protected** option
1. Click **Save changes** for the changes to take effect

Shinya Maeda's avatar
Shinya Maeda committed
163
![specific Runners edit icon](img/protected_runners_check_box.png)
Shinya Maeda's avatar
Shinya Maeda committed
164

165 166
## Manually clearing the Runners cache

167
Read [clearing the cache](../caching/index.md#clearing-the-cache).
168

169
## How shared Runners pick jobs
170

171 172 173
Shared Runners abide to a process queue we call fair usage. The fair usage
algorithm tries to assign jobs to shared Runners from projects that have the
lowest number of jobs currently running on shared Runners.
174

175
**Example 1**
176

177
We have following jobs in queue:
178

179 180 181 182 183 184
- Job 1 for Project 1
- Job 2 for Project 1
- Job 3 for Project 1
- Job 4 for Project 2
- Job 5 for Project 2
- Job 6 for Project 3
185 186 187

With the fair usage algorithm jobs are assigned in following order:

188 189 190 191 192 193
1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (i.e. all projects)
1. Job 4 is next, because 4 is now the lowest job number from projects with no running jobs (Project 1 has a job running)
1. Job 6 is next, because 6 is now the lowest job number from projects with no running jobs (Projects 1 and 2 have jobs running)
1. Job 2 is next, because, of projects with the lowest number of jobs running (each has 1), it is the lowest job number
1. Job 5 is next, because Project 1 now has 2 jobs running, and between Projects 2 and 3, Job 5 is the lowest remaining job number
1. Lastly we choose Job 3... because it's the only job left
194 195 196 197 198 199 200

---

**Example 2**

We have following jobs in queue:

201 202 203 204 205 206
- Job 1 for project 1
- Job 2 for project 1
- Job 3 for project 1
- Job 4 for project 2
- Job 5 for project 2
- Job 6 for project 3
207 208 209

With the fair usage algorithm jobs are assigned in following order:

210
1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (i.e. all projects)
211
1. We finish job 1
212 213
1. Job 2 is next, because, having finished Job 1, all projects have 0 jobs running again, and 2 is the lowest available job number
1. Job 4 is next, because with Project 1 running a job, 4 is the lowest number from projects running no jobs (Projects 2 and 3)
214
1. We finish job 4
215 216 217
1. Job 5 is next, because having finished Job 4, Project 2 has no jobs running again
1. Job 6 is next, because Project 3 is the only project left with no running jobs
1. Lastly we choose Job 3... because, again, it's the only job left (who says 1 is the loneliest number?)
218 219

## Using shared Runners effectively
220

221
If you are planning to use shared Runners, there are several things you
222 223
should keep in mind.

224
### Using tags
225

226
You must setup a Runner to be able to run all the different types of jobs
227 228 229 230
that it may encounter on the projects it's shared over. This would be
problematic for large amounts of projects, if it wasn't for tags.

By tagging a Runner for the types of jobs it can handle, you can make sure
231
shared Runners will [only run the jobs they are equipped to run](../yaml/README.md#tags).
232

233
For instance, at GitLab we have Runners tagged with "rails" if they contain
234 235
the appropriate dependencies to run Rails test suites.

236
### Preventing Runners with tags from picking jobs without tags
237

238 239 240
You can configure a Runner to prevent it from picking
[jobs with tags](../yaml/README.md#tags) when the Runner does not have tags
assigned. This setting can be enabled the first
241 242 243 244 245
time you [register a Runner][register] and can be changed afterwards under
each Runner's settings.

To make a Runner pick tagged/untagged jobs:

246
1. Visit your project's **Settings ➔ CI/CD**
247 248 249 250
1. Find the Runner you wish and make sure it's enabled
1. Click the pencil button
1. Check the **Run untagged jobs** option
1. Click **Save changes** for the changes to take effect
251

Tomasz Maczukin's avatar
Tomasz Maczukin committed
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283
### Setting maximum job timeout for a Runner

For each Runner you can specify a _maximum job timeout_. Such timeout,
if smaller than [project defined timeout], will take the precedence. This
feature can be used to prevent Shared Runner from being appropriated
by a project by setting a ridiculous big timeout (e.g. one week).

When not configured, Runner will not override project timeout.

How this feature will work:

**Example 1 - Runner timeout bigger than project timeout**

1. You set the _maximum job timeout_ for a Runner to 24 hours
1. You set the _CI/CD Timeout_ for a project to **2 hours**
1. You start a job
1. The job, if running longer, will be timeouted after **2 hours**

**Example 2 - Runner timeout not configured**

1. You remove the _maximum job timeout_ configuration from a Runner
1. You set the _CI/CD Timeout_ for a project to **2 hours**
1. You start a job
1. The job, if running longer, will be timeouted after **2 hours**

**Example 3 - Runner timeout smaller than project timeout**

1. You set the _maximum job timeout_ for a Runner to **30 minutes**
1. You set the _CI/CD Timeout_ for a project to 2 hours
1. You start a job
1. The job, if running longer, will be timeouted after **30 minutes**

284
### Be careful with sensitive information
285

286 287
With some [Runner Executors](https://docs.gitlab.com/runner/executors/README.html),
if you can run a job on the Runner, you can get access to any code it runs
288
and get the token of the Runner. With shared Runners, this means that anyone
289 290
that runs jobs on the Runner, can access anyone else's code that runs on the
Runner.
291

292 293
In addition, because you can get access to the Runner token, it is possible
to create a clone of a Runner and submit false jobs, for example.
294

295
The above is easily avoided by restricting the usage of shared Runners
296 297
on large public GitLab instances, controlling access to your GitLab instance,
and using more secure [Runner Executors](https://docs.gitlab.com/runner/executors/README.html).
298 299 300 301

### Forks

Whenever a project is forked, it copies the settings of the jobs that relate
302 303
to it. This means that if you have shared Runners setup for a project and
someone forks that project, the shared Runners will also serve jobs of this
304 305
project.

306
## Attack vectors in Runners
307

308 309 310
Mentioned briefly earlier, but the following things of Runners can be exploited.
We're always looking for contributions that can mitigate these
[Security Considerations](https://docs.gitlab.com/runner/security/).
311

312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333
### Resetting the registration token for a Project

If you think that registration token for a Project was revealed, you should
reset them. It's recommended because such token can be used to register another
Runner to thi Project. It may be next used to obtain the values of secret
variables or clone the project code, that normally may be unavailable for the
attacker.

To reset the token:

1. Go to **Settings > CI/CD** for a specified Project
1. Expand the **General pipelines settings** section
1. Find the **Runner token** form field and click the **Reveal value** button
1. Delete the value and save the form
1. After the page is refreshed, expand the **Runners settings** section
    and check the registration token - it should be changed

From now on the old token is not valid anymore and will not allow to register
a new Runner to the project. If you are using any tools to provision and
register new Runners, you should now update the token that is used to the
new value.

334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365
## Determining the IP address of a Runner

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17286) in GitLab 10.6.

It may be useful to know the IP address of a Runner so you can troubleshoot
issues with that Runner. GitLab stores and displays the IP address by viewing
the source of the HTTP requests it makes to GitLab when polling for jobs. The
IP address is always kept up to date so if the Runner IP changes it will be
automatically updated in GitLab.

The IP address for shared Runners and specific Runners can be found in
different places.

### Shared Runners

To view the IP address of a shared Runner you must have admin access to
the GitLab instance. To determine this:

1. Visit **Admin area ➔ Overview ➔ Runners**
1. Look for the Runner in the table and you should see a column for "IP Address"

![shared Runner IP address](img/shared_runner_ip_address.png)

### Specific Runners

You can find the IP address of a Runner for a specific project by:

1. Visit your project's **Settings ➔ CI/CD**
1. Find the Runner and click on it's ID which links you to the details page
1. On the details page you should see a row for "IP Address"

![specific Runner IP address](img/specific_runner_ip_address.png)
Tomasz Maczukin's avatar
Tomasz Maczukin committed
366 367 368 369 370 371 372

[install]: http://docs.gitlab.com/runner/install/
[fifo]: https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)
[register]: http://docs.gitlab.com/runner/register/
[protected branches]: ../../user/project/protected_branches.md
[protected tags]: ../../user/project/protected_tags.md
[project defined timeout]: ../../user/project/pipelines/settings.html#timeout