先决条件
Docker
Linux
macOS
Windows
FreeBSD
单行注册命令
- 使用身份验证令牌注册在 UI 中创建的 Runner
- 使用注册令牌注册 Runner（已弃用）
  - 兼容旧版的注册处理
Check registration token 错误
[[runners]] 配置模板文件
- 示例

注册 Runner (BASIC ALL)

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

Runner 注册是将 Runner 与一个或多个极狐GitLab 实例连接起来的过程。

您可以通过重复 register 命令，在同一台主机上注册多个 Runner，每个都有不同的配置。

先决条件

在没有安装极狐GitLab 的服务器上安装 Runner。
创建 Runner

如果是在 JihuLab.com 上注册 Runner，则 gitlab-ci coordinator URL 是 https://jihulab.com。

Docker

先决条件：

在容器中安装极狐GitLab Runner。

以下步骤描述了启动暂时的 gitlab-runner 容器以注册您在安装期间创建的容器。注册完成后，生成的配置将写入您选择的配置卷（例如，/srv/gitlab-runner/config）并且由 Runner 使用配置卷进行加载。

使用 Docker 容器注册 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
```
输入您的极狐GitLab 实例 URL（也称为 gitlab-ci coordinator URL）。
输入注册 Runner 时获取的令牌。
输入 Runner 描述。您可以在极狐GitLab UI 中进行变更。
输入以逗号隔开的与 Runner 有关的标签，您可以后续在极狐GitLab UI 中进行变更。
为 Runner 输入可选的维护记录。
提供 Runner 执行器。对于大多数用例来说，输入 docker。
如果您输入 docker 作为执行器。对于在 .gitlab-ci.yml 中没有定义镜像的项目，系统会要求您使用默认镜像。

Linux

在 Linux 下注册 Runner：

运行以下命令：

sudo gitlab-runner register

如果您使用代理，您需要添加环境变量再运行注册命令：

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

sudo -E gitlab-runner register

输入您的极狐GitLab 实例 URL（也称为 gitlab-ci coordinator URL）。
输入注册 Runner 时获取的令牌。
输入 Runner 描述。您可以在极狐GitLab UI 中进行变更。
输入以逗号隔开的与 Runner 有关的标签，您可以后续在极狐GitLab UI 中进行变更。
为 Runner 输入可选的维护记录。
提供 Runner 执行器。对于大多数用例来说，输入 docker。
如果您输入 docker 作为执行器。对于在 .gitlab-ci.yml 中没有定义镜像的项目，系统会要求您使用默认镜像。

macOS

在 macOS 下注册 Runner 之前安装 Docker.app。

在 macOS 下注册 Runner：

运行以下命令：
```
gitlab-runner register
```
输入您的极狐GitLab 实例 URL（也称为 gitlab-ci coordinator URL）。
输入注册 Runner 时获取的令牌。
输入 Runner 描述。您可以在极狐GitLab UI 中进行变更。
输入以逗号隔开的与 Runner 有关的标签，您可以后续在极狐GitLab UI 中进行变更。
为 Runner 输入可选的维护记录。
提供 Runner 执行器。对于大多数用例来说，输入 docker。
如果您输入 docker 作为执行器。对于在 .gitlab-ci.yml 中没有定义镜像的项目，系统会要求您使用默认镜像。

Windows

在 Windows 下注册 Runner：

运行以下命令：
```
.\gitlab-runner.exe register
```
输入您的极狐GitLab 实例 URL（也称为 gitlab-ci coordinator URL）。
输入注册 Runner 时获取的令牌。
输入 Runner 描述。您可以在极狐GitLab UI 中进行变更。
输入以逗号隔开的与 Runner 有关的标签，您可以后续在极狐GitLab UI 中进行变更。
为 Runner 输入可选的维护记录。
提供 Runner 执行器。对于大多数用例来说，输入 docker。
如果您输入 docker 作为执行器。对于在 .gitlab-ci.yml 中没有定义镜像的项目，系统会要求您使用默认镜像。

FreeBSD

在 FreeBSD 下注册 Runner：

运行以下命令：

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

输入您的极狐GitLab 实例 URL（也称为 gitlab-ci coordinator URL）。
输入注册 Runner 时获取的令牌。
输入 Runner 描述。您可以在极狐GitLab UI 中进行变更。
输入以逗号隔开的与 Runner 有关的标签，您可以后续在极狐GitLab UI 中进行变更。
为 Runner 输入可选的维护记录。
提供 Runner 执行器。对于大多数用例来说，输入 docker。
如果您输入 docker 作为执行器。对于在 .gitlab-ci.yml 中没有定义镜像的项目，系统会要求您使用默认镜像。

单行注册命令

如果您想使用非交互模式注册 Runner，您可以使用 register 子命令，或使用其等效环境变量。

要显示所有 register 子命令列表，请运行以下命令：

gitlab-runner register -h

使用身份验证令牌注册在 UI 中创建的 Runner

引入于极狐GitLab Runner 15.10。

使用最常见的选项注册 Runner，您应该：

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

如果您在 Docker 容器中运行 Runner，请运行结构类似于以下示例的 register 命令：

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

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

弃用于极狐GitLab 15.6。

此功能已在 15.6 中被弃用，并计划在 17.0 中移除。这是个突破性的变化。在 16.2 及更高版本中，如果在注册期间传递了已弃用的参数，则在兼容旧版的注册过程中会自动忽略这些参数。有关更多信息，请参阅兼容旧版的注册流程。

要使用最常见的选项注册 Runner，请运行 register 命令，其结构类似于以下示例：

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"

如果您在 Docker 容器中运行 Runner，register 命令的结构类似于：

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --executor "docker" \
  --docker-image alpine:latest \
  --url "https://jihulab.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --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"

极狐GitLab Runner 12.0 中添加了 --access-level 参数。在注册过程中使用此参数创建受保护的 Runner。对于受保护的 Runner，请使用 --access-level="ref_protected" 参数。对于未受保护的 Runner，请使用 --access-level="not_protected" 或保留未定义的值。您稍后可以在项目的 设置 > CI/CD 菜单中打开或关闭此值。

兼容旧版的注册处理

注册令牌和一些 Runner 配置参数在 15.6 中已弃用，并将在 17.0 中删除。

为了最小化对自动化工作流程的干扰，如果在旧参数 --registration-token 中指定了身份验证令牌，则会触发 legacy-compatible registration process。此过程会导致以下命令行参数被忽略。仅当在 UI 中或使用 API 创建 Runner 时才能配置这些参数。

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

`Check registration token` 错误

当极狐GitLab 实例无法识别输入的注册令牌时会显示 check registration token 错误消息。当在极狐GitLab 中变更了实例组或项目注册令牌或用户未正确输入注册令牌的时候可能会出现此问题。

发生此错误时，极狐GitLab 管理员首先要验证注册令牌是否有效。

此外，请确认极狐GitLab 管理员允许在项目或群组中注册 Runner。

`[[runners]]` 配置模板文件

引入于极狐GitLab Runner 12.2。

某些 Runner 配置无法使用环境变量或命令行选项进行设置。

例如：

环境变量不支持切片。
整个 Kubernetes 执行器卷树故意不支持命令行选项。
对于由任何类型的自动化处理的环境来说，这都是一个问题。例如极狐GitLab Runner 官方 Helm Chart。在这种情况下，唯一的解决方案是在 Runner 注册后手动更新 config.toml 文件。这种方法不太理想，容易出错且不可靠。尤其是安装一个极狐GitLab Runner 却进行了不止一次注册的时候。

这个问题可以通过使用配置模板文件来解决。

使用配置模板文件，请使用以下内容将文件的路径传递给 register：

--template-config 命令行选项。
TEMPLATE_CONFIG_FILE 环境变量。
配置模板文件支持：
只有一个 [[runners]] 部分。
没有全局选项。

当使用 --template-config 或 TEMPLATE_CONFIG_FILE 时，[[runners]] 条目的配置被合并到常规 config.toml 文件中新创建的 [[runners]] 条目的配置中。

仅合并空选项。也就是：

空字符串。
空/不存在的条目。
零。
因此：
所有在 register 命令调用中使用命令行选项和/或环境变量提供的配置都进行了优先。
模板填补了空白并添加了额外的设置。

示例

我们向某个测试项目注册基于 Kubernetes 执行器的 Runner，然后查看 config.toml 文件：

$ sudo gitlab-runner register \
     --config /tmp/test-config.toml \
     --non-interactive \
     --url https://gitlab.com \
     --registration-token __REDACTED__ \
     --name test-runner \
     --tag-list kubernetes,test \
     --locked \
     --paused \
     --executor kubernetes \
     --kubernetes-host http://localhost:9876/

Runtime platform                                    arch=amd64 os=linux pid=1684 revision=436955cb version=15.11.0

Registering runner... succeeded                     runner=__REDACTED__
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

以上命令创建以下 config.toml 文件：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://jihulab.com"
  token = "__REDACTED__"
  executor = "kubernetes"
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
  [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]

我们可以看到从提供的命令行选项创建的基本配置：

Runner 证书（URL 和令牌）。
指定的执行器。
默认的空白部分 runners.kubernetes，在填写注册时只提供一个选项。

通常，必须设置更多选项才能使 Kubernetes 执行器可用，但以上选项对于我们的示例来说已经足够了。

假设我们必须为 Kubernetes 执行器配置 emptyDir 卷。我们无法在既不使用环境变量也不使用命令行选项进行注册时添加它。我们必须手动将这样的内容附加到文件末尾：

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

因为 TOML 不需要适当的缩进（取决于条目排序），我们可以将所需的更改附加到文件末尾。

但是，当在 config.toml 文件中注册更多的 [[runners]] 部分时，这件事会很难办。如果新建的总是在最末尾，就会有风险。在极狐GitLab Runner 12.2 中，使用 --template-config 标记，解决上述问题。

$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
  [runners.kubernetes]
    [runners.kubernetes.volumes]
      [[runners.kubernetes.volumes.empty_dir]]
        name = "empty_dir"
        mount_path = "/path/to/empty_dir"
        medium = "Memory"
EOF

有了这个文件，我们现在可以尝试再次注册 Runner，但这次添加 --template-config /tmp/test-config.template.toml 选项。除了这个变化，其余注册命令完全相同：

$ sudo gitlab-runner register \
     --config /tmp/test-config.toml \
     --template-config /tmp/test-config.template.toml \
     --non-interactive \
     --url https://gitlab.com \
     --registration-token __REDACTED__ \
     --name test-runner \
     --tag-list kubernetes,test \
     --locked \
     --paused \
     --executor kubernetes \
     --kubernetes-host http://localhost:9876/

Runtime platform                                    arch=amd64 os=linux pid=8798 revision=436955cb version=15.11.0

Registering runner... succeeded                     runner=__REDACTED__
Merging configuration from template file
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

我们可以看到，注册命令的输出有一点变化。我们可以看到 Merging configuration from template file 行。

现在让我们看看使用模板后的配置文件：：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://jihulab.com"
  token = "__REDACTED__"
  executor = "kubernetes"
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
  [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"

我们可以看到，配置与以前几乎相同。唯一的变化是现在它拥有 [[runners.kubernetes.volumes.empty_dir]] 条目，且其选项在文件末尾。它被添加到由注册创建的 [[runners]] 条目中。因为整个文件是用同样的机制保存的，所以我们也有适当的缩进。

如果配置模板包含一个设置，并且相同的设置被传递给 register 命令，传递给 register 命令的设置优先于配置模板中指定的设置。

$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
  executor = "docker"
EOF

$ sudo gitlab-runner register \
     --config /tmp/test-config.toml \
     --template-config /tmp/test-config.template.toml \
     --non-interactive \
     --url https://gitlab.com \
     --registration-token __REDACTED__ \
     --name test-runner \
     --tag-list shell,test \
     --locked \
     --paused \
     --executor shell

Runtime platform                                    arch=amd64 os=linux pid=12359 revision=436955cb version=15.11.0

Registering runner... succeeded                     runner=__REDACTED__
Merging configuration from template file
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

如我们所见，注册命令指定了 shell 执行器，而模板包含 docker 执行器。我们来看看最终的配置内容：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://jihulab.com"
  token = "__REDACTED__"
  executor = "shell"
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]

使用 register 命令选项设置的配置具有优先权，并且被放置在最终配置中。

注册 Runner (BASIC ALL)

先决条件

Docker

Linux

macOS

Windows

FreeBSD

单行注册命令

使用身份验证令牌注册在 UI 中创建的 Runner

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

兼容旧版的注册处理

Check registration token 错误

[[runners]] 配置模板文件

示例

`Check registration token` 错误

`[[runners]]` 配置模板文件