极狐GitLab Runner 命令

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

极狐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>

超级用户权限#

当以超级用户 (root) 身份执行时，访问极狐GitLab Runner 配置的命令会表现得有所不同。文件位置取决于执行命令的用户。

当您执行 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 格式。

您可以找到要编辑的文件：

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

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

信号#

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

Command	Signal	Action
register	SIGINT	取消 runner 注册并删除已注册的 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>

不要使用 killall 或 pkill 进行正常关闭，如果您使用 shell 或 docker 执行器。这可能会导致由于子进程也被杀死而导致信号处理不当。仅在处理作业的主进程上使用它。

某些操作系统配置为在服务失败时自动重启服务（这是某些平台的默认设置）。如果您的操作系统具有此配置，它可能会在通过上述信号关闭 runner 后自动重启 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   16.5.0 (853330f9)
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   artifacts-downloader  download and extract build artifacts (internal)
28   artifacts-uploader    create and upload build artifacts (internal)
29   cache-archiver        create and upload cache artifacts (internal)
30   cache-extractor       download and extract cache artifacts (internal)
31   cache-init            changed permissions for cache paths (internal)
32   health-check          check health for a specific address
33   read-logs             reads job logs from a file, used by kubernetes executor (internal)
34   help, h               Shows a list of commands or help for one command
35
36GLOBAL OPTIONS:
37   --cpuprofile value           write cpu profile to file [$CPU_PROFILE]
38   --debug                      debug mode [$RUNNER_DEBUG]
39   --log-format value           Choose log format (options: runner, text, json) [$LOG_FORMAT]
40   --log-level value, -l value  Log level (options: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
41   --help, -h                   show help
42   --version, -v                print the version

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

使用以下命令来注册新的 runner，或列出并验证它们是否仍然注册。

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

这些命令支持以下参数：

Parameter	Default	Description
--config	查看配置文件部分	指定使用的自定义文件

gitlab-runner register#

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

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

您可以注册一个 runner：

交互式。
非交互式。

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

交互式注册#

此命令通常在交互模式下使用（默认）。在 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]] 配置模板文件#

History

在极狐GitLab Runner 12.2 中引入。

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

gitlab-runner list#

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

gitlab-runner verify#

此命令验证已注册的 runners 是否可以连接到极狐GitLab。但是，它不会验证 runners 是否被极狐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

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

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

shell
gitlab-runner verify --delete

gitlab-runner unregister#

此命令通过使用极狐GitLab Runners API 取消注册已注册的 runners。

它期望以下任一项：

完整的 URL 和 runner 的 token。
runner 的名称。

使用 --all-runners 选项，它会取消注册所有附加的 runners。

可以通过极狐GitLab Runners API 取消注册 runners，但用户的配置不会被修改。

如果 runner 是使用 runner 注册 token 创建的，使用 runner 身份验证 token 的 gitlab-runner unregister 会删除 runner。
如果 runner 是在极狐GitLab UI 或使用 Runners API 创建的，使用 runner 身份验证 token 的 gitlab-runner unregister 会删除 runner 管理器，但不会删除 runner。要完全删除 runner，请在 runners 管理页面删除 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 和 token#

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

通过名称#

shell
gitlab-runner unregister --name test-runner

如果具有给定名称的 runner 多于一个，则仅删除第一个。

所有 runners#

shell
gitlab-runner unregister --all-runners

gitlab-runner reset-token#

此命令通过使用极狐GitLab Runners API 重置 runner 的 token，使用runner ID 或当前 token。

它期望 runner 的名称（或 URL 和 ID），以及一个可选的 PAT，如果通过 runner ID 重置。PAT 和 runner ID 旨在用于 token 已经过期的情况。

使用 --all-runners 选项，它会重置所有附加 runners 的 token。

使用 runner 的当前 token#

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

所有 runners#

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

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

gitlab-runner install
gitlab-runner uninstall
gitlab-runner start
gitlab-runner stop
gitlab-runner restart
gitlab-runner status
多个服务
运行服务相关命令时出现 访问被拒绝

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

参数	默认值	描述
--service	gitlab-runner	指定自定义服务名称
--config	查看配置文件	指定使用的自定义配置

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 服务，具有多个独立的配置。

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

gitlab-runner run#

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

该命令会被执行并工作，直到它接收到信号。

它接受以下参数。

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

gitlab-runner run-single#

History

在极狐GitLab Runner 17.1 中引入了使用配置文件的能力。

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

将所有选项作为 CLI 参数或环境变量，包括极狐GitLab URL 和 Runner token。例如，单个作业，所有参数都显式指定：
```
shell
gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:2.7
```
从配置文件中读取以使用特定 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 系统上，使用提升的命令提示符。运行管理员命令提示符。在 Windows 搜索字段中输入命令提示符，右键单击并选择以管理员身份运行。确认您要执行提升的命令提示符。

gitlab-runner stop 无法正常关闭#

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

以下是防止此情况的两种方法：

将 runner 注册为本地服务（如 systemd），并使用 SIGQUIT 作为 kill 信号，并使用 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 命令

使用环境变量#

在调试模式下运行#

超级用户权限#

配置文件#

信号#

命令概述#

注册相关命令#

gitlab-runner register#

交互式注册#

非交互式注册#

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

gitlab-runner list#

gitlab-runner verify#

gitlab-runner unregister#

通过 URL 和 token#

通过名称#

所有 runners#

gitlab-runner reset-token#

使用 runner 的当前 token#

使用 PAT 和 runner 名称#

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

所有 runners#

服务相关命令#

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#

故障排除#

运行服务相关命令时出现 访问被拒绝#

gitlab-runner stop 无法正常关闭#

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

运行服务相关命令时出现访问被拒绝#