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. *nixシステムでGitLab Runnerがスーパーユーザー（root）として実行されている場合は/etc/gitlab-runner/config.toml
2. *nixシステムでGitLab Runnerが非rootユーザーとして実行されている場合は~/.gitlab-runner/config.toml
3. その他のシステムでは./config.toml

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

シグナル

システムシグナルを使用してGitLab Runnerを操作できます。以下のコマンドは、以下のシグナルをサポートしています:

たとえばRunnerの設定ファイルを強制的に再読み込みするには、次のように実行します:

sudo kill -SIGHUP <main_runner_pid>

正常なシャットダウンの場合は次のようになります:

sudo kill -SIGQUIT <main_runner_pid>

一部のオペレーティングシステムは、サービスが失敗すると自動的に再起動するように設定されています（一部のプラットフォームではデフォルトです）。ご使用のオペレーティングシステムでこのように設定されている、上記のシグナルによってRunnerがシャットダウンされると、自動的にRunnerが再起動される可能性があります。

コマンドの概要

引数を指定せずにgitlab-runnerを実行すると、次のように表示されます:

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   17.10.1 (ef334dcc)

AUTHOR:
   GitLab Inc. <support@gitlab.com>

COMMANDS:
   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
   wrapper               start multi runner service wrapped with gRPC manager server
   fleeting              manage fleeting plugins
   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
   proxy-exec            execute internal commands (internal)
   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

以下で各コマンドの動作を詳しく説明します。

登録関連コマンド

新しいRunnerを登録するか、Runnerが登録されている場合にリストして検証するには、次のコマンドを使用します。

• gitlab-runner register
  • インタラクティブ登録
  • 非インタラクティブ登録
• gitlab-runner list
• gitlab-runner verify
• gitlab-runner unregister

これらのコマンドでは次の引数がサポートされています:

gitlab-runner register

このコマンドは、GitLab Runners APIを使用して、GitLabにRunnerを登録します。

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

Runnerは次のいずれかの方法で登録できます:

• インタラクティブ
• 非インタラクティブ

インタラクティブ登録

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

この質問に対する回答を事前に入力するには、登録コマンドの呼び出し時に引数を追加します:

gitlab-runner register --name my-runner --url "http://gitlab.example.com" --token my-authentication-token

あるいはregisterコマンドよりも前に環境変数を設定します:

export CI_SERVER_URL=http://gitlab.example.com
export RUNNER_NAME=my-runner
export CI_SERVER_TOKEN=my-authentication-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

[[runners]]設定テンプレートファイル

設定テンプレートファイル機能を使用して、Runnerの登録中に追加のオプションを設定できます。

gitlab-runner list

このコマンドは、設定ファイルに保存されているすべてのRunnerをリストします。

gitlab-runner verify

このコマンドは、登録されたRunnerがGitLabに接続できることを確認します。ただし、Runnerが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を削除するには、次のコマンドを実行します。

gitlab-runner verify --delete

gitlab-runner unregister

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

次のいずれかを指定する必要があります:

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

--all-runnersオプションを使用すると、アタッチされているすべてのRunnerの登録が解除されます。

• Runner登録トークンを使用してRunnerが作成された場合、Runner認証トークンを指定したgitlab-runner unregisterを実行すると、Runnerが削除されます。
• RunnerがGitLab UIまたはRunners APIで作成された場合、Runner認証トークンを指定してgitlab-runner unregisterを実行すると、Runnerマネージャーが削除されますが、Runnerは削除されません。Runnerを完全に削除するには、Runner管理ページでRunnerを削除するか、DELETE /runners REST APIエンドポイントを使用します。

1つのRunnerを登録解除するには、まずgitlab-runner listを実行してRunnerの詳細を取得します:

test-runner     Executor=shell Token=t0k3n URL=http://gitlab.example.com

次にこの情報を使用して、次のいずれかのコマンドで登録を解除します。

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 Runners APIを使用して、Runner IDまたは現在のトークンのいずれかでRunnerのトークンをリセットします。

Runnerの名前（またはURLとID）が必要です。Runner 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
• 複数のサービス
• サービス関連コマンドの実行時にアクセスが拒否されました

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

gitlab-runner install

このコマンドは、GitLab Runnerをサービスとしてインストールします。受け入れられる引数のセットは、実行するシステムに応じて異なります。

Windows（Windows）で実行する場合、またはスーパーユーザーとして実行する場合は、--userフラグが受け入れられます。このフラグにより、shell（Shell） executorで実行されるビルドの権限を削除できます。

gitlab-runner uninstall

このコマンドは、GitLab Runnerがサービスとして実行されないようにするため、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サービスをインストールできます。

ユーザーサービス

一部のinitシステム（systemdなど）を使用することにより、サービスをユーザーサービスとして管理できます。initシステムにこの機能が含まれている場合、gitlab-runnerサービスをユーザーサービスとして管理するには、サービス関連のコマンドを実行する際に--user-serviceフラグを指定します。

実行関連コマンド

このコマンドを使用すると、GitLabからビルドをフェッチして処理できます。

gitlab-runner run

gitlab-runner runコマンドは、GitLab Runnerがサービスとして開始されたときに実行されるメインコマンドです。config.tomlから定義されているすべてのRunnerを読み取り、それらすべてを実行しようとします。

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

次のパラメータを受け入れます。

gitlab-runner run-single

1つのGitLabインスタンスから1つのビルドを実行するには、この補助コマンドを使用します。このコマンドでは次のことができます:

• GitLab URLやRunnerトークンなど、すべてのオプションをCLIパラメータまたは環境変数として取ります。たとえば、すべてのパラメータが明示的に指定されたシングルジョブの場合は次のようになります:

  gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:3.3

• 設定ファイルを読み取って、特定のRunnerの設定を使用します。たとえば、設定ファイルが指定されたシングルジョブの場合は次のようになります:

  gitlab-runner run-single -c ~/.gitlab-runner/config.toml -r runner-name

--helpフラグを使用すると、使用可能なすべての設定オプションを確認できます:

gitlab-runner run-single --help

--max-buildsオプションを使用して、Runnerが終了するまでに実行するビルドの数を制御できます。デフォルトの0は、Runnerにビルド制限がなく、ジョブが永久に実行されることを意味します。

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

内部コマンド

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が正常にシャットダウンしない

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

これを防ぐには、次の2つの方法があります:

• kill（強制終了）シグナルとしてSIGQUITを使用して、Runnerをローカルサービス（systemdなど）として登録し、gitlab-runner stopまたはsystemctl stop gitlab-runner.serviceを使用します。この動作を有効にするための設定例を次に示します:

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

  • 設定の変更を適用するには、このファイルを作成した後、systemctl daemon-reloadを使用してsystemdを再読み込みします。

• kill -SIGQUIT <pid>を使用してプロセスを手動で強制終了します。メインのgitlab-runnerプロセスのpidを確認する必要があります。これを確認するには、起動時に表示されるログを調べます:

  $ gitlab-runner run
  Runtime platform                                    arch=arm64 os=linux pid=8 revision=853330f9 version=16.5.0

システムIDステートファイルの保存: アクセスが拒否される

GitLab Runner 15.7および15.8は、config.tomlファイルを含むディレクトリに対する書き込み権限がない場合、起動しない可能性があります。

GitLab Runnerは起動時に、config.tomlを含むディレクトリにある.runner_system_idファイルを検索します。.runner_system_idファイルが見つからない場合、新しいファイルを作成します。GitLab Runnerに書き込み権限がない場合、起動が失敗します。

この問題を解決するには、一時的にファイル書き込み権限を許可してgitlab-runner runを実行します。.runner_system_idファイルが作成されたら、権限を読み取り専用にリセットできます。