管理运行器

GitLab Runner 有以下几种类型的运行器，具体可用性取决于您希望谁能够访问：

• 实例运行器 可用于 GitLab 实例中的所有组和项目。
• 组运行器 可用于组中的所有项目和子组。
• 项目运行器 与特定项目关联。 通常，项目运行器一次只被一个项目使用。

实例运行器

实例运行器 可用于 GitLab 实例中的每个项目。

当您有多个具有相似需求的作业时，请使用实例运行器。与其 为多个项目设置多个空闲运行器，不如设置少量运行器来处理 多个项目。

如果您使用的是 GitLab 自托管版，管理员可以：

• 安装 GitLab Runner 并注册一个实例运行器。
• 为每个组设置实例运行器的最大 计算分钟数。

如果您使用的是 GitLab.com：

• 您可以从 GitLab 维护的实例运行器列表 中选择。
• 实例运行器会消耗您账户中包含的 计算分钟数。

使用运行器认证令牌创建实例运行器

先决条件：

• 您必须是管理员。

创建运行器时，会为其分配一个运行器认证令牌，您使用该令牌来注册它。运行器使用此令牌在从作业队列获取作业时向 GitLab 进行身份验证。

要创建实例运行器：

1. 在左侧边栏底部，选择 Admin。
2. 选择 CI/CD > Runners。
3. 选择 New instance runner。
4. 选择安装了 GitLab Runner 的操作系统。
5. 在 Tags 部分，Tags 字段中，输入作业标签以指定运行器可以运行的作业。 如果此运行器没有作业标签，请选择 Run untagged。
6. 可选。在 Runner description 字段中，添加一个在 GitLab 中显示的运行器描述。
7. 可选。在 Configuration 部分，添加其他配置。
8. 选择 Create runner。
9. 按照屏幕说明从命令行注册运行器。当命令行提示时：
   • 对于 GitLab instance URL，使用您的 GitLab 实例 URL。例如，如果您的项目 托管在 gitlab.example.com/yourname/yourproject，您的 GitLab 实例 URL 是 https://gitlab.example.com。
   • 对于 executor，输入 executor 的类型。executor 是 运行器执行作业的环境。

您也可以 使用 API 创建运行器。

使用注册令牌创建实例运行器（已弃用）

先决条件：

• 运行器注册令牌必须在 Admin 区域中启用。
• 您必须是管理员。

要创建实例运行器：

1. 在左侧边栏底部，选择 Admin。
2. 选择 CI/CD > Runners。
3. 选择 Register an instance runner。
4. 复制注册令牌。
5. 注册运行器。

暂停或恢复实例运行器

先决条件：

• 您必须是管理员。

您可以暂停运行器，使其不再接受 GitLab 实例中组和项目的作业。

1. 在左侧边栏底部，选择 Admin。
2. 选择 CI/CD > Runners。
3. 在搜索框中，输入运行器描述或筛选运行器列表。
4. 在运行器列表中，在运行器右侧：
   • 要暂停运行器，选择 Pause ( )。
   • 要恢复运行器，选择 Resume ( )。

删除实例运行器

先决条件：

• 您必须是管理员。

删除实例运行器时，它将从 GitLab 实例中永久删除，并且 不再被组和项目使用。如果您想暂时停止运行器接受 作业，可以改为暂停运行器。

要删除单个或多个实例运行器：

1. 在左侧边栏底部，选择 Admin。
2. 选择 CI/CD > Runners。
3. 在搜索框中，输入运行器描述或筛选运行器列表。
4. 删除实例运行器：
   • 要删除单个运行器，在运行器旁边，选择 Delete runner ( )。
   • 要删除多个实例运行器，为每个运行器选择复选框，然后选择 Delete selected。
   • 要删除所有运行器，选择运行器列表顶部的复选框，然后选择 Delete selected。
5. 选择 Permanently delete runner。

为项目启用实例运行器

在 GitLab.com 上，实例运行器 默认在所有项目中启用。

在 GitLab 自托管版中，管理员可以 为所有新项目启用它们。

对于现有项目，管理员必须 安装 和 注册它们。

要为项目启用实例运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 启用 Turn on instance runners for this project 开关。

为组启用实例运行器

要为组启用实例运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 启用 Turn on instance runners for this group 开关。

为项目禁用实例运行器

您可以禁用单个项目或组的实例运行器。 您必须拥有项目 或组的 Owner 角色。

要为项目禁用实例运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 在 Instance runners 区域，关闭 Turn on runners for this project 开关。

实例运行器在以下情况下会自动为项目禁用：

• 如果父组的实例运行器设置被禁用，并且
• 如果不允许项目覆盖此设置。

为组禁用实例运行器

要为组禁用实例运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 关闭 Enable instance runners for this group 开关。
5. 可选。要允许为单个项目或子组启用实例运行器， 选择 Allow projects and subgroups to override the group setting。

实例运行器如何选择作业

实例运行器使用公平使用队列处理作业。该队列防止 项目创建数百个作业并使用所有可用的 实例运行器资源。

公平使用队列算法根据在实例运行器上 运行作业数量最少的项目来分配作业。

例如，如果队列中有以下作业：

• 项目 1 的作业 1
• 项目 1 的作业 2
• 项目 1 的作业 3
• 项目 2 的作业 4
• 项目 2 的作业 5
• 项目 3 的作业 6

当多个 CI/CD 作业同时运行时，公平使用算法按以下顺序分配作业：

1. 作业 1 首先被分配，因为它来自没有运行作业的项目中编号最低的作业（即所有项目）。
2. 接下来是作业 4，因为 4 现在来自没有运行作业的项目中编号最低的作业（项目 1 有一个作业正在运行）。
3. 接下来是作业 6，因为 6 现在来自没有运行作业的项目中编号最低的作业（项目 1 和 2 都有作业正在运行）。
4. 接下来是作业 2，因为在运行作业数量最少的项目中（每个项目都有 1 个），它是编号最低的作业。
5. 接下来是作业 5，因为项目 1 现在有 2 个作业正在运行，而作业 5 是项目 2 和 3 之间编号最低的剩余作业。
6. 最后是作业 3，因为它是剩下的唯一作业。

当一次只运行一个作业时，公平使用算法按以下顺序分配作业：

1. 首先选择作业 1，因为它来自没有运行作业的项目中编号最低的作业（即所有项目）。
2. 我们完成作业 1。
3. 接下来是作业 2，因为完成作业 1 后，所有项目又都有 0 个作业正在运行，而 2 是可用的最低作业编号。
4. 接下来是作业 4，因为项目 1 正在运行一个作业，4 是来自没有运行作业的项目（项目 2 和 3）中的最低编号。
5. 我们完成作业 4。
6. 接下来是作业 5，因为完成作业 4 后，项目 2 又没有作业正在运行。
7. 接下来是作业 6，因为项目 3 是唯一没有运行作业的项目。
8. 最后我们选择作业 3，因为，再次强调，它是剩下的唯一作业。

组运行器

当您希望组中的所有项目都能访问一组运行器时，请使用组运行器。

组运行器使用先进先出（FIFO）队列处理作业。

使用运行器认证令牌创建组运行器

先决条件：

• 您必须拥有组的 Owner 角色。

您可以为 GitLab 自托管版或 GitLab.com 创建组运行器。 创建运行器时，会为其分配一个运行器认证令牌，您使用该令牌来注册它。 运行器使用此令牌在从作业队列获取作业时向 GitLab 进行身份验证。

要创建组运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Build > Runners。
3. 选择 New group runner。
4. 在 Tags 部分，Tags 字段中，输入作业标签以指定运行器可以运行的作业。 如果此运行器没有作业标签，请选择 Run untagged。
5. 可选。在 Runner description 字段中，添加一个在 GitLab 中显示的运行器描述。
6. 可选。在 Configuration 部分，添加其他配置。
7. 选择 Create runner。
8. 选择安装了 GitLab Runner 的平台。
9. 完成屏幕说明：
   • 对于 Linux、macOS 和 Windows，当命令行提示时：
     • 对于 GitLab instance URL，使用您的 GitLab 实例 URL。例如，如果您的项目 托管在 gitlab.example.com/yourname/yourproject，您的 GitLab 实例 URL 是 https://gitlab.example.com。
     • 对于 executor，输入 executor 的类型。executor 是 运行器执行作业的环境。
   • 对于 Google Cloud，请参阅 在 Google Cloud 中预配运行器。

您也可以 使用 API 创建运行器。

使用注册令牌创建组运行器（已弃用）

先决条件：

• 运行器注册令牌必须在顶级组中启用。
• 您必须拥有组的 Owner 角色。

要创建组运行器：

1. 安装 GitLab Runner。
2. 在左侧边栏，选择 Search or go to 并找到您的组。
3. 选择 Build > Runners。
4. 在右上角，选择 Register a group runner。
5. 选择 Show runner installation and registration instructions。 这些说明包括令牌、URL 和注册运行器的命令。

或者，您可以复制注册令牌并遵循文档 如何注册运行器。

查看组运行器

先决条件：

• 您必须拥有组的 Maintainer 或 Owner 角色。

您可以查看组及其子组和项目的所有运行器。 您可以在 GitLab 自托管版或 GitLab.com 上执行此操作。

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Build > Runners。

筛选组运行器以仅显示继承的

您可以选择显示列表中的所有运行器，或仅显示 从实例或其他组继承的运行器。

默认情况下，仅显示继承的运行器。

要显示实例中所有可用的运行器，包括实例运行器和其他组中的运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Build > Runners。
3. 在列表上方，关闭 Show only inherited 开关。

暂停或恢复组运行器

先决条件：

• 您必须是管理员或拥有组的 Owner 角色。

您可以暂停运行器，使其不再接受 GitLab 实例中子组和项目的作业。如果您暂停被多个项目使用的组运行器，该运行器将暂停所有项目。

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Build > Runners。
3. 在搜索框中，输入运行器描述或筛选运行器列表。
4. 在运行器列表中，在运行器右侧：
   • 要暂停运行器，选择 Pause ( )。
   • 要恢复运行器，选择 Resume ( )。

删除组运行器

先决条件：

• 您必须是管理员或拥有组的 Owner 角色。

删除组运行器时，它将从 GitLab 实例中永久删除，并且 不再被子组和项目使用。如果您想暂时停止运行器接受 作业，可以改为暂停运行器。

要删除单个或多个组运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Build > Runners。
3. 在搜索框中，输入运行器描述或筛选运行器列表。
4. 删除组运行器：
   • 要删除单个运行器，在运行器旁边，选择 Delete runner ( )。
   • 要删除多个实例运行器，为每个运行器选择复选框，然后选择 Delete selected。
   • 要删除所有运行器，选择运行器列表顶部的复选框，然后选择 Delete selected。
5. 选择 Permanently delete runner。

清理过时的组运行器

先决条件：

• 您必须拥有组的 Owner 角色。

您可以清理超过三个月未活动的组运行器。

组运行器是在特定组中创建的运行器。

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 启用 Enable stale runner cleanup 开关。

查看过时的运行器清理日志

您可以检查 Sidekiq 日志 查看清理结果。在 Kibana 中，您可以使用以下查询：

{
  "query": {
    "match_phrase": {
      "json.class.keyword": "Ci::Runners::StaleGroupRunnersPruneCronWorker"
    }
  }
}

筛选已删除过时运行器的条目：

{
  "query": {
    "range": {
      "json.extra.ci_runners_stale_group_runners_prune_cron_worker.total_pruned": {
        "gte": 1,
        "lt": null
      }
    }
  }
}

项目运行器

当您想为特定项目使用运行器时，请使用项目运行器。例如， 当您有：

• 具有特定要求的作业，如需要凭据的部署作业。
• CI 活动频繁的项目，可以从与其他运行器分离中受益。

您可以设置一个项目运行器供多个项目使用。项目运行器 必须为每个项目显式启用。

项目运行器使用先进先出（FIFO）队列处理作业。

项目运行器所有权

当运行器首次连接到项目时，该项目成为运行器的所有者。

如果您删除所有者项目：

1. GitLab 查找共享该运行器的所有其他项目。
2. GitLab 将所有权分配给关联时间最长的项目。
3. 如果没有其他项目共享该运行器，GitLab 会自动删除该运行器。

您无法从所有者项目中取消分配运行器。请删除运行器。

使用运行器认证令牌创建项目运行器

先决条件：

• 您必须拥有项目的 Maintainer 角色。

您可以为 GitLab 自托管版或 GitLab.com 创建项目运行器。创建运行器时， 会为其分配一个运行器认证令牌，您使用该令牌注册到运行器。运行器使用此令牌在从作业队列获取作业时向 GitLab 进行身份验证。

要创建项目运行器：

1. 在左侧边栏，选择 Search or go to 并找到您的项目。
2. 选择 Settings > CI/CD。
3. 展开 Runners 部分。
4. 选择 New project runner。
5. 选择安装了 GitLab Runner 的操作系统。
6. 在 Tags 部分，Tags 字段中，输入作业标签以指定运行器可以运行的作业。 如果此运行器没有作业标签，请选择 Run untagged。
7. 可选。在 Runner description 字段中，添加一个在 GitLab 中显示的运行器描述。
8. 可选。在 Configuration 部分，添加其他配置。
9. 选择 Create runner。
10. 选择安装了 GitLab Runner 的平台。
11. 完成屏幕说明：
    • 对于 Linux、macOS 和 Windows，当命令行提示时：
      • 对于 GitLab instance URL，使用您的 GitLab 实例 URL。例如，如果您的项目 托管在 gitlab.example.com/yourname/yourproject，您的 GitLab 实例 URL 是 https://gitlab.example.com。
      • 对于 executor，输入 executor 的类型。executor 是 运行器执行作业的环境。
    • 对于 Google Cloud，请参阅 在 Google Cloud 中预配运行器。

您也可以 使用 API 创建运行器。

使用注册令牌创建项目运行器（已弃用）

先决条件：

• 运行器注册令牌必须在顶级组中启用。
• 您必须至少拥有项目的 Maintainer 角色。

要创建项目运行器：

1. 安装 GitLab Runner。
2. 在左侧边栏，选择 Search or go to 并 找到您要使用运行器的项目。
3. 选择 Settings > CI/CD。
4. 展开 Runners。
5. 在 Project runners 部分，记下 URL 和令牌。
6. 注册运行器。

运行器现在已为项目启用。

暂停或恢复项目运行器

先决条件：

• 您必须是管理员，或拥有项目的 Maintainer 角色。

您可以暂停项目运行器，使其不再接受在 GitLab 实例中分配给它的 项目的作业。

1. 在左侧边栏，选择 Search or go to 并 找到您要启用运行器的项目。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 在 Assigned project runners 部分，找到运行器。
5. 在运行器右侧：
   • 要暂停运行器，选择 Pause ( )，然后选择 Pause。
   • 要恢复运行器，选择 Resume ( )。

删除项目运行器

先决条件：

• 您必须是管理员，或拥有项目的 Maintainer 角色。
• 您无法删除分配给多个项目的项目运行器。在删除运行器之前，您必须禁用它在其中启用的所有项目。

删除项目运行器时，它将从 GitLab 实例中永久删除，并且 不再被项目使用。如果您想暂时停止运行器接受 作业，可以改为暂停运行器。

删除运行器时，其配置仍存在于运行器主机的 config.toml 文件中。 如果删除的运行器配置仍存在于该文件中，运行器主机将继续联系 GitLab。 为避免不必要的 API 流量，您还必须 注销已删除的运行器。

1. 在左侧边栏，选择 Search or go to 并 找到您要启用运行器的项目。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 在 Assigned project runners 部分，找到运行器。
5. 在运行器右侧，选择 Remove runner。
6. 要删除运行器，选择 Remove。

为不同项目启用项目运行器

创建项目运行器后，您可以为其启用其他项目。

先决条件： 您必须至少拥有以下项目的 Maintainer 角色：

• 运行器已启用的项目。
• 您要启用运行器的项目。
• 项目运行器不能被锁定。

要为项目启用项目运行器：

1. 在左侧边栏，选择 Search or go to 并 找到您要启用运行器的项目。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 在 Project runners 区域，在您想要的运行器旁边，选择 Enable for this project。

您可以从运行器启用的任何项目中编辑项目运行器。 修改包括解锁和编辑标签以及描述， 会影响使用该运行器的所有项目。

管理员可以为多个项目启用运行器。

防止项目运行器被启用到其他项目

您可以配置项目运行器，使其被"锁定"并且不能被启用到其他项目。 此设置可以在您首次注册运行器时启用，但也可以稍后更改。

要锁定或解锁项目运行器：

1. 在左侧边栏，选择 Search or go to 并 找到您要启用运行器的项目。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 找到您要锁定或解锁的项目运行器。确保它已启用。您不能锁定实例或组运行器。
5. 选择 Edit ( )。
6. 选择 Lock to current projects 复选框。
7. 选择 Save changes。

运行器状态

运行器可以具有以下状态之一。

过时运行器管理器清理

GitLab 定期删除过时的运行器管理器以保持数据库精简。 如果运行器联系 GitLab 实例，连接将被重新创建。

查看运行器性能统计

作为管理员，您可以查看运行器统计信息以了解您运行器群的性能。

Median job queued time 值是通过采样由实例运行器运行的 最近 100 个作业的队列持续时间来计算的。仅考虑来自最新 5000 个运行器的作业。

中位数是落入第 50 百分位的值。一半的作业 队列时间比中位数长，一半的作业队列时间比中位数 短。

要查看运行器统计信息：

1. 在左侧边栏底部，选择 Admin。
2. 选择 CI/CD > Runners。
3. 选择 View metrics。

确定需要升级的运行器

您运行器使用的 GitLab Runner 版本应 保持最新。

要确定需要升级的运行器：

1. 查看运行器列表：

   • 对于组：
     1. 在左侧边栏，选择 Search or go to 并找到您的组。
     2. 选择 Build > Runners。
   • 对于实例：
     1. 在左侧边栏底部，选择 Admin。
     2. 选择 CI/CD > Runners。

2. 在运行器列表上方，查看状态：

   • Outdated - recommended：运行器没有最新的 PATCH 版本，这可能会使其容易受到 安全或高严重性错误的影响。或者，运行器比您的 GitLab 实例落后一个或多个 MAJOR 版本，因此某些功能可能不可用或无法正常工作。
   • Outdated - available：有更新的版本可用，但升级不是关键。

3. 按状态筛选列表，查看哪些单个运行器需要升级。

确定运行器的 IP 地址

要排查运行器问题，您可能需要知道运行器的 IP 地址。 GitLab 通过查看运行器轮询作业时 HTTP 请求的来源来存储和显示 IP 地址。 GitLab 在 IP 地址更新时自动更新运行器的 IP 地址。

实例运行器和项目运行器的 IP 地址可以在 不同位置找到。

确定实例运行器的 IP 地址

先决条件：

• 您必须拥有实例的管理员权限。

要确定实例运行器的 IP 地址：

1. 在左侧边栏底部，选择 Admin。
2. 选择 CI/CD > Runners。
3. 在表格中找到运行器，查看 IP Address 列。

确定项目运行器的 IP 地址

要查找项目运行器的 IP 地址， 您必须拥有项目的 Owner 角色。

1. 转到项目的 Settings > CI/CD 并展开 Runners 部分。
2. 选择运行器名称，找到 IP Address 行。

向运行器配置添加维护说明

您可以为运行器添加维护说明以记录运行器。能够编辑运行器的 用户在查看运行器详情时会看到该说明。

使用此功能告知他人有关更改运行器配置的后果或问题。

在项目和组中启用使用运行器注册令牌

在 GitLab 17.0 中，所有 GitLab 实例中都将禁用使用运行器注册令牌。

先决条件：

• 运行器注册令牌必须在 Admin 区域中启用。

要在项目和组中启用使用运行器注册令牌：

1. 在左侧边栏，选择 Search or go to 并找到您的组。
2. 选择 Settings > CI/CD。
3. 展开 Runners。
4. 启用 Allow members of projects and groups to create runners with runner registration tokens 开关。