注册 Runner

Runner 注册是将 Runner 与一个或多个极狐GitLab 实例关联起来的过程。您必须注册 Runner，以便它能够从极狐GitLab 实例获取作业。

先决条件#

在注册 Runner 之前：

• 在与安装极狐GitLab 的服务器不同的服务器上安装极狐GitLab Runner。
• 如需使用 Docker 注册 Runner，请在 Docker 容器中安装极狐GitLab Runner。

使用 Runner 身份验证令牌注册#

先决条件：

• 获取 Runner 身份验证令牌。您可以：
  • 创建实例、群组或项目 Runner。有关说明，请参阅管理 Runner。
  • 在 config.toml 文件中找到 Runner 身份验证令牌。Runner 身份验证令牌的前缀为 glrt-。

注册 Runner 后，配置会保存到 config.toml。

要使用 Runner 身份验证令牌注册 Runner：

1. 运行注册命令：

shell
   sudo gitlab-runner register

shell
export HTTP_PROXY=http://yourproxyurl:3128
export HTTPS_PROXY=http://yourproxyurl:3128

sudo -E gitlab-runner register

shell
   gitlab-runner register

shell
   .\gitlab-runner.exe register

shell
   sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register

1. 输入您的极狐GitLab URL：
   • 对于极狐GitLab 私有化部署上的 Runner，请使用您的极狐GitLab 实例的 URL。例如， 如果您的项目托管在 gitlab.example.com/yourname/yourproject，则您的极狐GitLab 实例 URL 为 https://gitlab.example.com。
   • 对于 JihuLab.com 上的 Runner，极狐GitLab 实例 URL 为 https://jihulab.com。
2. 输入 Runner 身份验证令牌。
3. 输入 Runner 的描述。
4. 输入作业标签，以逗号分隔。
5. 输入 Runner 的可选维护备注。
6. 输入执行器的类型。

• 要在同一台主机上注册多个 Runner，且每个 Runner 使用不同的配置， 请重复运行 register 命令。
• 要在多台主机上注册相同的配置，请为每次 Runner 注册使用相同的 Runner 身份验证令牌。 有关更多信息，请参阅复用 Runner 配置。

您还可以使用非交互模式，通过附加参数来注册 Runner：

shell
1sudo gitlab-runner register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --token "$RUNNER_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner"

shell
1gitlab-runner register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --token "$RUNNER_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner"

shell
1.\gitlab-runner.exe register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --token "$RUNNER_TOKEN" \
5  --executor "docker-windows" \
6  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner"

shell
1sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --token "$RUNNER_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner"

shell
1docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner registry.gitlab.cn/jihulab/gitlab-runner register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --token "$RUNNER_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner"

使用 Runner 注册令牌注册（已弃用）#

先决条件：

• 必须在管理区域中启用 Runner 注册令牌。
• 在所需的实例、群组或项目获取 Runner 注册令牌。有关说明，请参阅管理 Runner。

注册 Runner 后，配置会保存到 config.toml。

要使用 Runner 注册令牌注册 Runner：

1. 运行注册命令：

shell
   sudo gitlab-runner register

shell
export HTTP_PROXY=http://yourproxyurl:3128
export HTTPS_PROXY=http://yourproxyurl:3128

sudo -E gitlab-runner register

shell
   gitlab-runner register

shell
   .\gitlab-runner.exe register

shell
   sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register

1. 输入您的极狐GitLab URL：
   • 对于极狐GitLab 私有化部署上的 Runner，请使用您的极狐GitLab 实例的 URL。例如， 如果您的项目托管在 gitlab.example.com/yourname/yourproject，则您的极狐GitLab 实例 URL 为 https://gitlab.example.com。
   • 对于 JihuLab.com，极狐GitLab 实例 URL 为 https://jihulab.com。
2. 输入您获取的用于注册 Runner 的令牌。
3. 输入 Runner 的描述。
4. 输入作业标签，以逗号分隔。
5. 输入 Runner 的可选维护备注。
6. 输入执行器的类型。

要在同一台主机上注册多个 Runner，且每个 Runner 使用不同的配置，请重复运行 register 命令。

您还可以使用非交互模式，通过附加参数来注册 Runner：

shell
1sudo gitlab-runner register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner" \
9  --maintenance-note "Free-form maintainer notes about this runner" \
10  --tag-list "docker,aws" \
11  --run-untagged="true" \
12  --locked="false" \
13  --access-level="not_protected"

shell
1gitlab-runner register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner" \
9  --maintenance-note "Free-form maintainer notes about this runner" \
10  --tag-list "docker,aws" \
11  --run-untagged="true" \
12  --locked="false" \
13  --access-level="not_protected"

shell
1.\gitlab-runner.exe register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker-windows" \
6  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner" \
9  --maintenance-note "Free-form maintainer notes about this runner" \
10  --tag-list "docker,aws" \
11  --run-untagged="true" \
12  --locked="false" \
13  --access-level="not_protected"

shell
1sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner" \
9  --maintenance-note "Free-form maintainer notes about this runner" \
10  --tag-list "docker,aws" \
11  --run-untagged="true" \
12  --locked="false" \
13  --access-level="not_protected"

shell
1docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner registry.gitlab.cn/jihulab/gitlab-runner register \
2  --non-interactive \
3  --url "https://jihulab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --docker-pull-policy "if-not-present" \
8  --description "docker-runner" \
9  --maintenance-note "Free-form maintainer notes about this runner" \
10  --tag-list "docker,aws" \
11  --run-untagged="true" \
12  --locked="false" \
13  --access-level="not_protected"

• --access-level 会创建一个受保护的 Runner。
  • 对于受保护的 Runner，请使用 --access-level="ref_protected" 参数。
  • 对于不受保护的 Runner，请使用 --access-level="not_protected" 或不定义该值。
• --maintenance-note 允许添加您认为有助于 Runner 维护的信息。最大长度为 255 个字符。

兼容旧版的注册流程#

Runner 注册令牌和若干 Runner 配置参数已被弃用。它们计划在极狐GitLab 20.0 中移除。为确保对您的自动化工作流造成的影响最小，如果在旧版参数 --registration-token中指定了 Runner 身份验证令牌，则会触发 legacy-compatible registration process。

兼容旧版的注册流程会忽略以下命令行参数。这些参数只能在 UI 中或通过 API 创建 Runner 时配置。

• --locked
• --access-level
• --run-untagged
• --maximum-timeout
• --paused
• --tag-list
• --maintenance-note

使用配置模板注册#

您可以使用配置模板来注册 Runner，并使用 register 命令不支持的设置。

先决条件：

• 模板文件所在位置的卷必须挂载到极狐GitLab Runner 容器上。
• 一个 Runner 身份验证令牌或注册令牌：
  • 获取 Runner 身份验证令牌（推荐）。您可以：
    • 在所需的实例、群组或项目获取 Runner 身份验证令牌。有关说明，请参阅管理 Runner。
    • 在 config.toml 文件中找到 Runner 身份验证令牌。Runner 身份验证令牌的前缀为 glrt-。
  • 获取实例、群组或项目的 Runner 注册令牌（已弃用）。有关说明，请参阅管理 Runner。

配置模板可用于那些由于以下原因而不支持 register 命令中某些参数的自动化环境：

• 基于环境的变量大小限制。
• Kubernetes 的执行器卷不可用的命令行选项。

要注册 Runner：

1. 创建一个 .toml 格式的配置模板文件，并添加您的规格。例如：

   toml
   1[[runners]]
   2  [runners.kubernetes]
   3  [runners.kubernetes.volumes]
   4    [[runners.kubernetes.volumes.empty_dir]]
   5      name = "empty_dir"
   6      mount_path = "/path/to/empty_dir"
   7      medium = "Memory"

2. 添加该文件的路径。您可以使用以下任一方式：

   • 命令行中的非交互模式：

     shell
     1$ sudo gitlab-runner register \
     2    --template-config /tmp/test-config.template.toml \
     3    --non-interactive \
     4    --url "https://jihulab.com" \
     5    --token <TOKEN> \ "# --registration-token if using the deprecated runner registration token"
     6    --name test-runner \
     7    --executor kubernetes
     8    --host = "http://localhost:9876/"

   • .gitlab.yaml 文件中的环境变量：

     yaml
     variables:
       TEMPLATE_CONFIG_FILE = <file_path>

     如果您更新了环境变量，则无需在每次注册时 在 register 命令中添加文件路径。

注册 Runner 后，配置模板中的设置会与在 config.toml中创建的 [[runners]] 条目合并：

toml
1concurrent = 1
2check_interval = 0
3
4[session_server]
5  session_timeout = 1800
6
7[[runners]]
8  name = "test-runner"
9  url = "https://jihulab.com"
10  token = "glrt-<TOKEN>"
11  executor = "kubernetes"
12  [runners.kubernetes]
13    host = "http://localhost:9876/"
14    bearer_token_overwrite_allowed = false
15    image = ""
16    namespace = ""
17    namespace_overwrite_allowed = ""
18    privileged = false
19    service_account_overwrite_allowed = ""
20    pod_labels_overwrite_allowed = ""
21    pod_annotations_overwrite_allowed = ""
22    [runners.kubernetes.volumes]
23
24      [[runners.kubernetes.volumes.empty_dir]]
25        name = "empty_dir"
26        mount_path = "/path/to/empty_dir"
27        medium = "Memory"

模板设置仅针对以下选项进行合并：

• 空字符串
• 空值或不存在的条目
• 零值

命令行参数或环境变量的优先级高于配置模板中的设置。例如，如果模板指定了 docker 执行器，但命令行指定了 shell，则配置的执行器为 shell。

为极狐GitLab 基础版集成测试注册 Runner#

要测试极狐GitLab 基础版集成，请使用配置模板注册一个 带有受限 Docker 执行器的 Runner。

1. 创建一个项目 Runner。

2. 创建一个包含 [[runners.docker.services]] 部分的模板：

   shell
   1$ cat > /tmp/test-config.template.toml << EOF
   2[[runners]]
   3[runners.docker]
   4[[runners.docker.services]]
   5name = "mysql:latest"
   6[[runners.docker.services]]
   7name = "redis:latest"
   8
   9EOF

3. 注册 Runner：

shell
1   sudo gitlab-runner register \
2     --non-interactive \
3     --url "https://jihulab.com" \
4     --token "$RUNNER_AUTHENTICATION_TOKEN" \
5     --template-config /tmp/test-config.template.toml \
6     --description "gitlab-ce-ruby-3.1" \
7     --executor "docker" \
8     --docker-image ruby:3.1

shell
1   gitlab-runner register \
2     --non-interactive \
3     --url "https://jihulab.com" \
4     --token "$RUNNER_AUTHENTICATION_TOKEN" \
5     --template-config /tmp/test-config.template.toml \
6     --description "gitlab-ce-ruby-3.1" \
7     --executor "docker" \
8     --docker-image ruby:3.1

shell
1   .\gitlab-runner.exe register \
2     --non-interactive \
3     --url "https://jihulab.com" \
4     --token "$RUNNER_AUTHENTICATION_TOKEN" \
5     --template-config /tmp/test-config.template.toml \
6     --description "gitlab-ce-ruby-3.1" \
7     --executor "docker" \
8     --docker-image ruby:3.1

shell
1   sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
2     --non-interactive \
3     --url "https://jihulab.com" \
4     --token "$RUNNER_AUTHENTICATION_TOKEN" \
5     --template-config /tmp/test-config.template.toml \
6     --description "gitlab-ce-ruby-3.1" \
7     --executor "docker" \
8     --docker-image ruby:3.1

shell
1   docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner registry.gitlab.cn/jihulab/gitlab-runner register \
2     --non-interactive \
3     --url "https://jihulab.com" \
4     --token "$RUNNER_AUTHENTICATION_TOKEN" \
5     --template-config /tmp/test-config.template.toml \
6     --description "gitlab-ce-ruby-3.1" \
7     --executor "docker" \
8     --docker-image ruby:3.1

有关更多配置选项，请参阅高级配置。

使用 Docker 注册 Runner#

使用 Docker 容器注册 Runner 后：

• 配置会写入您的配置卷。例如，/srv/gitlab-runner/config。
• 容器使用该配置卷来加载 Runner。

故障排除#

错误：Check registration token#

当极狐GitLab 实例无法识别注册期间输入的 Runner 注册令牌时，会显示 check registration token 错误消息。此问题可能在以下情况下发生：

• 实例、群组或项目 Runner 注册令牌已在极狐GitLab 中更改。
• 输入了错误的 Runner 注册令牌。

出现此错误时，您可以请极狐GitLab 管理员：

• 验证 Runner 注册令牌是否有效。
• 确认项目或群组中的 Runner 注册已获允许。

错误：410 Gone - runner registration disallowed#

当通过注册令牌进行的 Runner 注册已被禁用时，会显示 410 Gone - runner registration disallowed 错误消息。

出现此错误时，您可以请极狐GitLab 管理员：

• 验证 Runner 注册令牌是否有效。
• 确认实例中的 Runner 注册已获允许。
• 对于群组或项目 Runner 注册令牌，请验证相应群组 和/或项目中的 Runner 注册已获允许。