迁移到新的 runner 注册工作流

在 GitLab 16.0 中，我们引入了一个新的 runner 创建工作流，它使用 runner 认证令牌来注册 runner。使用注册令牌的旧工作流已被弃用，并计划在 GitLab 20.0 中移除。请改用 runner 创建工作流。

有关新工作流当前开发状态的信息，请参阅 epic 7663。

有关新架构的技术设计和原因，请参阅 Next GitLab Runner Token Architecture。

如果您在使用新的 runner 注册工作流时遇到问题或有顾虑，或者需要更多信息，请在 反馈问题 中告诉我们。

新的 runner 注册工作流

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

1. 在 GitLab UI 中直接 创建 runner 或 以编程方式 创建。
2. 获取 runner 认证令牌。
3. 在使用此配置注册 runner 时，使用 runner 认证令牌替代注册令牌。在多个主机上注册的 runner 管理器在 GitLab UI 中显示为同一个 runner，但带有标识性的系统 ID。

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

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

计划变更的时间框架

• 在 GitLab 15.10 及更高版本中，您可以使用新的 runner 注册工作流。
• 在 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 注册工作流中，将注册令牌替换为认证令牌。

在 GitLab 17.0 之后使用注册令牌

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

• 在 GitLab.com 上，您可以在顶级群组设置中手动 启用传统的 runner 注册流程。
• 在 GitLab Self-Managed 上，您可以在 Admin 区域设置中手动 启用传统的 runner 注册流程。

对现有 runner 的影响

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

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

gitlab-runner register 命令语法变更

gitlab-runner register 命令接受 runner 认证令牌而非注册令牌。 您可以从 Admin 区域的 Runners 页面生成令牌。 runner 认证令牌可以通过其 glrt- 前缀识别。

当您在 GitLab UI 中创建 runner 时，您指定的是之前由 gitlab-runner register 命令提示的命令行选项。 这些命令行选项将来会被弃用。

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

• 使用 --token 命令行选项，gitlab-runner register 命令不接受配置值。
• 使用 --registration-token 命令行选项，gitlab-runner register 命令会忽略配置值。

认证令牌的前缀是 glrt-。

为确保您的自动化工作流受到最小程度的干扰， 如果在传统参数 --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 20.0 及更高版本中指定它们，runner 将无法启动。
## 如果在 runnerRegistrationToken 中指定了 runner 认证令牌，注册将成功，但其他值将被忽略。
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true

对于 Kubernetes 上的 GitLab Runner，Helm 部署会将 runner 认证令牌传递给 runner worker pod 并创建 runner 配置。 在 GitLab 17.0 及更高版本中，如果您在附加到 GitLab.com 的 Kubernetes 托管 runner 上使用 runnerRegistrationToken 令牌字段，runner worker pod 会在创建过程中尝试使用不受支持的 Registration API 方法。

将无效的 runnerRegistrationToken 字段替换为 runnerToken 字段。您还必须修改存储在 secrets 中的 runner 认证令牌。

在传统的 runner 注册工作流中，字段是这样指定的：

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "REDACTED" # 已弃用，设置为 ""
  runner-token: ""

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

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "" # 出于兼容性原因需要留空
  runner-token: "REDACTED"

已知问题

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

当您使用新的注册工作流通过 Helm chart 注册您的 runner 时，pod 名称不会显示在 runner 详情页面上。 更多信息请参阅 issue 423523。

令牌轮换时 Runner 认证令牌不会更新

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

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

GitLab Operator 中的令牌轮换

当通过新工作流使用 GitLab Operator 进行 runner 注册时， 自定义资源定义中的 runner 认证令牌在令牌轮换期间不会更新。 这种情况发生在：

• 您在由 自定义资源定义 引用的秘密中使用 runner 认证令牌（前缀为 glrt-）。
• runner 认证令牌即将过期。 有关 runner 认证令牌过期的更多信息，请参阅 认证令牌安全性。

更多信息请参阅 issue 186。