管理 Runner

Runner 有以下类型，可根据需要选择：

  • 共享 runners，可用于极狐GitLab 实例中的所有群组和项目。
  • 群组 runners，可用于群组中的所有项目和子组。
  • 项目 runners 与特定项目相关联。通常，项目 runner 只用于一个项目。

实例 runners

实例 runners 可用于极狐GitLab 实例中的每一个项目。

当您有多个具有相似要求的作业时，请使用实例 runner。与其让多个 runner 闲置在许多项目中，不如让几个 runner 处理多个项目。

如果您使用的是极狐GitLab 的私有化部署实例：

如果您在使用 SaaS：

创建具有 runner 认证令牌的实例 runner

  • 引入于极狐GitLab 15.10。使用名为 create_runner_workflow_for_admin 的功能标志。
  • 在极狐GitLab 16.0 中默认启用。
  • 在极狐GitLab 16.2 中 GA。功能标志 create_runner_workflow_for_admin 被移除。

先决条件：

  • 您必须是管理员。

当您创建 runner 时，会给您分配一个用来注册 runner 的 runner 注册令牌。当从作业队列中获取作业时，runner 会使用此令牌与极狐GitLab 实例进行通信。

要创建实例 runner：

  1. 在左侧导航栏，在底部，选择 管理员。
  2. 选择 CI/CD > Runners。
  3. 选择 创建实例 runner。
  4. 选择极狐GitLab Runner 安装的操作系统。
  5. 在 标签 部分中，在 标签 字段中输入作业标签，以指定 runner 可运行的作业。如果此 runner 没有标签，请选择 运行未标记的。
  6. 可选。在 Runner 描述 字段中，输入要在极狐GitLab 中显示的 runner 描述。
  7. 可选。在 配置 部分中，添加其他配置。
  8. 选择 创建 runner。
  9. 按照命令行上的说明从命令行注册 runner。当命令行提示时：
    • 对于 GitLab 实例 URL，使用您极狐GitLab 实例的 URL。例如，如果您的项目托管在 gitlab.example.com/yourname/yourproject，则您的极狐GitLab 实例 URL 为 https://gitlab.example.com。
    • 对于 executor，输入 executor 的类型。执行器是 runner 执行作业的环境。

您还可以使用 API来创建 runner。

note 在注册期间，runner 认证令牌会在 UI 上短暂展示。注册后，runner 认证令牌会存储在 config.toml 中。

暂停或恢复实例 runner

先决条件：

  • 您必须是管理员。

您可以暂停 runner，然后它就无法接受来自群组和项目的作业。

  1. 在左侧导航栏，在底部，选择 管理员。
  2. 选择 CI/CD > Runners。
  3. 在搜索框中，输入 runner 描述或筛选 runner 列表。
  4. 在 runner 列表中，runner 右侧：
    • 要暂停 runner，请选择 暂停（ ）。
    • 要恢复 runner，请选择 恢复（ ）。

删除实例 runner

先决条件：

  • 您必须是管理员。

当您删除实例 runner 时，它会从极狐GitLab 实例中永久删除，且不再能被群组和项目使用。如果您想临时停止 runner 接受作业，您可以暂停runner。

要删除单个或多个实例 runner：

  1. 在左侧导航栏，在底部，选择 管理员。
  2. 选择 CI/CD > Runners。
  3. 在搜索框中，输入 runner 描述或筛选 runner 列表。
  4. 删除实例 runner：
    • 要删除单个 runner，请在 runner 右侧选择 删除 runner（ ）。
    • 要删除多个实例 runner，请选择每个 runner 的复选框，然后选择 删除所选。
    • 要删除所有 runner，请选择 runner 列表顶部的复选框，然后选择 删除所选。
  5. 选择 永久删除 runner。

为项目启用实例 runner

在 JihuLab.com 上，默认为所有项目启用实例 runner。

在极狐GitLab 私有化部署实例上，管理员可以为所有新项目启用它们。

对于既有的项目，管理员必须安装并注册它们。

要为项目启用实例 runner：

  1. 在左侧导航栏，选择 搜索或前往，找到您的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 Runner。
  4. 打开 为此项目启用实例 runner 开关。

为群组启用实例 runner

要为群组启用实例 runner：

  1. 在左侧导航栏，选择 搜索或前往，找到您的群组。
  2. 选择 设置 > CI/CD。
  3. 展开 Runner。
  4. 打开 为此群组启用实例 runner 开关。

为此项目禁用实例 runner

您可以为群组的单个项目禁用实例 runner。您必须具有项目或群组的所有者角色。

要为项目禁用实例 runner。

  1. 在左侧导航栏，选择 搜索或前往，找到您的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 Runner。
  4. 在 实例 runner 部分，关闭 为此项目启用实例 runner 开关。

实例 runner 在以下情况下自动为项目禁用：

  • 如果父群组的实例 runner 设置已禁用，且
  • 不允许覆盖此设置。

为群组禁用实例 runner

要为群组禁用实例 runner：

  1. 在左侧导航栏，选择 搜索或前往，找到您的群组。
  2. 选择 设置 > CI/CD。
  3. 展开 Runner。
  4. 关闭 为此群组启用实例 runner 开关。
  5. 可选。要允许项目和子组覆盖群组设置，请选择 允许项目和子组覆盖群组设置。

实例 runner 如何获取作业

实例 runner 通过使用公平使用队列来处理作业。此队列可防止项目创建数百个作业并使用所有可用的实例 runner 资源。

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

比如，如果这些作业在队列中：

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

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

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

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

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

群组 runner

当您希望群组中的所有项目都可以访问一组 runner时，请使用群组 runner。

群组 runner 使用先进先出 (FIFO) 队列来处理作业。

使用 runner 认证令牌创建 runner

  • 引入于极狐GitLab 15.10。使用名为 create_runner_workflow_for_namespace 的功能标志。默认禁用。
  • 在极狐GitLab 16.0 中默认启用。
  • 在极狐GitLab 16.2 中 GA。功能标志 create_runner_workflow_for_admin 被移除。

先决条件：

  • 您必须具有群组所有者角色。

您可以为极狐GitLab SaaS（JihuLab.com）或极狐GitLab 私有化部署实例创建群组 runner。当您创建 runner 时，会为您分配一个用来注册 runner 的 runner 认证令牌。当 runner 从作业队列获取作业时，runner 使用令牌来和极狐GitLab 进行认证。

要创建群组 runner：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 构建 > Runners。
  3. 选择 新建群组 runner。
  4. 在 标签 部分，标签 字段中输入作业标签，以指定 runner 可以运行的作业。如果群组 runner 没有作业标签，请选择 运行无标签。
  5. 可选。在 Runner 描述 字段中，添加一个 runner 描述，该描述将在极狐GitLab 中显示。
  6. 可选。在 配置 部分，添加其他配置。
  7. 选择 创建 runner。
  8. 选择极狐GitLab Runner 安装的平台。
  9. 完成屏幕上的说明：
    • 对 于 Linux、macOS 和 Windows，当命令行提示时：
      • 对于 GitLab 实例 URL，使用您的极狐GitLab 实例的 URL。例如，如果您的项目托管在 gitlab.example.com/yourname/yourproject，您的 GitLab 实例 URL 是 https://gitlab.example.com。
      • 对于 executor，输入 executor 的类型。执行器是 runner 执行作业的环境。

您还可以使用 API 来创建 runner。

note runner 认证令牌会在 runner 注册期间在 UI 上短暂展示。

查看群组 runners

  • 对于具有维护者角色的用户查看群组 runner 的能力引入于极狐GitLab 16.4。

先决条件：

  • 您必须具有群组的维护者或所有者角色。

您可以查看群组以及其子群组和项目的所有 runner。您可以在 JihuLab.com 或私有化部署实例上查看：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 构建 > Runners。

过滤群组以仅展示继承的

  • 引入于极狐GitLab 15.5。
  • 在极狐GitLab 15.5 中 GA。功能标志 runners_finder_all_available 被移除。

您可以选择在列表中展示所有的 runner，或仅展示那些从实例或其他群组继承的 runner。

默认情况下，仅展示继承的 runner。

要在实力上展示所有的 runner，包括实例 runner 和其他群组中的 runner：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 构建 > Runners。
  3. 在列表上方，关闭 仅展示继承的 开关。

暂停或恢复群组 runner

先决条件：

  • 您必须是管理员或具有群组的所有者角色。

您可以暂停 runner 以便它停止接受来自子组和项目的作业。如果您暂停了多个项目使用的群组 runner，runner 将暂停所有项目。

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 构建 > Runners。
  3. 在搜索框中，输入 runner 描述或过滤 runner 列表。
  4. 在 runner 列表中，前往 runner 右侧：
    • 要暂停 runner，请选择 暂停 ( )。
    • 要恢复 runner，请选择 恢复 ( )。

删除群组 runner

  • 多 runner 删除引入于极狐GitLab 15.6。

先决条件：

  • 您必须是管理员或具有群组的所有者角色。

当您删除群组 runner 时，它从极狐GitLab 示例中永久删除且无法再被子群组或项目使用。如果您想临时停止 runner 以阻止其接受作业，您可以暂停runner。

要删除单个或多个群组 runner：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 构建 > Runners。
  3. 在搜索框中，输入 runner 描述或过滤 runner 列表。
  4. 删除群组 runner：
    • 要删除单个 runner，请在 runner 右侧选择 删除 runner ( )。
    • 要删除多个群组 runner，请选择每个 runner 的复选框并选择 删除所选。
    • 要删除所有 runner，请选择 runner 列表顶部的复选框并选择 删除所选。
  5. 选择 永久删除 runner。

清理陈旧的群组 runner

  • 引入于极狐GitLab 15.1。

先决条件：

  • 您必须具有群组的所有者角色。

您可以清理那些不活跃超过三个月的群组 runner。

群组 runner 是在指定群组创建的 runner。

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 设置 > CI/CD。
  3. 展开 Runner。
  4. 打开 启用陈旧 runner 清理 开关。

查看陈旧 runner 的清理日志

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

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

Filter entries where stale runners were removed:

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

项目 runner

当您想将 runner 用于特定项目时，请使用项目 runner。 例如，当您有：

  • 具有特定要求的作业，例如需要凭据的部署作业。
  • 具有大量 CI 活动的项目可以从与其它 runner 分开中受益。

您可以设置一个项目 Runner 供多个项目使用。必须为每个项目明确启用项目 Runner。

项目 Runner 使用先进先出 (FIFO) 队列来处理作业。

note 项目 Runner 不会自动与派生项目共享。派生复制了克隆仓库的 CI/CD 设置。

使用 runner 认证令牌来创建项目 runner

  • 引入于极狐GitLab 15.10。使用名为 create_runner_workflow_for_namespace 的功能标志。默认禁用。
  • 在极狐GitLab 16.0 中默认启用。
  • 在极狐GitLab 16.2 中 GA。功能标志 create_runner_workflow_for_admin 被移除。

先决条件：

  • 您必须具有项目的维护者角色。

您可以为极狐GitLab 私有化部署实例或 JihuLab.com 创建 runner。当您创建 runner 时，会为您分配一个用来注册 runner 的 runner 认证令牌。当 runner 从作业队列获取作业时，runner 使用令牌来和极狐GitLab 进行认证。

要创建项目 runner：

  1. 在导航栏左侧，选择 搜索或前往 并找到您的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 Runner 部分。
  4. 选择 新建项目 runner。
  5. 选择您安装极狐GitLab Runner 的操作系统。
  6. 在 标签 部分，标签 字段中输入指定 runner 可以运行的作业的作业标签。如果此 runner 没有作业标签，请选择 运行无标签。
  7. 可选。在 Runner 描述 字段中，添加一个描述，该描述将在极狐GitLab 中显示。
  8. 可选。在 配置 部分，添加其他配置。
  9. 选择 创建 runner。
  10. 完成屏幕上的说明：
    • 对于 Linux、macOS 和 Windows，当命令行提示时：
      • 对于 GitLab 实例 URL，使用您的 GitLab 实例的 URL。例如，如果您的项目托管在 gitlab.example.com/yourname/yourproject，则您的 GitLab 实例 URL 为 https://gitlab.example.com。
      • 对于 executor，输入 executor 的类型。执行器是在 runner 执行作业的环境中。

您还可以使用 API 创建 runner。

note runner 注册令牌尽在注册期间短暂展示在 UI 上。

暂停或恢复项目 runner

先决条件：

  • 您必须是管理员，或具有项目的维护者角色。

您可以暂停 runner 以便它停止接受来自项目的作业。

  1. 在左侧导航栏，选择 搜索或前往 并找到您的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 Runner。
  4. 在 指派的项目 runner 部分，找到 runner。
  5. 在 runner 右侧：
    • 要暂停 runner，请选择 暂停 ( )，然后选择 暂停。
    • 要恢复 runner，请选择 恢复 ( )。

删除项目 runner

先决条件：

  • 您必须是管理员，或具有项目的所有者角色。
  • 您不能删除分配给多个项目的项目 runner。 在删除 runner 之前，您必须在所有启用 runner 的项目中禁用它。

当您删除一个项目 runner 时，它会从极狐GitLab 实例中永久删除并且无法再被项目使用。如果您想临时停止 runner 以阻止其接受作业，您可以暂停runner。

当您删除一个 runner 时，它的配置依旧会存在于宿主机的 config.toml 文件中。如果已删除的 runner 的配置仍然存在于此文件中，runner 主机将继续联系极狐GitLab。为了防止不必要的 API 流量，您还必须注销已删除的 runner。

  1. 在左侧边栏中，选择 搜索或前往 并找到您想启用 runner 的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 Runners。
  4. 在 指派的项目 runner 部分，找到 runner。
  5. 在 runner 右侧，选择 删除 runner。
  6. 要删除 runner，请选择 删除。

为不同项目启用项目 runner

当项目 runner 创建后，您可以为其他项目启用此 runner。

先决条件，在下列情况中，您必须至少具有维护者角色：

  • 已经启用 runner 的项目。
  • 您想启用 runner 的项目。
  • 项目 runner 未被锁定。

要为项目启用项目 runner：

  1. 在左侧边栏中，选择 搜索或前往 并找到您想启用 runner 的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 Runners。
  4. 在 项目 runner 区域，选择您想要的 runner，然后选择 为此项目启用。

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

管理员可以为多个项目启用 runner。

阻止项目 runner 被其他项目启用

您可以配置一个项目 runner 以让其变为“被锁定”，且不能被其他项目启用。可以在首次注册 runner时启用此设置，但是稍后就无法修改了。

锁定或解锁项目 runner：

  1. 在左侧边栏中，选择 搜索或前往 并找到您想启用 runner 的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 Runners。
  4. 找到您想要锁定或解锁的项目 runner。确保它已启用。您无法锁定实例或组 runner。
  5. 选择 编辑（ ）。
  6. 选择 锁定到当前项目 复选框。
  7. 选择 保存更改。

Runner 状态

Runner 可以具有以下状态。

状态 描述
online runner 在过去 2 小时内已经联系了极狐GitLab 且已经能够运行作业了。
offline runner 在过去 2 小时内没有联系极狐GitLab，且已经不能够运行作业了。检查 runner 以查看是否能够让其在线。
stale runner 在过去 7 天内没有联系极狐GitLab。如果 runner 的创建超过 7 天，但是它从未联系到实例，则认为它是 陈旧的。
never_contacted runner 从未联系过极狐GitLab。要让 runner 联系极狐GitLab，运行 gitlab-runner run。

查看 runner 性能统计

  • 引入于极狐GitLab 15.8。

作为管理员，您可以查看 runner 统计来学习 runner fleet 的性能。

作业队列数中位数 值是通过采样最近 100 个作业的队列持续时间来计算的，这些作业由实例运行器运行。仅考虑来自最新 5000 个 runner 的作业。

中位数是一个落在第 50 个百分位的值。一半的作业排队时间比中位数长，另一半排队时间比中位数短。

要查看 runner 统计：

  1. 在左侧导航栏，在底部，选择 管理员。
  2. 选择 CI/CD > runner。
  3. 选择 查看指标。

决定升级哪个 runner

  • 引入于极狐GitLab 15.3。

The version of GitLab Runner used by your runners should be kept up-to-date.

要决定升级哪个 runner：

  1. 查看 runner 列表：
    • 对于群组：
      1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
      2. 选择 构建 > 运行程序。
    • 对于实例：
      1. 在左侧导航栏，在底部，选择 管理员。
      2. 选择 CI/CD > Runners。
  2. 在 runner 列表上方，查看状态：
    • 过时 - 建议：runner 没有最新的 PATCH 版本，这可能会使它容易受到安全或高严重性漏洞的影响。或者，runner 比您的极狐GitLab 实例落后一个或多个 MAJOR 版本，因此一些功能可能不可用或无法正常工作。
    • 过时 - 可用：有可用的新版本，但升级不是至关重要的。
  3. 按状态筛选列表以查看需要升级的单个 runner。

确定 runner 的 IP 地址

为了对 runner 问题进行故障排查，您可能需要知道 runner 的 IP 地址。极狐GitLab 会存储并显示 runner 的 IP 地址，方法是查看 runner 轮询作业时 HTTP 请求的来源。极狐GitLab 会自动更新 runner 的 IP 地址，只要它被更新。

可以在不同的地方发现实例 runner 和项目 runner 的 IP 地址。

确定实例 runner 的 IP 地址

先决条件：

  • 您必须是管理员。
  1. 在左侧导航栏，在底部，选择 管理员。
  2. 选择 CI/CD > Runners。
  3. 在表格中找到 runner 并查看 IP Address 列。

Instance runner IP address

确定项目 runner 的 IP 地址

要想找到项目 runner 的 IP 地址，您必须具有项目的所有者角色。

  1. 前往项目的 设置 > CI/CD 并展开 Runners 部分。
  2. 选择 runner 名称并找到 IP Address 行。

Project runner IP address

在项目和群组中启用 runner 注册令牌的使用

  • 引入于极狐GitLab 16.11。
caution 传递 runner 注册令牌和对某些配置参数的支持已在极狐GitLab 15.6 中被弃用。它们计划在 GitLab 18.0 中移除。请改用 runner 身份验证令牌。有关更多信息，请参阅迁移到新的 runner 注册工作流程。

In GitLab 17.0, the use of runner registration tokens is disabled in all GitLab instances. 在极狐GitLab 17.0 中，在所有的示例中，runner 注册令牌的使用被禁用。

先决条件：

  • 必须在 管理员 区域中启用runner 注册令牌。

要在项目和群组中启用 runner 注册令牌的使用：

  1. 在左侧导航栏，选择 搜索或前往 并找到您的群组。
  2. 选择 设置 > CI/CD。
  3. 展开 Runners。
  4. 打开 允许项目和群组的成员使用 runner 注册令牌创建 runner 开关。