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:
   15.11.0 (436955cb)

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

COMMANDS:
   exec                  execute a build locally
   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，首先执行 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 实例中的单一构建。不使用配置文件，需要以参数或环境变量的方式传递所有选项。需要指定极狐GitLab URL 和 Runner 令牌。

例如：

gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:2.7

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

gitlab-runner run-single --help

您可以使用 --max-builds 选项控制退出前 Runner 执行的构建数量，默认为 0，表明该 Runner 没有构建限制，作业可以一直运行。

您还可以使用 --wait-timeout 选项控制退出前 Runner 等待作业的时间，默认为 0， 表明该 Runner 不会超时，会一直等待。

gitlab-runner exec（废弃）

caution 此功能废弃于 15.7 并计划在 17.0 中删除。流水线语法和验证模拟在极狐GitLab 流水线编辑器中可用。这是一个突破性的变化。
note exec 仅支持 .gitlab-ci.yml 的部分功能。 详情请参见 gitlab-runner exec 限制。

该命令会在本地运行构建，尽力复制 CI 环境。不用连接极狐GitLab，只需读取本地 .gitlab-ci.yml 并创建新的构建环境，所有的构建步骤在新环境中执行。

由于是本地运行，这条命令对于快速检查和验证 .gitlab-ci.yml ，以及调试损坏的构建很有用。

执行 exec 时，您需要指定执行器和 .gitlab-ci.yml 中的作业名称。应该从包括 .gitlab-ci.yml 的 Git 目录的根目录中执行该命令。

gitlab-runner exec 克隆本地 Git 仓库的当前状态。 您需要确保已经提交了需要进行测试的变更。

例如，下列命令使用 shell 执行器在本地执行 tests 作业。

gitlab-runner exec shell tests

查看可用执行器，运行：

gitlab-runner exec

查看 shell 执行器的所有可用选项，运行：

gitlab-runner exec shell

如果您想通过 exec 命令使用 docker 执行器，请在 docker-machine shell 或 boot2docker shell 上下文中使用，这样本地目录才能合理映射到 Docker 容器内的目录。

其他选项也可用：

  • 要查看所有可能的配置选项，请使用 --help：

    gitlab-runner exec --help
  • 指定 CI/CD 配置文件的路径，如果您的项目不使用默认的 .gitlab-ci.yml，请使用--cicd-config-file。
  • 要设置作业执行超时（以秒为单位），请使用 --timeout。 默认值 1800 表示执行在 30 分钟后超时。

gitlab-runner exec 限制

基于当前的 exec 执行，极狐GitLab CI/CD 的某些功能可能无法正常使用或只能部分使用。

我们正在考虑如何替换当前的 exec 执行，以完全兼容全部功能。

兼容表 - 基于 .gitlab-ci.yml 的功能

支持下列功能。表中未列出的功能表示暂不支持。

极狐GitLab CI 功能 exec 可用 备注
image 是 支持扩展配置 (name, entrypoint)
services 是 支持扩展配置 (name, alias, entrypoint, command)
before_script 是 支持全局和作业级别的 before_script
after_script 部分 不支持 after_script， 仅支持作业级别的 after_script。仅考虑命令， when 硬编码为 always
variables 是 支持默认值 （部分）、全局和作业级别的变量; 默认变量是预先设置的，如代码中所示
cache 部分 取决于特定配置情况
YAML feature 是 锚点 (&)、别名 (*) 和 map 合并 (<<) 是 YAML 规范的一部分，并且由 parser 进行处理
pages 部分 如果明确要求，会执行作业脚本，但并不影响 pages 状态，pages 状态由极狐GitLab 管理

兼容表 - 基于变量的功能

极狐GitLab CI 功能 exec 可用 备注
GIT_STRATEGY 是  
GIT_CHECKOUT 是  
GIT_SUBMODULE_STRATEGY 是  
GIT_SUBMODULE_PATHS 是  
GIT_SUBMODULE_UPDATE_FLAGS 是  
GIT_SUBMODULE_DEPTH 是  
GIT_SUBMODULE_FORCE_HTTPS 是  
GET_SOURCES_ATTEMPTS 是  
ARTIFACT_DOWNLOAD_ATTEMPTS 是 不支持产物
RESTORE_CACHE_ATTEMPTS 是  
GIT_DEPTH 是  

兼容表 - 其他功能

极狐GitLab CI 功能 exec 可用 备注
Secret Variables 否  
triggers 否  
schedules 否  
job timeout 否 硬编码到 1 个小时
[ci skip] 否  

其他要求和限制

只有本地安装 Docker 时，才能使用gitlab-runner exec docker， 因为极狐GitLab Runner 使用 host-bind 卷访问 Git 源。

内部命令

极狐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。 以下是 JihuLab.com 上共享 Runner 的配置示例：

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

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

    $ gitlab-runner run
Runtime platform                                    arch=amd64 os=linux pid=87858 revision=436955cb version=15.11.0