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如果您使用的是 shelldocker 执行器,则不可以使用 killallpkill 进行优雅关闭。因为这会关闭子进程,进而导致信号的不合理处理。主进程处理作业时才能使用该命令。

如果您的操作系统配置了关闭后自动重启服务 (某些平台会默认开启该服务),使用上述信号关闭 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 的两个选项:

  • 交互式
  • 非交互式
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

noteexec 仅支持 .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 shellboot2docker 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  
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。系统会让您确认您想执行高级命令提示符。