{{< details >}}

  1. Tier: 基础版, 专业版, 旗舰版
  2. Offering: JihuLab.com, 私有化部署

{{< /details >}}

{{< alert type=”disclaimer” />}}

在极狐GitLab 16.0 中，我们引入了一个新的 runner 创建工作流，该工作流使用 runner 身份验证令牌来注册 runner。使用注册令牌的传统工作流已被弃用，计划在极狐GitLab 20.0 中移除。请改用 runner 创建工作流。

新的 runner 注册工作流

对于新的 runner 注册工作流，您需要：

  1. 在极狐GitLab UI 中 创建一个 runner 或 通过编程方式创建。
  2. 收到一个 runner 身份验证令牌。
  3. 在注册 runner 时使用 runner 身份验证令牌而不是注册令牌。注册在多个主机上的 runner 管理器将在极狐GitLab UI 中显示为同一个 runner，但具有识别系统 ID。

新的 runner 注册工作流具有以下优点：

  • 保留了 runner 的所有权记录，并最大程度地减少了对用户的影响。
  • 添加了唯一的系统 ID，确保您可以在多个 runner 之间重用相同的身份验证令牌。有关更多信息，请参阅 重用极狐GitLab Runner 配置。

计划变更的预计时间框架

  1. 在极狐GitLab 15.10 及更高版本中，您可以使用新的 runner 注册工作流。
  2. 在极狐GitLab 20.0 中，我们计划禁用 runner 注册令牌。

防止您的 runner 注册工作流中断

在极狐GitLab 16.11 及更早版本中，您可以使用传统的 runner 注册工作流。

在极狐GitLab 17.0 中，传统的 runner 注册工作流默认被禁用。您可以暂时重新启用传统的 runner 注册工作流。有关更多信息，请参阅 在极狐GitLab 17.0 之后使用注册令牌。

如果您在升级到极狐GitLab 17.0 时没有迁移到新工作流，runner 注册将中断，并且 gitlab-runner register 命令将返回 410 Gone - runner registration disallowed 错误。

为避免工作流中断，您必须：

  1. 创建一个 runner 并获取身份验证令牌。
  2. 在您的 runner 注册工作流中用身份验证令牌替换注册令牌。

{{< alert type=”warning” >}}

在极狐GitLab 17.0 及更高版本中，runner 注册令牌被禁用。要使用存储的 runner 注册令牌注册新 runner，您必须 启用令牌。

{{< /alert >}}

在极狐GitLab 17.0 之后使用注册令牌

要在极狐GitLab 17.0 之后继续使用注册令牌：

  1. 在 JihuLab.com 上，您可以在顶级群组设置中手动 启用传统 runner 注册流程。
  2. 在极狐GitLab私有化部署中，您可以在 管理员 区域设置中手动 启用传统 runner 注册流程。

对现有 runner 的影响

在升级到极狐GitLab 17.0 后，现有 runner 将继续正常工作。此更改仅影响新 runner 的注册。

极狐GitLab Runner Helm chart 在每次执行作业时生成新的 runner pod。对于这些 runner，请 启用传统 runner 注册 以使用注册令牌。在极狐GitLab 18.0 及更高版本中，您必须迁移到 新的 runner 注册工作流。

gitlab-runner register 命令语法的更改

gitlab-runner register 命令接受 runner 身份验证令牌而不是注册令牌。您可以从 管理员 区域的 Runners 页面生成令牌。runner 身份验证令牌可以通过其 glrt- 前缀识别。

当您在极狐GitLab UI 中创建 runner 时，您需要指定先前由 gitlab-runner register 命令提示的命令行选项的配置值。这些命令行选项将在未来被弃用。

如果您使用以下方式指定 runner 身份验证令牌：

  • --token 命令行选项，gitlab-runner register 命令不接受配置值。
  • --registration-token 命令行选项，gitlab-runner register 命令忽略配置值。
Token Registration command
Runner authentication token gitlab-runner register --token $RUNNER_AUTHENTICATION_TOKEN
Runner registration token (deprecated) gitlab-runner register --registration-token $RUNNER_REGISTRATION_TOKEN <runner configuration arguments>

身份验证令牌的前缀为 glrt-。

为了确保对您的自动化工作流的最小干扰，指定 runner 身份验证令牌的情况下，触发与传统兼容的注册处理。 如果在传统参数 --registration-token 中指定了 runner 身份验证令牌，则会触发与传统兼容的注册处理。

极狐GitLab 15.9 的命令示例：

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --tag-list "shell,mac,gdk,test" \
    --run-untagged "false" \
    --locked "false" \
    --access-level "not_protected" \
    --registration-token "REDACTED"

在极狐GitLab 15.10 及更高版本中，您可以在 UI 中创建 runner 并设置属性，例如标签列表、锁定状态和访问级别。在极狐GitLab 15.11 及更高版本中，当指定具有 glrt- 前缀的 runner 身份验证令牌时，这些属性将不再作为 register 的参数接受。

以下示例显示了新命令：

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --token "REDACTED"

对自动扩展的影响

在自动扩展场景中，例如极狐GitLab Runner Operator 或极狐GitLab Runner Helm Chart，从 UI 生成的 runner 身份验证令牌替换了注册令牌。这意味着相同的 runner 配置在作业之间重用，而不是为每个作业创建一个 runner。特定的 runner 可以通过在 runner 进程启动时生成的唯一系统 ID 进行识别。

通过编程方式创建 runner

在极狐GitLab 15.11 及更高版本中，您可以使用 POST /user/runners REST API 作为已认证用户创建 runner。仅当 runner 配置是动态的或不可重用时才应使用此方法。如果 runner 配置是静态的，您应重用现有 runner 的 runner 身份验证令牌。

有关如何自动化 runner 创建和注册的说明，请参阅教程，自动化 runner 创建和注册。

使用 Helm chart 安装极狐GitLab Runner

在 runner 注册期间无法设置几个 runner 配置选项。这些选项只能在以下情况下进行配置：

  • 在 UI 中创建 runner 时。
  • 使用 user/runners REST API 端点。

以下配置选项不再支持在 values.yaml 中设置：

## 所有这些字段已被弃用，并且如果在极狐GitLab Runner 18.0 及更高版本中指定它们，runner 将无法启动。
## 如果在 runnerRegistrationToken 中指定了 runner 身份验证令牌，注册将成功，但其他值将被忽略。
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true

runnerRegistrationToken 字段替换了 runnerToken 字段。对于 Kubernetes 上的极狐GitLab Runner，Helm 部署将 runner 身份验证令牌 传递给 runner 工作 pod 并创建 runner 配置。在极狐GitLab 17.0 中，如果 Kubernetes 托管的 runner 附加到 JihuLab.com 使用 runnerRegistrationToken，则 runner 工作 pod 在创建时使用不支持的 Registration API 方法。

如果您将 runner 身份验证令牌存储在 密钥 中，您还必须修改它们。

在传统 runner 注册工作流中，字段是通过以下方式指定的：

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "REDACTED" # DEPRECATED, set to ""
  runner-token: ""

在新的 runner 注册工作流中，您必须使用 runner-token 代替：

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "" # need to leave as an empty string for compatibility reasons
  runner-token: "REDACTED"

{{< alert type=”note” >}}

如果您的密钥管理解决方案不允许您为 runner-registration-token 设置空字符串，您可以将其设置为任何字符串。当存在 runner-token 时，将忽略此值。

{{< /alert >}}

已知问题

Pod 名称在 runner 详情页面不可见

当您使用 Helm chart 的新注册工作流注册 runner 时，pod 名称不会显示在 runner 详情页面上。

runner 身份验证令牌在旋转时不更新

在多个 runner 管理器中注册相同 runner 时的令牌旋转

当您通过新工作流在多个主机机器上注册 runner 时，只有第一个 runner 管理器会收到新令牌。其余的 runner 管理器继续使用无效令牌并断开连接。您必须手动更新这些管理器以使用新令牌。

极狐GitLab Operator 中的令牌旋转

在通过极狐GitLab Operator 使用新工作流注册 runner 时，Custom Resource Definition 中的 runner 身份验证令牌在令牌旋转期间不会更新。这种情况发生在：