注册 runners

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

History

引入于极狐GitLab Runner 15.0，对注册请求格式的更改阻止了极狐GitLab Runner 与早期版本的极狐GitLab 通信。您必须使用与极狐GitLab 版本匹配的极狐GitLab Runner 版本，或者升级极狐GitLab 应用程序。

极狐GitLab Runner 注册是将 runner 与一个或多个极狐GitLab 实例链接的过程。您必须注册 runner，以便它可以从极狐GitLab 实例获取作业。

要求#

在注册 runner 之前：

在与极狐GitLab 安装位置不同的服务器上安装极狐GitLab Runner。
对于使用 Docker 注册 runner，在 Docker 容器中安装极狐GitLab Runner。

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

History

引入于极狐GitLab 15.10。

先决条件：

获取一个 runner 身份验证令牌。您可以：
- 创建一个实例, 群组, 或项目 runner。
- 在 config.toml 文件中找到 runner 身份验证令牌。runner 身份验证令牌的前缀为 glrt-。

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

运行注册命令：

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

要使用容器注册，您可以：

使用具有正确配置卷挂载的短生命周期 gitlab-runner 容器：
- 对于本地系统卷挂载：
```
shell
docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
```
  如果您在安装过程中使用了 /srv/gitlab-runner/config 以外的配置卷，请使用正确的卷更新命令。
- 对于 Docker 卷挂载：
```
shell
docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
```

使用活动 runner 容器内的可执行文件：

shell
docker exec -it gitlab-runner gitlab-runner register

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

要在同一主机上注册多个 runner，每个 runner 使用不同的配置，请重复 register 命令。
要在多个主机上注册相同配置，请为每个 runner 注册使用相同的 runner 身份验证令牌。有关更多信息，请参见重用 runner 配置。

您还可以使用非交互模式来使用其他参数注册 runner：

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

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

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

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

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

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

传递 runner 注册令牌和支持某些配置参数的功能在极狐GitLab 15.6 中已弃用。它们计划在极狐GitLab 20.0 中删除。请改用 runner 身份验证令牌。有关更多信息，请参见迁移到新的 runner 注册工作流。

先决条件：

runner 注册令牌必须在 管理员 区域中启用。
在所需的实例, 群组, 或项目上获取一个 runner 注册令牌。

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

运行注册命令：

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

要启动一个短生命周期的 gitlab-runner 容器来注册您在安装过程中创建的容器：

对于本地系统卷挂载：
```
shell
docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
```
如果您在安装过程中使用了 /srv/gitlab-runner/config 以外的配置卷，请使用正确的卷更新命令。

对于 Docker 卷挂载：

shell
docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register

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

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

您还可以使用非交互模式来使用其他参数注册 runner：

shell
1sudo gitlab-runner register \
2  --non-interactive \
3  --url "https://gitlab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --description "docker-runner" \
8  --maintenance-note "自由形式的关于此 runner 的维护者注释" \
9  --tag-list "docker,aws" \
10  --run-untagged="true" \
11  --locked="false" \
12  --access-level="not_protected"

shell
1gitlab-runner register \
2  --non-interactive \
3  --url "https://gitlab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --description "docker-runner" \
8  --maintenance-note "自由形式的关于此 runner 的维护者注释" \
9  --tag-list "docker,aws" \
10  --run-untagged="true" \
11  --locked="false" \
12  --access-level="not_protected"

shell
1.\gitlab-runner.exe register \
2  --non-interactive \
3  --url "https://gitlab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker-windows" \
6  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
7  --description "docker-runner" \
8  --maintenance-note "自由形式的关于此 runner 的维护者注释" \
9  --tag-list "docker,aws" \
10  --run-untagged="true" \
11  --locked="false" \
12  --access-level="not_protected"

shell
1sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
2  --non-interactive \
3  --url "https://gitlab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --description "docker-runner" \
8  --maintenance-note "自由形式的关于此 runner 的维护者注释" \
9  --tag-list "docker,aws" \
10  --run-untagged="true" \
11  --locked="false" \
12  --access-level="not_protected"

shell
1docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
2  --non-interactive \
3  --url "https://gitlab.com/" \
4  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
5  --executor "docker" \
6  --docker-image alpine:latest \
7  --description "docker-runner" \
8  --maintenance-note "自由形式的关于此 runner 的维护者注释" \
9  --tag-list "docker,aws" \
10  --run-untagged="true" \
11  --locked="false" \
12  --access-level="not_protected"

--access-level 创建一个受保护的 runner。
- 对于受保护的 runner，使用参数 --access-level="ref_protected"。
- 对于不受保护的 runner，使用 --access-level="not_protected" 或将值留空。
--maintenance-note 允许添加您可能认为对 runner 维护有帮助的信息。最大长度为 255 个字符。

兼容旧版的注册过程#

History

引入于极狐GitLab 16.2。

runner 注册令牌和多个 runner 配置参数在极狐GitLab 15.6 中已弃用，计划在极狐GitLab 20.0 中删除。为了确保您的自动化工作流程受到最小干扰，如果在遗留参数 --registration-token 中指定了 runner 身份验证令牌，则会触发兼容旧版的注册过程。

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

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

使用配置模板注册#

您可以使用配置模板注册一个具有 register 命令不支持的设置的 runner。

先决条件：

模板文件位置的卷必须挂载在极狐GitLab Runner 容器上。
一个 runner 身份验证或注册令牌：
- 获取一个 runner 身份验证令牌（推荐）。您可以：
  - 创建一个实例, 群组, 或项目 runner。
  - 在 config.toml 文件中找到 runner 身份验证令牌。runner 身份验证令牌的前缀为 glrt-。
- 获取一个 runner 注册令牌（已弃用），用于实例, 群组, 或项目 runner。

对于由于环境限制而不支持某些参数的自动化环境，可以使用配置模板：

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

配置模板仅支持单个 [[runners]] 部分，不支持全局选项。

要注册 runner：

使用 .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"

添加文件的路径。您可以使用：

命令行中的非交互模式：

shell
1$ sudo gitlab-runner register \
2    --template-config /tmp/test-config.template.toml \
3    --non-interactive \
4    --url "https://gitlab.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 命令中添加文件路径。

toml
1concurrent = 1
2check_interval = 0
3
4[session_server]
5  session_timeout = 1800
6
7[[runners]]
8  name = "test-runner"
9  url = "https://gitlab.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。

创建一个项目 runner。

创建一个包含 [[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

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

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

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

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

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

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

使用 Docker 注册 runners#

在您使用 Docker 容器注册 runner 之后：

配置将写入您的配置卷。例如，/srv/gitlab-runner/config。
容器使用配置卷加载 runner。

如果 gitlab-runner restart 在 Docker 容器中运行，极狐GitLab Runner 将启动一个新进程而不是重新启动现有进程。要应用配置更改，请重启 Docker 容器。

故障排除#

检查注册令牌错误#

检查注册令牌错误消息在极狐GitLab 实例无法识别注册过程中输入的 runner 注册令牌时显示。当以下情况发生时，可能会出现此问题：

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

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

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

410 Gone - runner 注册不允许错误#

410 Gone - runner 注册不允许错误消息在禁用通过注册令牌注册 runner 时显示。

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

验证 runner 注册令牌是否有效。
确认实例中的 runner 注册是允许的。
如果是群组或项目 runner 注册令牌，验证相应群组和/或项目中 runner 注册是否允许。

注册 runners

要求#

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

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

兼容旧版的注册过程#

使用配置模板注册#

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

使用 Docker 注册 runners#

故障排除#

检查注册令牌 错误#

410 Gone - runner 注册不允许 错误#

检查注册令牌错误#

410 Gone - runner 注册不允许错误#