GitLab Runner 命令

GitLab Runner 包括一组命令，用以注册、管理和运行您的构建。

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

gitlab-runner --help

在命令后添加 --help 查看具体帮助页面。

gitlab-runner <command> --help

使用环境变量

大多数命令支持将环境变量作为传递配置到命令的一种方法。

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

命令:

gitlab-runner run --help

输出消息类似于：

NAME:
   gitlab-runner run - run multi runner service

USAGE:
   gitlab-runner run [command options] [arguments...]

OPTIONS:
   -c, --config "/Users/ayufan/.gitlab-runner/config.toml"      Config file [$CONFIG_FILE]

在 Debug 模式下运行

Debug 模式在查找未知行为和错误原因时非常有用。

在 Debug 模式下运行命令，需要加上 --debug:

gitlab-runner --debug <command>

超级用户权限

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

当您执行 gitlab-runner 命令，可以看到它的运行模式：

$ gitlab-runner run

INFO[0000] Starting multi-runner from /Users/ayufan/.gitlab-runner/config.toml ...  builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...

当您确认此模式是您所需要的模式时，您应该使用 user-mode；否则，为命令加上前缀 sudo:

$ 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 格式。

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

  1. 极狐GitLab Runner 以超级用户 (root) 执行的 *nix 系统： /etc/gitlab-runner/config.toml
  2. 极狐GitLab Runner 以 non-root 执行的 *nix 系统: ~/.gitlab-runner/config.toml
  3. 其他系统： ./config.toml

大多数命令可以通过参数指定自定义配置文件，这样您就可以在一个机器上进行不同配置。使用 -c 或 --config 标记，或者 CONFIG_FILE 环境变量指定自定义配置文件。

信号

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

命令 信号 动作
register SIGINT 取消 Runner 注册，如已注册，将其删除。
run, exec, run-single SIGINT, SIGTERM 停止所有运行中的构建并以最快的速度退出。执行两次该命令立即退出（强制关闭）。
run, exec, run-single SIGQUIT 停止接受新构建。当前运行的构建结束后立即退出（优雅关闭）。
run SIGHUP 强制重新加载配置文件。

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

sudo kill -SIGHUP <main_runner_pid>

对于优雅关闭:

sudo kill -SIGQUIT <main_runner_pid>
caution 如果您使用的是 shell 或 docker 执行器，则不可以使用 killall 或 pkill 进行优雅关闭。因为这会关闭子进程，进而导致信号的不合理处理。主进程处理作业时才能使用该命令。

如果您的操作系统配置了关闭后自动重启服务 （某些平台会默认开启该服务），使用上述信号关闭 Runner 后，Runner 会自动重启。

命令概览

不加参数运行 gitlab-runner 会显示：

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   16.5.0 (853330f9)

AUTHOR:
   GitLab Inc. <support@gitlab.com>

COMMANDS:
   list                  List all configured runners
   run                   run multi runner service
   register              register a new runner
   reset-token           reset a runner's token
   install               install service
   uninstall             uninstall service
   start                 start service
   stop                  stop service
   restart               restart service
   status                get status of a service
   run-single            start single runner
   unregister            unregister specific runner
   verify                verify all registered runners
   artifacts-downloader  download and extract build artifacts (internal)
   artifacts-uploader    create and upload build artifacts (internal)
   cache-archiver        create and upload cache artifacts (internal)
   cache-extractor       download and extract cache artifacts (internal)
   cache-init            changed permissions for cache paths (internal)
   health-check          check health for a specific address
   read-logs             reads job logs from a file, used by kubernetes executor (internal)
   help, h               Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --cpuprofile value           write cpu profile to file [$CPU_PROFILE]
   --debug                      debug mode [$RUNNER_DEBUG]
   --log-format value           Choose log format (options: runner, text, json) [$LOG_FORMAT]
   --log-level value, -l value  Log level (options: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
   --help, -h                   show help
   --version, -v                print the version

下面会详细介绍每个命令的含义。

注册相关的命令

使用下列命令注册新 Runner， 如果已经注册成功，会列出或校验 Runner。

命令支持下列参数：

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

gitlab-runner register

使用极狐GitLab Runner API 在极狐GitLab 注册新 Runner。

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

以下是注册 Runner 的两个选项：

  • 交互式
  • 非交互式
note 使用极狐GitLab Runner API 可以直接注册 Runner，但是不能自动生成配置。

交互式注册

通常在交互模式下使用此命令（默认），在注册过程中系统会问您一些问题。

调用注册命令时，可以通过添加参数预填问题。

gitlab-runner register --name my-runner --url http://gitlab.example.com --registration-token my-registration-token

您也可以在 register 命令前面配置环境变量预填问题。

export CI_SERVER_URL=http://gitlab.example.com
export RUNNER_NAME=my-runner
export REGISTRATION_TOKEN=my-registration-token
gitlab-runner register

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

gitlab-runner register --help

非交互式注册

您可以在非交互式/无人值守模式下进行注册。

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

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

或者通过在 register 命令的前面配置环境变量。

<other-environment-variables>
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register
note 带有 --key={true|false} 的命令行中，必须传递布尔参数。

[[runners]] 配置模板文件

引入于极狐GitLab Runner 12.2。

在注册 Runner 过程中可以使用 配置模板文件 功能轻松配置其他选项。

gitlab-runner list

列出存储在配置文件中的所有 Runner。

gitlab-runner verify

检测注册的 Runner 是否可以连接到极狐GitLab， 但不会校验其是否被极狐GitLab Runner 服务使用。示例输出为：

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 移除的旧 Runner：

caution 此操作不可撤销，并且会更新配置文件，在执行前请备份 config.toml。
gitlab-runner verify --delete

gitlab-runner unregister

使用极狐GitLab Runners API 取消已注册的 Runner。

需要以下其中一种：

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

使用 --all-runners 选项取消注册所有相关 Runner。

note 使用极狐GitLab Runner API 可以直接取消注册 Runner，但是配置没有更改。
  • 如果 runner 是用 runner 注册令牌创建的，那么使用 runner 认证令牌执行 gitlab-runner unregister 命令就会删除 runner。
  • 如果是在极狐GitLab UI 上或者通过 Runner API 创建的 runner，那么使用 runner 认证令牌执行 gitlab-runner unregister 命令只会删除 runner 管理器，但不会删除 runner。要想彻底删除 runner，需要在 runner 管理员界面上进行删除或者使用 DELETE/runner API 端点来实现。

要取消注册单个 Runner，首先执行 gitlab-runner list 获取 Runner 详细信息：

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

然后使用详细信息通过下列命令取消注册。

caution 此操作不可撤销，并且会更新配置文件，在执行前请备份 config.toml。

通过 URL 和令牌 

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

通过名称 

gitlab-runner unregister --name test-runner
note 如果有两个重名的 Runner，仅移除第一个。

所有 Runner 

gitlab-runner unregister --all-runners

gitlab-runner reset-token

此命令使用极狐GitLab Runner API 重置 Runner 令牌，其中使用 Runner ID 或当前令牌。

如果通过 Runner ID 进行重置，则需要 Runner 名称（或 URL 和 ID），以及一个可选的 PAT。 如果令牌已经过期，则需要使用 PAT 和 Runner ID。

使用 --all-runners 选项会重置所有附属的 Runner 令牌。

使用当前 Runner 令牌 

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

使用 PAT 和 Runner 名称 

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

使用 PAT、极狐GitLab URL 和 Runner ID 

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

所有 Runner 

gitlab-runners reset-token --all-runners

服务相关的命令

以下命令能够让您以系统或用户服务的形式管理 Runner，用以安装、卸载、启动和停止 Runner 服务。

所有服务相关的命令都支持以下参数：

参数 默认 描述
--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 服务的状态。服务运行时，退出码是 0；服务未运行时，退出码不是 0。

多个服务

用户可以通过指定 --service 标记安装多个极狐GitLab Runner 服务，并进行多个配置。

运行相关的命令

获取和处理极狐GitLab 的构建。

gitlab-runner run

运行极狐GitLab Runner 服务的主命令。从 config.toml 读取并运行所有定义的 Runner。

接收信号前会一直执行这个命令。

支持以下参数：

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

gitlab-runner run-single

  • 使用配置文件的能力自极狐GitLab 17.1 引入。

这是一个补充命令，可以运行单一极狐GitLab 实例中的单一构建。它可以：

  • 将所有选项作为命令行参数或环境变量来使用，包括极狐GitLab URL 和 Runner 令牌。例如，显式指定了所有参数的单个作业：
gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:2.7
  • 从配置文件中读取以使用指定 runner 的配置。例如，具有配置文件的单个作业：
gitlab-runner run-single -c ~/.gitlab-runner/config.toml -r runner-name

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

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 未优雅关闭

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

有两种方法可以防止这种情况：

  • 将 Runner 注册为本地服务（如 systemd），将 SIGQUIT 作为结束信号，并使用 gitlab-runner stop 或 systemctl stop gitlab-runner.service。下面的示例演示了如何开启此功能：

    ; /etc/systemd/system/gitlab-runner.service.d/kill.conf
[Service]
KillSignal=SIGQUIT
TimeoutStopSec=infinity

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

    $ 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 文件创建后，就可以恢复权限为只读。