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

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

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

大多数命令接受参数来指定自定义配置文件，允许您在一台计算机上具有多个不同的配置。要指定自定义配置文件，请使用-c  or  --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	是

兼容性表 - 其他功能

GitLab CI功能	可用 exec	评论
秘密变量	没有
触发器	没有
时间表	没有
工作超时	没有	硬编码为1小时
[ci skip]	没有

其他要求和限制

gitlab-runner exec docker只能在本地安装Docker时使用。这是必需的，因为GitLab Runner使用主机绑定卷来访问Git源。

内部命令

GitLab Runner作为单个二进制文件分发，并包含一些在构建期间使用的内部命令。

gitlab-runner artifacts-downloader

从GitLab下载工件存档。

gitlab-runner artifacts-uploader

将工件存档上传到GitLab。

gitlab-runner cache-archiver

创建缓存存档，将其存储在本地或将其上载到外部服务器。

gitlab-runner cache-extractor

从本地或外部存储的文件还原缓存存档

原文地址：https://docs.gitlab.com/runner/commands/README.html