BigW Consortium Gitlab

README.md 6.33 KB
Newer Older
1 2 3
# Runners

In GitLab CI, Runners run your [yaml](../yaml/README.md).
4
A Runner is an isolated (virtual) machine that picks up jobs
5 6
through the coordinator API of GitLab CI.

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, 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 15
## Shared vs. Specific Runners

16
A Runner that is specific only runs for the specified project. A shared Runner
17
can run jobs for every project that has enabled the option **Allow shared Runners**.
18

19 20 21 22
**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 Runners.
23

24
**Specific Runners** are useful for jobs that have special requirements or for
25
projects with a specific demand. If a job has certain requirements, you can set
26 27 28
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.
29

30 31
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
32 33
up by another project's jobs.

34 35 36
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.
37

38
Specific Runners do not get shared with forked projects automatically.
39 40 41 42
A fork does copy the CI settings (jobs, allow shared, etc) of the cloned repository.

# Creating and Registering a Runner

43
There are several ways to create a Runner. Only after creation, upon
44 45
registration its status as Shared or Specific is determined.

46
[See the documentation for](https://docs.gitlab.com/runner/install)
47 48
the different methods of installing a Runner instance.

49
After installing the Runner, you can either register it as `Shared` or as `Specific`.
50 51 52 53
You can only register a Shared Runner if you have admin access to the GitLab instance.

## Registering a Shared Runner

54
You can only register a shared Runner if you are an admin on the linked
55 56
GitLab instance.

57
Grab the shared-Runner token on the `admin/runners` page of your GitLab CI
58 59
instance.

60
![shared token](shared_runner.png)
61

62
Now simply register the Runner as any Runner:
63 64

```
65
sudo gitlab-ci-multi-runner register
66 67
```

68
Shared Runners are enabled by default as of GitLab 8.2, but can be disabled with the
69
`DISABLE SHARED RUNNERS` button. Previous versions of GitLab defaulted shared Runners to
70
disabled.
71 72 73 74 75

## Registering a Specific Runner

Registering a specific can be done in two ways:

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

79 80
There are several ways to create a Runner instance. The steps below only
concern registering the Runner on GitLab CI.
81 82 83

###  Registering a Specific Runner with a Project Registration token

84 85
To create a specific Runner without having admin rights to the GitLab instance,
visit the project you want to make the Runner work for in GitLab CI.
86

87 88
Click on the Runner tab and use the registration token you find there to
setup a specific Runner for this project.
89

90
![project Runners in GitLab CI](project_specific.png)
91

92
To register the Runner, run the command below and follow instructions:
93 94

```
95
sudo gitlab-ci-multi-runner register
96 97
```

98
###  Lock a specific Runner from being enabled for other projects
99

100 101 102
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.
This setting is available on each Runner in *Project Settings* > *Runners*.
103

104 105 106
###  Making an existing Shared Runner Specific

If you are an admin on your GitLab instance,
107 108
you can make any shared Runner a specific Runner, _but you can not
make a specific Runner a shared Runner_.
109

110
To make a shared Runner specific, go to the Runner page (`/admin/runners`)
111 112
and find your Runner. Add any projects on the left to make this Runner
run exclusively for these projects, therefore making it a specific Runner.
113

114
![making a shared Runner specific](shared_to_specific_admin.png)
115 116 117

## Using Shared Runners Effectively

118
If you are planning to use shared Runners, there are several things you
119 120 121 122
should keep in mind.

### Use Tags

123
You must setup a Runner to be able to run all the different types of jobs
124 125 126 127
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
128
shared Runners will only run the jobs they are equipped to run.
129

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

133
### Prevent Runner with tags from picking jobs without tags
134

135 136 137
You can configure a Runner to prevent it from picking jobs with tags when
the Runner does not have tags assigned. This setting is available on each
Runner in *Project Settings* > *Runners*.
138 139

### Be careful with sensitive information
140

141 142 143
If you can run a job on a Runner, you can get access to any code it runs
and get the token of the Runner. With shared Runners, this means that anyone
that runs jobs on the Runner, can access anyone else's code that runs on the Runner.
144

145 146
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.
147

148
The above is easily avoided by restricting the usage of shared Runners
149 150 151 152 153
on large public GitLab instances and controlling access to your GitLab instance.

### Forks

Whenever a project is forked, it copies the settings of the jobs that relate
154 155
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
156 157
project.

158
## Attack vectors in Runners
159

160 161 162
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/).