先决条件
使用 runner 认证令牌注册
使用 runner 注册令牌注册（已弃用）
- 与传统注册兼容的注册流程
使用配置模板注册
使用 Docker 注册 runner
故障排查
- Check registration token 错误
- 410 Gone - runner registration disallowed 错误

注册 Runner

引入于极狐GitLab Runner 15.0，对注册请求格式做了更改，防止极狐GitLab Runner 与低于 14.8 版本的极狐GitLab 通信。您必须使用适合极狐GitLab 版本的 Runner 版本，或升级极狐GitLab 应用程序。

Runner 注册是将 Runner 与一个或多个极狐GitLab 实例连接起来的过程。您必须注册 runner 来让其从极狐GitLab 实例获取 CI/CD 作业。

先决条件

在没有安装极狐GitLab 的服务器上安装 Runner。
如用 Docker 进行 runner 注册, 须在 Docker 容器中安装极狐GitLab Runner。

使用 runner 认证令牌注册

自极狐GitLab 15.10 引入。

先决条件:

如要获取 runner 认证令牌，您可以：
- 创建一个实例、群组或项目 runner。
- 在 config.toml 文件中定位至 runner 认证令牌。Runner 认证令牌以 glrt- 为前缀。

当您注册 runner 以后，配置会被保存到 config.toml 文件中。

使用 runner 认证令牌注册 runner：

运行注册命令：

::Tabs

:::TabTitle Linux

sudo gitlab-runner register

如果您在代理后面，添加环境变量再运行注册命令：

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

sudo -E gitlab-runner register

:::TabTitle macOS

gitlab-runner register

:::TabTitle Windows

.\gitlab-runner.exe register

:::TabTitle FreeBSD

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

:::TabTitle Docker

如果是容器化注册，您可以： - 使用一个短生命周期的 gitlab-runner 容器，并正确的配置卷挂载： - 本地系统卷挂载：

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

如果您在安装过程中使用的配置卷不是 `/srv/gitlab-runner/config`，请使用正确的卷更新命令。

Docker 卷挂载：

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

在激活的 runner 容器中执行注册命令：

docker exec -it gitlab-runner gitlab-runner register

::EndTabs

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

如要在同一个宿主机上注册多个 runner，每个 runner 都要有不同的配置，重复 register 命令即可。
如要在多个宿主机上注册相同配置的 runner，使用相同的 runner 认证令牌进行每个 runner 注册。更多信息请参阅复用 runner 配置。

您还可以使用非交互式模式来在 runner 注册过程中添加额外的参数：

::Tabs

:::TabTitle Linux

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

:::TabTitle macOS

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

:::TabTitle Windows

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner"

:::TabTitle FreeBSD

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

:::TabTitle Docker

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

::EndTabs

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

为特定配置参数传递 runner 注册令牌和某些配置参数的方法已在极狐GitLab 15.6 中被弃用。将在极狐GitLab 18.0 中被彻底移除。取而代之的是 runner 认证令牌。更多详情可以查看迁移到新的 runner 注册工作流。

先决条件：

必须在管理中心中开启了 Runner 认证令牌
在期望的实例、群组或项目中获取 runner 认证令牌。

当您注册 runner 以后，配置会被保存到 config.toml 文件中。

使用 runner 认证令牌注册 runner：

运行注册命令：

::Tabs

:::TabTitle Linux

sudo gitlab-runner register

如果您在代理后面，添加环境变量再运行注册命令：

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

sudo -E gitlab-runner register

:::TabTitle macOS

gitlab-runner register

:::TabTitle Windows

.\gitlab-runner.exe register

:::TabTitle FreeBSD

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

:::TabTitle Docker

使用一个短生命周期的 gitlab-runner 容器，并正确的配置卷挂载：

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

对于 Docker 卷挂载：

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

::EndTabs

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

To register multiple runners on the same host machine, each with a different configuration, repeat the register command.

如要在同一个宿主机上注册多个 runner，每个 runner 都要有不同的配置，重复 register 命令即可。

您还可以使用非交互式模式来在 runner 注册过程中添加额外的参数：

::Tabs

:::TabTitle Linux

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

:::TabTitle macOS

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

:::TabTitle Windows

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

:::TabTitle FreeBSD

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

:::TabTitle Docker

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

::EndTabs

--access-level creates a protected runner.
--access-level 创建了一个受保护的 Runner。
- 对于受保护的 Runner，请使用 --access-level="ref_protected" 参数。
- 对于未受保护的 Runner，请使用 --access-level="not_protected" 或保留未定义的值。
--maintenance-note 允许添加与 runner 维护相关的信息。最大长度为 255 个字符。

与传统注册兼容的注册流程

自极狐GitLab 16.2 引入。

Runner 注册令牌和一些 Runner 配置参数在 15.6 中已弃用，并将在 18.0 中被彻底删除。为了最小化对自动化工作流程的干扰，如果 runner 认证令牌通过传统命令 --registration-token 被指定，则会触发 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。
  - 在 config.toml 文件中定位至 runner 认证令牌处。Runner 认证令牌有一个 glrt- 前缀。
- 获取实例、群组或项目 runner 注册令牌（已弃用）

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

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

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

要注册 runner：

创建 .toml 格式的配置模板文件并添加您的配置内容。比如：

[[runners]]
  [runners.kubernetes]
  [runners.kubernetes.volumes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty_dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"

在文件中添加路径。您可以：

非交互模式下，在命令行执行：

$ sudo gitlab-runner register \
    --template-config /tmp/test-config.template.toml \
    --non-interactive \
    --url "https://gitlab.com" \
    --token <TOKEN> \ "# --registration-token if using the deprecated runner registration token"
    --name test-runner \
    --executor kubernetes
    --host = "http://localhost:9876/"

在 .gitlab-ci.yaml 文件中添加环境变量：
```
variables:
  TEMPLATE_CONFIG_FILE = <file_path>
```
如果您更新了环境变量，每次当您注册时，您无需将文件路径添加到 register 命令中。

当您注册 runner 后，配置模板中的设置就会和 config.toml 文件中的 [[runners]] 部分进行合并：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://gitlab.com"
  token = "glrt-<TOKEN>"
  executor = "kubernetes"
  [runners.kubernetes]
    host = "http://localhost:9876/"
    bearer_token_overwrite_allowed = false
    image = ""
    namespace = ""
    namespace_overwrite_allowed = ""
    privileged = false
    service_account_overwrite_allowed = ""
    pod_labels_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    [runners.kubernetes.volumes]

      [[runners.kubernetes.volumes.empty_dir]]
        name = "empty_dir"
        mount_path = "/path/to/empty_dir"
        medium = "Memory"

Template settings are merged only for options that are: 模板设置仅合并以下选项：

空字符
Null 或非存在条目
零值

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

使用 Docker 注册 runner

After you register the runner with a Docker container:

在您使用 Docker 注册 runner 后：

配置文件被写入您的配置卷。比如，/srv/gitlab-runner/config。
容器使用配置卷来加载 runner。

如果在 Docker 容器中执行 gitlab-runner restart 命令，runner 会启动一个新的进程，而不是重启现有的进程。如要让配置更改生效，您必须重启 Docker 容器。

故障排查

`Check registration token` 错误

当在注册期间输入的 runner 注册令牌不被极狐GitLab 实例所认可时，就会出现 check registration token 错误。当发生以下情况时，就会出现该问题：

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

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

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

`410 Gone - runner registration disallowed` 错误

当禁用 runner 注册令牌时，就会出现 410 Gone - runner registration disallowed 错误。

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

验证 runner 注册令牌是否有效。
确认 runner 注册在实例上是被允许的。
在群组或项目 runner 注册令牌允许的范围内，确认 runner 注册在群组或项目上是被允许的。

注册 Runner

先决条件

使用 runner 认证令牌注册

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

与传统注册兼容的注册流程

使用配置模板注册

使用 Docker 注册 runner

故障排查

Check registration token 错误

410 Gone - runner registration disallowed 错误

`Check registration token` 错误

`410 Gone - runner registration disallowed` 错误