极狐GitLab Runner 命令 - GitLab Runner

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，极狐GitLab 私有化部署

极狐GitLab Runner 包含一组命令，您可以使用这些命令来注册、管理和运行构建。

您可以通过执行以下命令来查看命令列表：

shell
gitlab-runner --help

在命令后附加 --help 以查看其特定的帮助页面：

shell
gitlab-runner <command> --help

使用环境变量#

大多数命令支持使用环境变量作为向命令传递配置的方式。

当为特定命令调用 --help 时，您可以看到环境变量的名称。例如，您可以在下方看到 run 命令的帮助信息：

shell
gitlab-runner run --help

输出类似于：

plaintext
1NAME:
2   gitlab-runner run - run multi runner service
3
4USAGE:
5   gitlab-runner run [command options] [arguments...]
6
7OPTIONS:
8   -c, --config "/Users/ayufan/.gitlab-runner/config.toml"      Config file [$CONFIG_FILE]

以调试模式运行#

当您查找未定义行为或错误的原因时，请使用调试模式。

要以调试模式运行命令，请在命令前加上 --debug：

shell
gitlab-runner --debug <command>

超级用户权限#

访问极狐GitLab Runner 配置的命令在以超级用户（root）身份执行时行为会有所不同。文件位置取决于执行命令的用户。

当您执行 gitlab-runner 命令时，您会看到其运行的模式：

shell
1$ gitlab-runner run
2
3INFO[0000] Starting multi-runner from /Users/ayufan/.gitlab-runner/config.toml ...  builds=0
4WARN[0000] Running in user-mode.
5WARN[0000] Use sudo for system-mode:
6WARN[0000] $ sudo gitlab-runner...

如果您确定这是您想要使用的模式，则应使用 user-mode。否则，请在您的命令前加上 sudo：

shell
$ sudo gitlab-runner run

INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml ...  builds=0
INFO[0000] Running in system-mode.

在 Windows 的情况下，您可能需要以管理员身份运行命令提示符。

配置文件#

极狐GitLab Runner 配置使用 TOML 格式。

您可以在以下位置找到需要编辑的文件：

在 *nix 系统上，当极狐GitLab Runner 以超级用户（root）身份执行时：/etc/gitlab-runner/config.toml
在 *nix 系统上，当极狐GitLab Runner 以非 root 身份执行时：~/.gitlab-runner/config.toml
在其他系统上：./config.toml

大多数命令接受一个参数来指定自定义配置文件，因此您可以在单台机器上拥有多个不同的配置。要指定自定义配置文件，请使用 -c 或 --config 标志，或使用 CONFIG_FILE 环境变量。

信号#

您可以使用系统信号与极狐GitLab Runner 交互。以下命令支持以下信号：

命令	信号	操作
register	SIGINT	取消 Runner 注册，如果已注册则删除。
run, run-single	SIGINT, SIGTERM	中止所有正在运行的构建并尽快退出。使用两次可立即退出（强制关闭）。
run, run-single	SIGQUIT	停止接受新的构建。在正在运行的构建完成后尽快退出（优雅关闭）。
run	SIGHUP	强制重新加载配置文件。

例如，要强制重新加载 Runner 的配置文件，请运行：

shell
sudo kill -SIGHUP <main_runner_pid>

对于优雅关闭：

shell
sudo kill -SIGQUIT <main_runner_pid>

如果您使用 shell 或 docker 执行器，请勿使用 killall 或 pkill 进行优雅关闭。这可能导致子进程也被终止，从而造成信号处理不当。请仅在处理作业的主进程上使用它。

某些操作系统配置为在服务失败时自动重启服务（这是某些平台的默认设置）。如果您的操作系统具有此配置，则当 Runner 被上述信号关闭时，它可能会自动重启。

命令概览#

如果您不带任何参数运行 gitlab-runner，您将看到以下内容：

plaintext
1NAME:
2   gitlab-runner - a GitLab Runner
3
4USAGE:
5   gitlab-runner [global options] command [command options] [arguments...]
6
7VERSION:
8   17.10.1 (ef334dcc)
9
10AUTHOR:
11   GitLab Inc. <support@gitlab.com>
12
13COMMANDS:
14   list                  List all configured runners
15   run                   run multi runner service
16   register              register a new runner
17   reset-token           reset a runner's token
18   install               install service
19   uninstall             uninstall service
20   start                 start service
21   stop                  stop service
22   restart               restart service
23   status                get status of a service
24   run-single            start single runner
25   unregister            unregister specific runner
26   verify                verify all registered runners
27   wrapper               start multi runner service wrapped with gRPC manager server
28   fleeting              manage fleeting plugins
29   artifacts-downloader  download and extract build artifacts (internal)
30   artifacts-uploader    create and upload build artifacts (internal)
31   cache-archiver        create and upload cache artifacts (internal)
32   cache-extractor       download and extract cache artifacts (internal)
33   cache-init            changed permissions for cache paths (internal)
34   health-check          check health for a specific address
35   proxy-exec            execute internal commands (internal)
36   read-logs             reads job logs from a file, used by kubernetes executor (internal)
37   help, h               Shows a list of commands or help for one command
38
39GLOBAL OPTIONS:
40   --cpuprofile value           write cpu profile to file [$CPU_PROFILE]
41   --debug                      debug mode [$RUNNER_DEBUG]
42   --log-format value           Choose log format (options: runner, text, json) [$LOG_FORMAT]
43   --log-level value, -l value  Log level (options: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
44   --help, -h                   show help
45   --version, -v                print the version

下面我们详细解释每个命令的作用。

使用以下命令注册新的 Runner，或列出并验证它们是否仍处于注册状态。

gitlab-runner register
- 交互式注册
- 非交互式注册
gitlab-runner list
gitlab-runner verify
gitlab-runner unregister

这些命令支持以下参数：

参数	默认值	描述
--config	参见配置文件部分	指定要使用的自定义配置文件

gitlab-runner register#

此命令通过使用极狐GitLab Runners API 在极狐GitLab 中注册您的 Runner。

注册的 Runner 会被添加到配置文件中。您可以在单个极狐GitLab Runner 安装中使用多个配置。执行 gitlab-runner register 会添加一个新的配置条目，而不会移除之前的条目。

您可以通过以下方式注册 Runner：

交互式。
非交互式。

Runner 可以直接使用极狐GitLab Runners API 注册，但不会自动生成配置。

交互式注册#

此命令通常以交互模式（默认）使用。在 Runner 注册过程中，系统会向您提出多个问题。

您可以通过在调用注册命令时添加参数来预填这些问题：

shell
gitlab-runner register --name my-runner --url "http://gitlab.example.com" --token my-authentication-token

或者在 register 命令之前配置环境变量：

shell
export CI_SERVER_URL=http://gitlab.example.com
export RUNNER_NAME=my-runner
export CI_SERVER_TOKEN=my-authentication-token
gitlab-runner register

要检查所有可能的参数和环境，请执行：

shell
gitlab-runner register --help

非交互式注册#

可以在非交互式/无人值守模式下使用注册。

您可以在调用注册命令时指定参数：

shell
gitlab-runner register --non-interactive <other-arguments>

或者在 register 命令之前配置环境变量：

shell
<other-environment-variables>
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register

布尔参数必须在命令行中使用 --key={true|false} 传递。

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

在 Runner 注册期间，可以使用配置模板文件功能配置其他选项。

gitlab-runner list#

此命令列出保存在配置文件中的所有 Runner。

gitlab-runner lint#

此命令验证配置文件而不启动 Runner。它会报告：

TOML 语法错误。
内置 JSON schema 验证检测到的语义错误。
未知或拼写错误的键（例如，buids_dir 而不是 builds_dir，或 [[runner.kubernetes...]] 而不是 [[runners.kubernetes...]]），TOML 解码器通常会静默忽略这些错误。

如果发现上述任何问题，或者配置文件不存在，该命令将以非零状态退出。与 run 和 register 不同，lint 将配置文件缺失视为严重错误。

在重启 Runner 之前或在 CI 中使用 lint 验证配置：

shell
gitlab-runner lint --config /etc/gitlab-runner/config.toml

gitlab-runner verify#

此命令验证已注册的 Runner 是否可以连接到极狐GitLab。但它不验证 Runner 是否被极狐GitLab Runner 服务使用。示例输出如下：

plaintext
Verifying runner... is alive                        runner=fee9938e
Verifying runner... is alive                        runner=0db52b31
Verifying runner... is alive                        runner=826f687f
Verifying runner... is alive                        runner=32773c0f

使用 --token 标志验证单个 Runner，而不是所有已注册的 Runner。将 --token 与 --url 结合使用，还可以匹配 Runner 的极狐GitLab 实例 URL：

shell
gitlab-runner verify --url "https://gitlab.example.com" --token my-authentication-token

与其他极狐GitLab Runner 命令不同，verify 的 --url 和 --token 标志不会读取 CI_SERVER_URL 和 CI_SERVER_TOKEN 环境变量。请在命令行中设置这些标志以选择 Runner。

要移除已从极狐GitLab 中删除的旧 Runner，请执行以下命令。

此操作无法撤销。它会更新配置文件，因此请确保在执行前备份 config.toml。

shell
gitlab-runner verify --delete

gitlab-runner unregister#

此命令通过使用极狐GitLab Runners API 注销已注册的 Runner。

它需要以下任一信息：

完整的 URL 和 Runner 的令牌。
Runner 的名称。

使用 --all-runners 选项，它将注销所有附加的 Runner。

Runner 可以使用极狐GitLab Runners API 注销，但不会为用户修改配置。

如果 Runner 是使用 Runner 注册令牌创建的，则使用 Runner 身份验证令牌的 gitlab-runner unregister 会删除该 Runner。
如果 Runner 是在极狐GitLab UI 中或通过 Runners API 创建的，则使用 Runner 身份验证令牌的 gitlab-runner unregister 会删除 Runner 管理器，但不会删除 Runner。要完全移除 Runner，请在 Runner 管理页面中删除该 Runner 或使用 DELETE /runners REST API 端点。

要注销单个 Runner，首先通过执行 gitlab-runner list 获取 Runner 的详细信息：

plaintext
test-runner     Executor=shell Token=t0k3n URL=http://gitlab.example.com

然后使用此信息，通过以下命令之一注销它。

此操作无法撤销。它会更新配置文件，因此请确保在执行前备份 config.toml。

通过 URL 和令牌#

shell
gitlab-runner unregister --url "http://gitlab.example.com/" --token t0k3n

通过名称#

shell
gitlab-runner unregister --name test-runner

如果存在多个具有给定名称的 Runner，则只会移除第一个。

所有 Runner#

shell
gitlab-runner unregister --all-runners

gitlab-runner reset-token#

此命令通过使用极狐GitLab Runners API 重置 Runner 的令牌，可以使用 Runner ID 或当前令牌。

它需要 Runner 的名称（或 URL 和 ID），以及一个可选的 PAT（如果通过 Runner ID 重置）。PAT 和 Runner ID 旨在用于令牌已过期的情况。

使用 --all-runners 选项，它将重置所有附加 Runner 的令牌。

使用 Runner 的当前令牌#

shell
gitlab-runner reset-token --name test-runner

使用 PAT 和 Runner 名称#

shell
gitlab-runner reset-token --name test-runner --pat PaT

使用 PAT、极狐GitLab URL 和 Runner ID#

shell
gitlab-runner reset-token --url "https://gitlab.example.com/" --id 12345 --pat PaT

所有 Runner#

shell
gitlab-runner reset-token --all-runners

以下命令允许您将 Runner 作为系统或用户服务进行管理。使用它们来安装、卸载、启动和停止 Runner 服务。

gitlab-runner install
gitlab-runner uninstall
gitlab-runner start
gitlab-runner stop
gitlab-runner restart
gitlab-runner status
多个服务
运行服务相关命令时出现 Access Denied

所有服务相关命令都接受这些参数：

参数	默认值	描述
--service	gitlab-runner	指定自定义服务名称
--config	参见配置文件	指定要使用的自定义配置文件
--user-service	参见用户服务	配置极狐GitLab Runner 作为用户服务（systemd）运行

gitlab-runner install#

此命令将极狐GitLab Runner 安装为服务。它根据运行的系统接受不同的参数集。

在 Windows 上或以超级用户身份运行时，它接受 --user 标志，该标志允许您降低使用 shell 执行器运行的构建的权限。

参数	默认值	描述
--service	gitlab-runner	指定要使用的服务名称
--config	参见配置文件	指定要使用的自定义配置文件
--syslog	true（适用于非 systemd 系统）	指定服务是否应与系统日志服务集成
--working-directory	当前目录	指定使用 shell 执行器运行构建时存储所有数据的根目录
--user	root	指定执行构建的用户
--password	无	指定执行构建的用户的密码

gitlab-runner uninstall#

此命令停止并卸载极狐GitLab Runner，使其不再作为服务运行。

gitlab-runner start#

此命令启动极狐GitLab Runner 服务。

gitlab-runner stop#

此命令停止极狐GitLab Runner 服务。

gitlab-runner restart#

此命令停止然后启动极狐GitLab Runner 服务。

gitlab-runner status#

此命令打印极狐GitLab Runner 服务的状态。当服务正在运行时，退出代码为零；当服务未运行时，退出代码为非零。

多个服务#

通过指定 --service 标志，可以安装多个极狐GitLab Runner 服务，并使用多个独立的配置。

用户服务#

您可以使用某些初始化系统（如 systemd）将服务作为用户服务进行管理。如果您的初始化系统提供此功能，并且您希望将 gitlab-runner 服务作为用户服务进行管理，请在运行服务相关命令时指定 --user-service 标志。

此命令允许从极狐GitLab 获取和处理构建。

gitlab-runner run#

gitlab-runner run 命令是当极狐GitLab Runner 作为服务启动时执行的主命令。它从 config.toml 读取所有已定义的 Runner，并尝试运行所有 Runner。

该命令会一直执行，直到收到信号。

它接受以下参数。

参数	默认值	描述
--config	参见配置文件	指定要使用的自定义配置文件
--working-directory	当前目录	指定使用 shell 执行器运行构建时存储所有数据的根目录
--user	当前用户	指定执行构建的用户
--syslog	false	将所有日志发送到 SysLog（Unix）或 EventLog（Windows）
--listen-address	空	Prometheus 指标 HTTP 服务器应监听的地址（<host>:<port>）

gitlab-runner run-single#

使用此补充命令从单个极狐GitLab 实例运行单个构建。它可以：

将所有选项作为 CLI 参数或环境变量，包括极狐GitLab URL 和 Runner 令牌。例如，一个明确指定所有参数的单个作业：
```
shell
gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:3.3
```
从配置文件读取以使用特定 Runner 的配置。例如，使用配置文件的单个作业：
```
shell
gitlab-runner run-single -c ~/.gitlab-runner/config.toml -r runner-name
```

您可以使用 --help 标志查看所有可能的配置选项：

shell
gitlab-runner run-single --help

您可以使用 --max-builds 选项控制 Runner 在退出前执行的构建数量。0 的默认值意味着 Runner 没有构建限制，作业将永远运行。

您还可以使用 --wait-timeout 选项控制 Runner 在退出前等待作业的时间。0 的默认值意味着 Runner 没有超时，并在作业之间永远等待。

内部命令#

极狐GitLab Runner 作为单个二进制文件分发，并包含一些在构建期间使用的内部命令。

gitlab-runner artifacts-downloader#

从极狐GitLab 下载产物归档。

gitlab-runner artifacts-uploader#

将产物归档上传到极狐GitLab。

gitlab-runner cache-archiver#

创建缓存归档，将其存储在本地或上传到外部服务器。

gitlab-runner cache-extractor#

从本地或外部存储的文件中恢复缓存归档。

故障排查#

以下是一些常见的陷阱。

通常，服务相关命令需要管理员权限：

在 Unix（Linux、macOS、FreeBSD）系统上，在 gitlab-runner 前加上 sudo
在 Windows 系统上，使用提升的命令提示符。运行一个 Administrator 命令提示符。要在 Windows 搜索字段中写入 Command Prompt，请右键单击并选择 Run as administrator。确认您要执行提升的命令提示符。

gitlab-runner stop 无法优雅关闭#

当极狐GitLab Runner 安装在主机上并运行本地执行器时，它会为下载或上传产物、处理缓存等操作启动额外的进程。这些进程作为 gitlab-runner 命令执行，这意味着您可以使用 pkill -QUIT gitlab-runner 或 killall QUIT gitlab-runner 来终止它们。当您终止它们时，它们负责的操作将失败。

以下是防止此问题的两种方法：

将 Runner 注册为本地服务（如 systemd），并使用 SIGQUIT 作为终止信号，并使用 gitlab-runner stop 或 systemctl stop gitlab-runner.service。以下是启用此行为的示例配置：
```
toml
; /etc/systemd/system/gitlab-runner.service.d/kill.conf
[Service]
KillSignal=SIGQUIT
TimeoutStopSec=infinity
```
- 要应用配置更改，在创建此文件后，使用 systemctl daemon-reload 重新加载 systemd。

使用 kill -SIGQUIT <pid> 手动终止进程。您必须找到主 gitlab-runner 进程的 pid。您可以通过查看日志找到它，因为它会在启动时显示：

shell
$ gitlab-runner run
Runtime platform                                    arch=arm64 os=linux pid=8 revision=853330f9 version=16.5.0

保存系统 ID 状态文件：访问被拒绝#

如果极狐GitLab Runner 15.7 和 15.8 对包含 config.toml 文件的目录没有写权限，则可能无法启动。

当极狐GitLab Runner 启动时，它会在包含 config.toml 的目录中搜索 .runner_system_id 文件。如果找不到 .runner_system_id 文件，它会创建一个新文件。如果极狐GitLab Runner 没有写权限，它将无法启动。

要解决此问题，请临时允许文件写权限，然后运行 gitlab-runner run。创建 .runner_system_id 文件后，您可以将权限重置为只读。

使用环境变量#

以调试模式运行#

超级用户权限#

配置文件#

信号#

命令概览#

注册相关命令#

gitlab-runner register#

交互式注册#

非交互式注册#

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

gitlab-runner list#

gitlab-runner lint#

gitlab-runner verify#

gitlab-runner unregister#

通过 URL 和令牌#

通过名称#

所有 Runner#

gitlab-runner reset-token#

使用 Runner 的当前令牌#

使用 PAT 和 Runner 名称#

使用 PAT、极狐GitLab URL 和 Runner ID#

所有 Runner#

服务相关命令#

gitlab-runner install#

gitlab-runner uninstall#

gitlab-runner start#

gitlab-runner stop#

gitlab-runner restart#

gitlab-runner status#

多个服务#

用户服务#

运行相关命令#

gitlab-runner run#

gitlab-runner run-single#

内部命令#

gitlab-runner artifacts-downloader#

gitlab-runner artifacts-uploader#

gitlab-runner cache-archiver#

gitlab-runner cache-extractor#

故障排查#

运行服务相关命令时出现 Access Denied#

gitlab-runner stop 无法优雅关闭#

保存系统 ID 状态文件：访问被拒绝#