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の設定にアクセスするコマンドは、スーパーユーザー(root)で実行すると動作が異なります。ファイルの場所はコマンドを実行するユーザーによって異なります。

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) として実行した場合：/etc/gitlab-runner/config.toml
  2. GitLab Runnerをnon-rootで実行した場合：~/.gitlab-runner/config.toml
  3. その他のシステムでは./config.toml

ほとんどのコマンドはカスタム設定ファイルを指定する引数を受け付けるので、1台のマシンで複数の異なる設定を行うことができます。カスタム設定ファイルを指定するには、-c または--config フラグを使用するか、CONFIG_FILE 環境変数を使用します。

シグナル

システムシグナルを使って GitLab Runner とやり取りすることができます。以下のコマンドは以下のシグナルをサポートしています：

コマンドシグナルアクション
registerシギントランナーの登録をキャンセルし、すでに登録されている場合は削除します。
run,exec 、run-single sigint,sigterm 実行中のビルドをすべて中止し、できるだけ早く終了します。今すぐ終了するには2回使用してください（強制シャットダウン）。
run,exec 、run-single SIGQUIT新しいビルドの受け付けを停止します。現在実行中のビルドが終了したらすぐに終了します（グレースフル・シャットダウン）。
runシグアップ設定ファイルを強制的にリロードします。

例えば、Runnerの設定ファイルを強制的にリロードするには、次のように実行します：

sudo kill -SIGHUP <main_runner_pid>

グレースフル・シャットダウンの場合

sudo kill -SIGQUIT <main_runner_pid>
caution
shell またはdocker のエクゼキュータを使用している場合は、killall またはpkill をグレースフル・シャットダウンに使用しないでください。これは、サブプロセスも強制終了されるため、シグナルの不適切な処理を引き起こす可能性があります。ジョブを処理するメインプロセスのみに使用してください。

サービスが失敗した場合に自動的に再起動するようにオペレーションシステムが設定されている場合（いくつかのプラットフォームではデフォルトです）、上記のシグナルによってシャットダウンされた場合、自動的にランナーが再起動されることがあります。

コマンドの概要

引数なしで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

以下、各コマンドが何をするのか詳しく説明します。

新しいランナーを登録したり、登録済みのランナーをリストアップして確認したりするには、以下のコマンドを使用します。

これらのコマンドは以下の引数をサポートしています：

パラメータデフォルト説明
--config 設定ファイルのセクションを参照してください。使用するカスタム設定ファイルの指定

gitlab-runner register

このコマンドは GitLabRunners API を使って GitLab にランナーを登録します。

登録されたRunnerは設定ファイルに追加されます。GitLab Runnerの一つのインストールで複数の設定を使用することができます。gitlab-runner register を実行すると、新しい設定項目が追加されます。以前のものは削除されません。

ランナー登録には2つの方法があります：

  • 対話式
  • 非対話的。
note
RunnerはGitLabRunners APIを使って直接登録できますが、設定は自動生成されません。

インタラクティブな登録

このコマンドは通常インタラクティブ・モード（デフォルト）で使用します。ランナー登録中に複数の質問をされます。

この質問は、registrationコマンドを起動する際に引数を追加することで、事前に入力することができます：

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

このコマンドは、設定ファイルに保存されているすべてのランナーを一覧表示します。

gitlab-runner verify

このコマンドは登録されたランナーが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

このコマンドは GitLabRunners API を使って登録されている Runner の登録を解除します。

このコマンドは

  • 完全なURLとランナーのトークン。
  • ランナーの名前。

--all-runners オプションで、すべてのランナーの登録を解除します。

note
GitLabRunners APIを使って直接 Runner の登録を解除することもできますが、ユーザーの設定は変更されません。

ランナーの登録を解除するには、まずgitlab-runner list を実行してランナーの詳細を取得します：

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
指定された名前のランナーが複数存在する場合、最初のランナーのみが削除されます。

すべてのランナー 

gitlab-runner unregister --all-runners

gitlab-runner reset-token

このコマンドは GitLab Runners API を使ってランナーのトークンをリセットします。

ランナーの名前（あるいは URL と ID）、そしてランナー ID でリセットする場合はオプションで PAT を指定します。PAT と Runner ID は、トークンがすでに期限切れになっている場合に使用するものです。

--all-runners オプションを指定すると、アタッチされているすべてのRunnerのトークンをリセットします。

ランナーの現在のトークンで 

gitlab-runner reset-token --name test-runner

PATとランナー名を含む 

gitlab-runner reset-token --name test-runner --pat PaT

PAT、GitLab URL、ランナーIDを含む 

gitlab-runner reset-token --url "https://gitlab.example.com/" --id 12345 --pat PaT

すべてのランナー 

gitlab-runners reset-token --all-runners

以下のコマンドを使用すると、システムまたはユーザーサービスとしてRunnerを管理できます。これらのコマンドを使用して、Runnerサービスをインストール、アンインストール、開始、停止します。

すべてのサービス関連コマンドは、これらの引数を受け入れます：

パラメータデフォルト説明
--servicegitlab-runnerカスタムサービス名の指定
--config 設定ファイルを見る使用するカスタム設定ファイルの指定

gitlab-runner install

このコマンドは GitLab Runner をサービスとしてインストールします。実行するシステムによって異なる引数を受け取ります。

Windowsやスーパーユーザーで実行する場合は、--user フラグを受け取ります。このフラグを使うと、Shellexecutor で実行するビルドの権限を落とすことができます。

パラメータデフォルト説明
--servicegitlab-runner使用するサービス名を指定します。
--config 設定ファイルを見る使用するカスタム設定ファイルの指定
--syslog true (systemd以外のシステムの場合)サービスがシステムのロギングサービスとインテグレーションするかどうかを指定します。
--working-directoryカレントディレクトリ ShellExecutor でビルドを実行する際に、すべてのデータが格納されるルートディレクトリを指定します。
--userrootビルドを実行するユーザーを指定します。
--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 がサービスとして開始されたときに実行されるメインコマンドです。config.toml から定義されたすべての Runner を読み込み、すべての Runner を実行しようとします。

コマンドはシグナルを受け取るまで実行され、動作します。

以下のパラメータを受け付けます。

パラメータデフォルト説明
--config 設定ファイル参照使用するカスタム設定ファイルの指定
--working-directoryカレントディレクトリ ShellExecutor でビルドを実行する際に、すべてのデータが格納されるルートディレクトリを指定します。
--user現在のユーザービルドを実行するユーザーを指定します。
--syslogfalseすべてのログを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 オプションを使用すると、ランナーが終了するまでに実行するビルド数を制御できます。デフォルトの0 は、ランナーにビルド制限がなく、ジョブが永遠に実行されることを意味します。

また、--wait-timeout オプションを使用して、Runner がジョブを終了するまでの待機時間を制御できます。デフォルトの0 は、ランナーにタイムアウトがなく、ジョブ間で永遠に待機することを意味します。

gitlab-runner exec (非推奨)

caution
この機能はGitLab 15.7で非推奨となり、17.0で削除される予定です。パイプライン構文と検証シミュレーションはGitLabパイプラインエディターで利用できます。この変更はブレークチェンジです。
note
.gitlab-ci.yml の全ての機能がexec でサポートされているわけではありません。具体的に何がサポートされているかは、gitlab-runner execの制限事項で確認してください。

このコマンドを使うと、CI 環境をできるだけ再現するようにローカルでビルドを実行できます。GitLab に接続する必要はなく、ローカルの.gitlab-ci.yml を読み込み、すべてのビルドステップが実行される新しいビルド環境を作成します。

このコマンドは、.gitlab-ci.yml を素早くチェック・検証したり、壊れたビルドをデバッグしたりするのに便利です。

exec を実行する際には、.gitlab-ci.yml. .gitlab-ci.ymlNET Framework に存在する Executor とジョブ名を指定する必要があります。.gitlab-ci.ymlこのコマンドは、.NET Framework を含む Git リポジトリのルートディレクトリから実行する必要が .gitlab-ci.ymlあります。

gitlab-runner exec はローカルの Git リポジトリの現在の状態をクローンします。テストしたい変更があれば、事前にコミットしておきましょう。

たとえば、次のコマンドはtests という名前のジョブをローカルで Shell Executor を使って実行します：

gitlab-runner exec shell tests

利用可能なエクゼキュータの一覧を見るには、次のコマンドを実行してください：

gitlab-runner exec

shell Executorで利用可能なすべてのオプションのリストを見るには、以下を実行してください：

gitlab-runner exec shell

exec コマンドでdocker Executor を使用したい場合は、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 コメント
imageyes拡張設定 (name,entrypoint) もサポートされています。
servicesyes拡張設定 (name,alias,entrypoint,command) もサポートされています。
before_scriptyesグローバルとジョブレベルの両方をサポートbefore_script.
after_script一部グローバルafter_script はサポートされていません。ジョブレベルのafter_script;コマンドのみが考慮され、when はalways にハードコードされます。
variablesyesデフォルト変数、グローバル変数、ジョブレベル変数をサポートします。デフォルト変数はコードにあるようにあらかじめ設定されています。
cache一部具体的な設定については、期待通りに機能する場合もあれば、そうでない場合もあります。
YAMLの特徴yesアンカー (&)、エイリアス (*)、マップマージ (<<)はYAML仕様の一部であり、パーサーによって処理されます。
pages一部ジョブのスクリプトは明示的に要求されれば実行されますが、GitLabによって管理されるPagesの状態には影響しません。

互換性表 - 変数に基づく機能

GitLab CI機能利用可能な機能exec コメント
GIT_STRATEGYyes 
GIT_CHECKOUTyes 
GIT_SUBMODULE_STRATEGYyes 
GIT_SUBMODULE_PATHSyes 
GIT_SUBMODULE_UPDATE_FLAGSyes 
GIT_SUBMODULE_DEPTHyes 
GIT_SUBMODULE_FORCE_HTTPSyes 
GET_SOURCES_ATTEMPTSyes 
ARTIFACT_DOWNLOAD_ATTEMPTSいいえアーティファクトはサポートされていません。
RESTORE_CACHE_ATTEMPTSyes 

互換性表 - その他の機能

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

ローカルまたは外部保存ファイルからキャッシュアーカイブを復元します。

トラブルシューティング

以下はよくある落とし穴です。

通常、サービス関連のコマンドは管理者権限が必要です：

  • Unix（Linux、MacOS、FreeBSD）システムでは、gitlab-runner の前にsudo
  • Windowsシステムでは、昇格コマンドプロンプトを使用します。Administrator コマンドプロンプトを実行します。最も簡単な方法は、Windows の検索フィールドにCommand Prompt と入力し、右クリックしてRun as administrator を選択することです。昇格コマンドプロンプトを実行するかどうかの確認を求められます。

/usr/lib/gitlab-runner: No such file or directory

GitLab13.3では、gitlab-runner の実行ファイルが/usr/lib/ から/usr/bin/ に移動しました。後方互換性のために、/usr/lib/gitlab-runner から/usr/bin/gitlab-runner を指すシンボリックリンクが追加されました。GitLab 14.0では、シンボリックリンクは削除されました。/usr/lib/gitlab-runner: No such file or directory のエラーを解決するには、以下のいずれかを行ってください：

  • gitlab-runner を直接呼び出します（/usr/bin が$PATH の内部にあると仮定します）。
  • /usr/bin/gitlab-runner 。

gitlab-runner stop シャットダウンしない

Runnerがホストにインストールされ、ローカルのExecutorを実行するとき、アーティファクトのダウンロードやアップロード、キャッシュの処理など、いくつかのオペレーションのために追加のプロセスを開始します。これらのプロセスは、gitlab-runner コマンドとして実行されます。つまり、pkill -QUIT gitlab-runner またはkillall QUIT gitlab-runner を使って kill することができます。これらのプロセスを終了させると、担当するオペレーションは失敗します。

これを防ぐ2つの方法があります：

  • SIGQUIT を kill シグナルとして、ランナーをローカルサービス（systemd のような）として登録し、gitlab-runner stop またはsystemctl stop gitlab-runner.serviceを使います。GitLab.com の共有ランナーの設定の例を示します：

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

  • 手動でkill -SIGQUIT <pid> でプロセスを kill してください。メインのgitlab-runner プロセスのpid を見つける必要があります。起動時に表示されるので、ログを見ればわかります：

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