gitlab runner命令

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：

gitlab-runner --debug <command>

超级用户权限

访问GitLab Runner配置的命令在以super-user（root）身份执行时的行为有所不同。文件位置取决于执行命令的用户。

请注意在执行用于运行构建，注册服务或管理注册的运行程序的命令时写入的通知：

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 </span>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格式。

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

/etc/gitlab-runner/config.toml当gitlab-runner作为超级用户（root）执行时，在* nix系统上
~/.gitlab-runner/config.toml 当gitlab-runner以非root身份执行时，在* nix系统上
./config.toml 在其他系统上

大多数命令接受参数来指定自定义配置文件，允许您在一台计算机上具有多个不同的配置。要指定自定义配置文件，请使用-cor --config标志，或使用CONFIG_FILE环境变量。

信号

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

命令	信号	行动
`register`	SIGINT	取消runner注册，如果已经注册则删除
`run`，`exec`，`run-single`	SIGINT，SIGTERM	中止所有正在运行的构建并尽快退出。使用两次立即退出（强制关机）。
`run`，`exec`，`run-single`	SIGQUIT	停止接受新版本。当前正在运行的构建完成后立即退出（正常关闭）。
`run`	SIGHUP	强制重新加载配置文件

例如，要强制重新加载Runner的配置文件，请运行（所有gitlab-runner进程都将收到此信号）：

sudo killall -SIGHUP gitlab-runner

如果您的操作系统配置为在服务失败时自动重启服务（这是某些平台上的默认设置），则可能会在上述信号关闭时自动重启运行器。

命令概述

如果你gitlab-runner没有任何参数运行，这就是你看到的：

NAME:
   gitlab-runner - a GitLab Runner
USAGE:
   gitlab-runner [global options] command [command options] [arguments...]
VERSION:
   1.0.0~beta.142.ga8d37f3 (a8d37f3)
AUTHOR (S)</span>:
   GitLab Inc. <support@gitlab.com>
COMMANDS:
   exec        execute a build locally
   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
   archive    find and archive files (internal)
   artifacts    upload build artifacts (internal)
   extract    extract files from an archive (internal)
   help, h    Shows a list of commands or help for one command

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

注册相关命令

以下命令允许您注册新的运行器，或列出并验证它们是否仍然已注册。

gitlab-runner注册
- 互动注册
- 非互动注册
gitlab-runner列表
gitlab-runner验证
gitlab-runner unregister

以上命令支持以下参数：

参数	默认	描述
`—config`	请参阅配置文件部分	指定要使用的自定义配置文件

gitlab-runner注册

此命令在GitLab中注册您的GitLab Runner。已注册的运行器将添加到配置文件中。您可以在单个GitLab Runner中使用多个配置。执行 gitlab-runner register添加新的配置条目，它不会删除以前的配置条目。

注册Runner有两种选择，交互式和非交互式。

互动注册

此命令通常用于交互模式（默认）。在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
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register

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

gitlab-runner register --help

非互动注册

可以在非交互/无人值守模式下使用注册。

您可以在调用registration命令时指定参数：

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

或者通过在register命令之前配置环境变量：

<span style="color:#1f1f1f"><span style="color:#eff1f5"><code><other-environment-variables>
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register
</code></span></span>

注意：必须在命令行中传递布尔参数--key={true|false}。

gitlab-runner列表

此命令列出配置文件中保存的所有运行程序。

gitlab-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运行程序中删除，请执行以下命令。

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

gitlab-runner verify --delete

gitlab-runner unregister

此命令允许注销其中一个注册的跑步者。它需要一个完整的URL和跑步者的令牌，或者跑步者的名字。使用该 --all-runners选项，它将取消注册所有附加的跑步者。

要取消注册特定的跑步者，首先通过执行gitlab-runner list以下步骤获取跑步者的详细信息：

test-runner   Executor=shell Token=gitlab.example.com

然后使用以下命令之一使用此信息取消注册。

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

通过URL和令牌：

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

按名字：

注意：如果有多个具有给定名称的跑步者，则只会删除第一个

gitlab-runner unregister --name test-runner

所有选手：

gitlab-runner unregister --all-runners

与服务相关的命令

注意：从GitLab Runner 10.0开始，不推荐使用 与服务相关的命令，这些命令将在其中一个即将发布的版本中删除。

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

gitlab-runner安装
gitlab-runner uninstall
gitlab-runner开始
gitlab-runner停止
gitlab-runner restart
gitlab-runner状态
多项服务
运行与服务相关的命令时拒绝访问

所有服务相关命令都接受以下参数：

参数	默认	描述
`—service`	`gitlab-runner`	指定自定义服务名称
`—config`	请参阅配置文件	指定要使用的自定义配置文件

gitlab-runner install

此命令将GitLab Runner安装为服务。它接受不同的参数集，具体取决于它运行的系统。

当在Windows上运行或作为超级用户运行时，它接受--user标志，该标志允许您删除使用shell执行程序运行的构建的权限。

参数	默认	描述
`—syslog`	`true`	指定服务是否应与系统日志记录服务集成
`—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作为服务启动时执行的主要命令。它从中读取所有已定义的Runners config.toml并尝试运行所有这些Runners 。

该命令被执行并一直有效，直到它收到一个信号。

它接受以下参数。

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

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.1

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

gitlab-runner run-single --help

您可以使用该--max-builds选项控制运行器在退出之前将执行的构建数量。默认值0表示运行器没有构建限制并将永久运行作业。

您还可以使用该--wait-timeout选项控制跑步者在退出前等待作业的时间。默认值0表示跑步者没有超时并且将在作业之间永久等待。

gitlab-runner exec

注意：并非所有功能.gitlab-ci.yml都受支持exec。请检查部分限制中gitlab-runner exec究竟支持的内容。

此命令允许您在本地运行构建，尝试尽可能多地复制CI环境。它不需要连接到GitLab，而是读取本地.gitlab-ci.yml并创建一个新的构建环境，其中执行所有构建步骤。

此命令对于快速检查和验证.gitlab-ci.yml以及调试损坏的构建非常有用，因为所有内容都在本地运行。

执行时，exec您需要指定执行程序和存在的作业名称.gitlab-ci.yml。该命令应该从包含的Git存储库的根目录执行.gitlab-ci.yml。

gitlab-runner exec将克隆本地Git存储库的当前状态。确保您已事先提交了要测试的任何更改。

例如，以下命令将使用shell执行程序在本地执行名为tests的作业：

gitlab-runner exec shell tests

要查看可用执行程序列表，请运行：

gitlab-runner exec

要查看执行程序的所有可用选项的列表，请shell运行：

gitlab-runner exec shell

如果要将docker执行程序与exec命令一起使用，请在docker-machine shell或的上下文中使用它boot2docker shell。这是将本地目录正确映射到Docker容器内的目录所必需的。

的局限性 gitlab-runner exec

目前实施execGitLab CI 的某些功能将无法正常工作或部分工作。

我们目前正在考虑如何替换当前的exec实现，以使所有功能完全兼容。请跟踪问题以获取更多详细信息。

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

GitLab CI功能	可用 `exec`	评论
图片	是	还支持扩展配置（`name`，`entrypoint`）
服务	是	扩展配置（`name`，`alias`，`entrypoint`，`command`），也支持
阶段	没有	`exec` 只能独立完成一项工作
before_script	是	支持全局和工作级别 `before_script`
after_script	部分	全球`after_script`不受支持，只有工作级别`after_script`; 只考虑命令，`when`硬编码`always`
变量	是	支持默认（部分），全局和作业级变量; 默认变量是预先设定的，如https://gitlab.com/gitlab-org/gitlab-runner/blob/master/helpers/gitlab_ci_yaml_parser/parser.go#L147
文物	没有
高速缓存	部分	关于具体配置，它可能会或可能不会按预期工作
缓存：政策	没有
环境	没有
只要	没有
除了	没有
`allow_failure`	没有	`exec`只是退出工作的结果; 调用者有责任决定失败是否正常
标签	没有
什么时候	没有
依赖	没有
覆盖	没有
重试	没有
隐藏的钥匙	没有	如果明确要求运行，`exec`将尝试运行此类作业
YAML功能	是	Anchors（`&`），aliases（`*`），map merge（`<<`）是YAML规范的一部分，由解析器处理
网页	部分	如果明确要求，将执行作业的脚本，但它不会影响由GitLab管理的页面状态

兼容性表 - 基于变量的功能

GitLab CI功能	可用 `exec`	评论
GIT_STRATEGY	是
GIT_CHECKOUT	是
GIT_SUBMODULE_STRATEGY	是
GET_SOURCES_ATTEMPTS	是
ARTIFACT_DOWNLOAD_ATTEMPTS	没有	不支持工件
RESTORE_CACHE_ATTEMPTS	是
GIT_DEPTH	是