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 格式。
您可以在以下位置找到编辑文件:
- 极狐GitLab Runner 以超级用户 (
root
) 执行的 *nix 系统:/etc/gitlab-runner/config.toml
- 极狐GitLab Runner 以 non-root 执行的 *nix 系统:
~/.gitlab-runner/config.toml
- 其他系统:
./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>
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.1.0 (76984217)
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
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 [$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 的两个选项:
- 交互式
- 非交互式
交互式注册
通常在交互模式下使用此命令(默认),在注册过程中系统会问您一些问题。
调用注册命令时,可以通过添加参数预填问题。
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
--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:
config.toml
。gitlab-runner verify --delete
gitlab-runner unregister
使用极狐GitLab Runners API 取消已注册的 Runner。
需要以下其中一种:
- 完整的 URL 和 Runner 的令牌。
- Runner 的名称。
使用 --all-runners
选项取消注册所有相关 Runner。
要取消注册特定 Runner, 首先执行
gitlab-runner list
获取 Runner 详细信息:
test-runner Executor=shell Token=t0k3n URL=http://gitlab.example.com
然后使用详细信息通过下列命令取消注册。
config.toml
。通过 URL 和令牌
gitlab-runner unregister --url http://gitlab.example.com/ --token t0k3n
通过名称
gitlab-runner unregister --name test-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 服务。
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 服务的状态。服务运行时,退出码是 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
(废弃)
该命令会在本地运行构建,尽力复制 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
| 是 | 支持默认值 (部分)、全局和作业级别的变量; 预设默认变量请参见 https://jihulab.com/gitlab-cn/gitlab-runner/-/blob/c715666c059cc88a354d7cbcb5948b992d23f2a8/helpers/gitlab_ci_yaml_parser/parser.go#L149 |
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 | 是 | |
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=8d21977e version=12.10.0~beta.82.g8d21977e