diff options
Diffstat (limited to 'doc/ci/runners/README.md')
| -rw-r--r-- | doc/ci/runners/README.md | 101 |
1 files changed, 90 insertions, 11 deletions
diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 76d746155eb..7a7b50b294d 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -1,4 +1,4 @@ -# Runners +# Configuring GitLab Runners 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 @@ -35,7 +35,7 @@ are: 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** -under **Settings ➔ Pipelines**. +under **Settings ➔ CI/CD**. 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 @@ -61,7 +61,7 @@ You can only register a shared Runner if you are an admin of the GitLab instance 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 -**Settings ➔ Pipelines** page. Previous versions of GitLab defaulted shared +**Settings ➔ CI/CD** page. Previous versions of GitLab defaulted shared Runners to disabled. ## Registering a specific Runner @@ -76,7 +76,7 @@ Registering a specific can be done in two ways: 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: -1. Go to **Settings ➔ Pipelines** to obtain the token +1. Go to **Settings ➔ CI/CD** to obtain the token 1. [Register the Runner][register] ### Making an existing shared Runner specific @@ -101,12 +101,53 @@ can be changed afterwards under each Runner's settings. To lock/unlock a Runner: -1. Visit your project's **Settings ➔ Pipelines** +1. Visit your project's **Settings ➔ CI/CD** 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 +## Assigning a Runner to another project + +If you are Master on a project where a specific Runner is assigned to, and the +Runner is not [locked only to that project](#locking-a-specific-runner-from-being-enabled-for-other-projects), +you can enable the Runner also on any other project where you have Master permissions. + +To enable/disable a Runner in your project: + +1. Visit your project's **Settings ➔ CI/CD** +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 +user with Master role in you project can assign your runner to another arbitrary +project without requiring your authorization, so use it with caution. + +## Protected Runners + +> +[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194) +in GitLab 10.0. + +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. + +To protect/unprotect Runners: + +1. Visit your project's **Settings ➔ CI/CD** +1. Find a Runner you want to protect/unprotect and make sure it's enabled +1. Click the pencil button besides the Runner name +1. Check the **Protected** option +1. Click **Save changes** for the changes to take effect + + + +## Manually clearing the Runners cache + +Read [clearing the cache](../caching/index.md#clearing-the-cache). + ## How shared Runners pick jobs Shared Runners abide to a process queue we call fair usage. The fair usage @@ -169,21 +210,22 @@ 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 -shared Runners will only run the jobs they are equipped to run. +shared Runners will [only run the jobs they are equipped to run](../yaml/README.md#tags). For instance, at GitLab we have Runners tagged with "rails" if they contain the appropriate dependencies to run Rails test suites. ### Preventing Runners with tags from picking jobs without tags -You can configure a Runner to prevent it from picking jobs with tags when -the Runner does not have tags assigned. This setting can be enabled the first +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 time you [register a Runner][register] and can be changed afterwards under each Runner's settings. To make a Runner pick tagged/untagged jobs: -1. Visit your project's **Settings ➔ Pipelines** +1. Visit your project's **Settings ➔ CI/CD** 1. Find the Runner you wish and make sure it's enabled 1. Click the pencil button 1. Check the **Run untagged jobs** option @@ -191,7 +233,8 @@ To make a Runner pick tagged/untagged jobs: ### Be careful with sensitive information -If you can run a job on a Runner, you can get access to any code it runs +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 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. @@ -200,7 +243,8 @@ 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. The above is easily avoided by restricting the usage of shared Runners -on large public GitLab instances and controlling access to your GitLab instance. +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). ### Forks @@ -218,3 +262,38 @@ We're always looking for contributions that can mitigate these [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 + +## 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" + + + +### 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" + + |