GitLab Runners

GitLab Runners

Original URL:

GitLab CI 中,Runners 运行你的 yaml。Runner 是一个独立/隔离的(虚拟)机器,它通过 GitLab CI 的协调器(coordinator) API 拾取作业。

Runner 可以服务特定的项目,或为 GitLab CI 的任何项目提供服务。为所有项目提供服务的 Runner 称为 Shared Runner

理想情况下,GitLab Runner 不应与 GitLab 安装在相同机器上。阅读需求文档以获取更多信息。

Shared vs. Specific Runners

具体的 Runner 仅针对指定的项目运行。共享的 Runner 可以为启用了 Allow shared Runners 的项目运行作业。

Shared Runners 对多个项目间需求类似的作业很有用。您可以使用一个或多个 Runner 来处理多个项目,而不是让多个 Runner 闲置等待多个项目。这样可以更容易维护和更新 Runner。

Specific Runners 对于要求特殊的作业,或有特定需求的项目很有用。如果一个作业有一定的要求,你可以设置一个 Specific Runner 来搞,而不必为所有 Runner 这样做。例如,如果要部署某个项目,可以设置 Specific Runner 以获取正确的凭据。

CI 活动频繁旺盛的项目也可以从使用 Specific Runner 中受益。通过 Specific Runners 可确保 Runner 不被其他项目的作业阻塞。

您可以设置 Specific Runner 供多个项目使用。与 Shared Runner 的区别在于,必须为 Runner 显式地启用上述每个项目,才能运行这些项目的作业。

Specific Runner 不会自动与 fork 出去的项目共享。fork 将复制所克隆的代码仓库 CI 设置(jobsallow shared 等)。

创建并注册 Runner

有几种方法可以创建 Runner。只有创建后,注册才能确定其为SharedSpecific状态。

安装 Runner 实例的不同方法,请参阅文档

安装 Runner 后,可将其注册为SharedSpecific。如果您有 GitLab 实例的管理员访问权限,则只能注册一个Shared Runner

注册Shared Runner

如果您是链接的 GitLab 实例上的管理员,则只能注册一个Shared Runner
(You can only register a shared Runner if you are an admin on the linked GitLab instance.)

在 GitLab CI 实例的admin/runners页面上获取shared-Runner令牌。

shared token

现在只需注册 Runner 即可:

sudo gitlab-ci-multi-runner register

从 GitLab 8.2 起,Shared Runners 默认启用,但可以使用DISABLE SHARED RUNNERS按钮禁用。以前版本的 GitLab 中,Shared Runners 默认为禁用。

注册Specific Runner

Registering a specific can be done in two ways:

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

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

Registering a Specific Runner with a Project Registration token

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.

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

project Runners in GitLab CI

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

sudo gitlab-ci-multi-runner register

Lock a specific Runner from being enabled for other projects

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.

Making an existing Shared Runner Specific

If you are an admin on your GitLab instance, you can make any shared Runner a specific Runner, but you can not make a specific Runner a shared Runner.

To make a shared Runner specific, go to the Runner page (/admin/runners) 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.

making a shared Runner specific

Using Shared Runners Effectively

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

Use Tags

You must setup a Runner to be able to run all the different types of jobs 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.

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

Prevent Runner 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 is available on each Runner in Project Settings > Runners.

Be careful with sensitive information

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.

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.


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

Attack vectors in Runners

Mentioned briefly earlier, but the following things of Runners can be exploited. We're always looking for contributions that can mitigate these Security Considerations.

Leave a Reply

Your email address will not be published.