高度な設定

GitLab Runnerと個別に登録されたRunnerの動作を変更するには、config.tomlファイルを修正します。

config.tomlファイルは次の場所にあります。

• GitLab Runnerがrootとして実行される場合、*nixシステムでは/etc/gitlab-runner/にあります。このディレクトリは、サービス設定のパスでもあります。
• GitLab Runnerが非rootユーザーとして実行される場合、*nixシステムでは~/.gitlab-runner/にあります。
• その他のシステムの./。

ほとんどのオプションでは、オプションを変更した場合にGitLab Runnerを再起動する必要はありません。これには、[[runners]]セクションのパラメータとlisten_addressを除くグローバルセクションのほとんどのパラメータが含まれます。Runnerがすでに登録されている場合は、再度登録する必要はありません。

GitLab Runnerは、設定の変更を3秒ごとに確認し、必要に応じて再読み込みします。またGitLab Runnerは、SIGHUPシグナルに応答して設定を再読み込みします。

設定検証

設定検証は、config.tomlファイルの構造をチェックするプロセスです。設定バリデーターからの出力は、infoレベルのメッセージのみを示します。

設定検証プロセスは、情報提供のみを目的としています。この出力から、Runner設定に関する潜在的な問題を特定できます。設定検証では、起こり得るすべての問題を検出できるとは限りません。また、メッセージがないからといって、config.tomlファイルに欠陥がないことが保証されるわけではありません。

グローバルセクション

これらの設定はグローバルなものです。すべてのRunnerに適用されます。

設定の警告

ロングポーリングのイシュー

GitLab Runnerは、GitLabのロングポーリングがGitLab Workhorseを介してオンになっている場合、いくつかの設定シナリオでロングポーリングのイシューが発生する可能性があります。これらは、設定に応じて、パフォーマンスのボトルネックから重大な処理遅延まで多岐にわたります。GitLab Runnerのワーカーは、長時間（GitLab Workhorseの設定である-apiCiLongPollingDuration（デフォルトは50秒）と一致）ロングポーリングリクエストで停止し、他のジョブが迅速に処理されるのを妨げる可能性があります。

このイシューは、GitLab Workhorseの-apiCiLongPollingDuration設定によって制御されるGitLab CI/CDのロングポーリング機能に関連しています。オンにすると、ジョブリクエストは、ジョブが利用可能になるのを待機している間、設定された時間までブロックされる可能性があります。

デフォルトのGitLab Workhorseのロングポーリングの設定値は50秒です（最近のGitLabバージョンではデフォルトでオンになっています）。

次に、設定例をいくつか示します:

• Omnibus：gitlab_workhorse['api_ci_long_polling_duration'] = "50s" in /etc/gitlab/gitlab.rb
• Helmチャート: gitlab.webservice.workhorse.extraArgs設定を使用
• CLI：gitlab-workhorse -apiCiLongPollingDuration 50s

詳細については、以下を参照してください:

• Runnerのロングポーリング
• Workhorseの設定

Symptoms:

• 一部のプロジェクトからのジョブは、開始前に遅延が発生します（時間は、GitLabインスタンスのロングポーリングのタイムアウトと一致します）。
• 他のプロジェクトからのジョブはすぐに実行されます
• Runnerログの警告メッセージ：CONFIGURATION: Long polling issues detected

Common problematic scenarios:

• ワーカーのスターベーションボトルネック: concurrent設定がRunnerの数よりも少ない（重大なボトルネック）
• リクエストのボトルネック: request_concurrency=1のRunnerは、ロングポーリング中にジョブの遅延を引き起こします
• ビルド制限のボトルネック: limit設定（≤2）が低いRunnerとrequest_concurrency=1の組み合わせ

Solution options:

GitLab Runnerは、問題のあるシナリオを自動的に検出し、警告メッセージで調整されたソリューションを提供します。一般的な解決策は次のとおりです:

• Runnerの数を超えるようにconcurrent設定を増やします。
• 高ボリュームのRunnerのrequest_concurrency値を1より大きい値に設定します（デフォルトは1）。システムのステートを理解し、設定に最適な値を見つけるために、Runnerのモニタリングをオンにすることを検討してください。ワークロードに基づいてrequest_concurrencyを自動的に調整するには、FF_USE_ADAPTIVE_REQUEST_CONCURRENCY機能フラグを使用することを検討してください。適応的な並行処理については、機能フラグのドキュメントを参照してください。
• limit設定と予想されるジョブボリュームのバランスを取ります。

Example problematic configurations:

シナリオ1: ワーカーのスターベーションボトルネック

concurrent = 2  # Only 2 concurrent workers

[[runners]]
  name = "runner-1"
[[runners]]
  name = "runner-2"
[[runners]]
  name = "runner-3"  # 3 runners, only 2 workers - severe bottleneck

シナリオ2: リクエストのボトルネック

concurrent = 4  # 4 workers available

[[runners]]
  name = "high-volume-runner"
  request_concurrency = 1  # Default: only 1 request at a time
  limit = 10               # Can handle 10 jobs, but only 1 request slot

シナリオ3: ビルド制限のボトルネック

concurrent = 4

[[runners]]
  name = "limited-runner"
  limit = 2                # Only 2 builds allowed
  request_concurrency = 1  # Only 1 request at a time
  # Creates severe bottleneck: builds at capacity + request slot blocked by long polling

Example corrected configuration:

concurrent = 4  # Adequate worker capacity

[[runners]]
  name = "high-volume-runner"
  request_concurrency = 3  # Allow multiple simultaneous requests
  limit = 10

[[runners]]
  name = "balanced-runner"
  request_concurrency = 2
  limit = 5

設定例

# Example `config.toml` file

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file
log_level = "warning"
log_format = "text"
check_interval = 3 # Value in seconds

[[runners]]
  name = "first"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "shell"
  (...)

[[runners]]
  name = "second"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker"
  (...)

[[runners]]
  name = "third"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker-autoscaler"
  (...)

log_formatの例（一部）

runner

Runtime platform                                    arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...

Configuration loaded                                builds=0
listen_address not defined, metrics & debug endpoints disabled  builds=0
[session_server].listen_address not defined, session endpoints disabled  builds=0

text

INFO[0000] Runtime platform                              arch=amd64 os=darwin pid=37773 revision=HEAD version="development version"
INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...
INFO[0000]
INFO[0000] Configuration loaded                          builds=0
INFO[0000] listen_address not defined, metrics & debug endpoints disabled  builds=0
INFO[0000] [session_server].listen_address not defined, session endpoints disabled  builds=0

json

{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2025-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2025-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Running in user-mode.","time":"2025-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Use sudo for system-mode:","time":"2025-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2025-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2025-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"Configuration loaded","time":"2025-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2025-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2025-06-05T15:57:35+02:00"}

check_intervalの仕組み

config.tomlに複数の[[runners]]セクションが含まれている場合、GitLab Runnerは設定されているGitlabインスタンスに対して、ジョブリクエストを継続的にスケジュールするループ処理を行います。

次の例では、check_intervalが10秒で、2つの[[runners]]セクション（runner-1とrunner-2）があります。GitLab Runnerは10秒ごとにリクエストを送信し、5秒間スリープします。

1. check_intervalの値（10s）を取得します。
2. Runnerのリスト（runner-1、runner-2）を取得します。
3. スリープ間隔（10s / 2 = 5s）を計算します。
4. 無限ループを開始します。
   1. runner-1のジョブをリクエストします。
   2. 5s（5秒間）スリープします。
   3. runner-2のジョブをリクエストします。
   4. 5s（5秒間）スリープします。
   5. 繰り返します。

check_interval設定例

# Example `config.toml` file

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file.
log_level = "warning"
log_format = "json"
check_interval = 10 # Value in seconds

[[runners]]
  name = "runner-1"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "shell"
  (...)

[[runners]]
  name = "runner-2"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker"
  (...)

この例では、Runnerのプロセスからのジョブリクエストが5秒ごとに行われます。runner-1とrunner-2が同じGitlabインスタンスに接続されている場合、このGitlabインスタンスも5秒ごとにこのRunnerから新しいリクエストを受信します。

runner-1の最初のリクエストから次のリクエストまでの間に、合計で2回のスリープ期間が発生します。各期間の長さは5秒であるため、runner-1のリクエストの間隔は約10秒です。runner-2にも同じことが当てはまります。

定義するRunnerが多いと、スリープ間隔は短くなります。ただし、Runnerに対するリクエストが繰り返されるのは、他のすべてのRunnerに対するリクエストとそれぞれのスリープ期間が実行された後になります。

[session_server]セクション

ジョブを操作するには、[[runners]]セクションの外側のルートレベルで[session_server]セクションを指定します。このセクションは、個々のRunnerごとではなく、すべてのRunnerに対して1回だけ設定を行います。

# Example `config.toml` file with session server configured

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file
log_level = "warning"
log_format = "runner"
check_interval = 3 # Value in seconds

[session_server]
  listen_address = "[::]:8093" # Listen on all available interfaces on port `8093`
  advertise_address = "runner-host-name.tld:8093"
  session_timeout = 1800

[session_server]セクションを設定する場合

• listen_addressとadvertise_addressには、host:portという形式を使用します。ここで、hostはIPアドレス（127.0.0.1:8093）またはドメイン（my-runner.example.com:8093）です。Runnerはこの情報を使用して、セキュアな接続のためのTLS証明書を作成します。
• listen_addressまたはadvertise_addressで定義されているIPアドレスとポートにGitLabが接続できることを確認します。
• アプリケーション設定allow_local_requests_from_web_hooks_and_servicesを有効にしていない場合は、advertise_addressがパブリックIPアドレスであることを確認してください。

セッションサーバーとターミナルサポートを無効にするには、[session_server]セクションを削除します。

GitLab Runner Dockerイメージを使用している場合は、docker runコマンドに-p 8093:8093を追加して、ポート8093を公開する必要があります。

[[runners]]セクション

各[[runners]]セクションは1つのRunnerを定義します。

例:

[[runners]]
  name = "example-runner"
  url = "http://gitlab.example.com/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
  clone_url = "http://gitlab.example.local"

従来の/ci URLサフィックス

1.0.0より前のバージョンのGitLab Runnerでは、RunnerのURLは/ciサフィックスで設定されていました（例：url = "https://gitlab.example.com/ci"）。このサフィックスは不要になったため、設定から削除する必要があります。

config.tomlに/ciサフィックスを含むURLが含まれている場合、GitLab Runnerは設定を処理するときに自動的にそれを削除します。ただし、イシューの可能性を回避するために、設定ファイルを更新してサフィックスを削除する必要があります。

既知の問題

• Gitサブモジュールの認証の失敗: GIT_SUBMODULE_FORCE_HTTPS=trueが設定されている場合、サブモジュールはfatal: could not read Username for 'https://gitlab.example.com': terminal prompts disabledのような認証エラーでクローンに失敗する可能性があります。このイシューは、/ciサフィックスがGit URLの書き換えルールを妨げるために発生します。詳しくは、issue 581678をご覧ください。

Problematic configuration:

[[runners]]
  name = "legacy-runner"
  url = "https://gitlab.example.com/ci"  # Remove the /ci suffix
  token = "TOKEN"
  executor = "docker"

Corrected configuration:

[[runners]]
  name = "legacy-runner"
  url = "https://gitlab.example.com"  # /ci suffix removed
  token = "TOKEN"
  executor = "docker"

GitLab Runnerが/ciサフィックスを含むURLで起動すると、警告メッセージをログに記録します:

WARNING: The runner URL contains a legacy '/ci' suffix. This suffix is deprecated and should be
removed from the configuration. Git submodules may fail to clone with authentication errors if this
suffix is present. Please update the 'url' field in your config.toml to remove the '/ci' suffix.
See https://docs.gitlab.com/runner/configuration/advanced-configuration.html#legacy-ci-url-suffix for more information.

この警告を解決するには、config.tomlファイルを編集し、urlフィールドから/ciサフィックスを削除します。

clone_urlの仕組み

Runnerが使用できないURLでGitLabインスタンスが利用可能な場合は、clone_urlを設定できます。

たとえば、ファイアウォールが原因でRunnerがURLにアクセスできない場合があります。Runnerが192.168.1.23上のノードに接続できる場合は、clone_urlをhttp://192.168.1.23に設定します。

clone_urlが設定されると、Runnerはhttp://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.gitの形式でクローンURLを作成します。

Git LFSエンドポイントを変更する

Git LFSエンドポイントを変更するには、次のいずれかのファイルでpre_get_sources_scriptを設定します。

• config.toml:

  pre_get_sources_script = "mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template; git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://<alternative-endpoint>"

• .gitlab-ci.yml:

  default:
    hooks:
      pre_get_sources_script:
        - mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template
        - git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://localhost

unhealthy_requests_limitとunhealthy_intervalの仕組み

GitLabインスタンスが長期間使用できない場合（バージョンのアップグレード中など）、そのRunnerはアイドル状態になります。GitLabインスタンスが再び使用可能になっても、Runnerは後の30～60分間は、ジョブ処理を再開しません。

Runnerがアイドル状態になる期間を増減するには、unhealthy_interval設定を変更します。

RunnerのGitLabサーバーへの接続試行回数を変更し、アイドル状態になる前に異常なスリープを受信するには、unhealthy_requests_limit設定を変更します。詳細については、check_intervalの仕組みを参照してください。

executor

次のexecutorを使用できます。

Shell

Shell executorを使用するように設定されている場合、CI/CDジョブはホストマシンでローカルに実行されます。サポートされているオペレーティングシステムのShellは次のとおりです。

shellオプションがbashまたはshに設定されている場合、BashのANSI-C引用符の処理方法を使用して、ジョブスクリプトがShellエスケープされます。

POSIX準拠のShellを使用する

GitLab Runner 14.9以降では、dashなどのPOSIX準拠のShellを使用するには、FF_POSIXLY_CORRECT_ESCAPES機能フラグを有効にします。有効にすると、POSIX準拠のShellエスケープメカニズムである二重引用符が使用されます。

[runners.docker]セクション

次の設定は、Dockerコンテナのパラメータを定義します。これらの設定は、Docker executorを使用するようにRunnerが設定されている場合に適用されます。

サービスとしてのDocker-in-Docker、またはジョブ内で設定されているコンテナランタイムは、これらのパラメータを継承しません。

[[runners.docker.services]]セクション

ジョブと実行する追加のサービスを指定します。利用可能なイメージのリストについては、Docker Registryを参照してください。各サービスは個別のコンテナで実行され、ジョブにリンクされます。

例:

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  memory = "128m"
  memory_swap = "256m"
  memory_reservation = "64m"
  oom_kill_disable = false
  cpuset_cpus = "0,1"
  cpuset_mems = "0,1"
  cpus = "2"
  dns = ["8.8.8.8"]
  dns_search = [""]
  service_memory = "128m"
  service_memory_swap = "256m"
  service_memory_reservation = "64m"
  service_cpuset_cpus = "0,1"
  service_cpus = "2"
  services_limit = 5
  privileged = false
  group_add = ["docker"]
  cap_add = ["NET_ADMIN"]
  cap_drop = ["DAC_OVERRIDE"]
  devices = ["/dev/net/tun"]
  disable_cache = false
  wait_for_services_timeout = 30
  cache_dir = ""
  volumes = ["/data", "/home/project/cache"]
  extra_hosts = ["other-host:127.0.0.1"]
  shm_size = 300000
  volumes_from = ["storage_container:ro"]
  links = ["mysql_container:mysql"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9", "redis:*", "mysql:*"]
  [runners.docker.ulimit]
    "rtprio" = "99"
  [[runners.docker.services]]
    name = "registry.example.com/svc1"
    alias = "svc1"
    entrypoint = ["entrypoint.sh"]
    command = ["executable","param1","param2"]
    environment = ["ENV1=value1", "ENV2=value2"]
  [[runners.docker.services]]
    name = "redis:2.8"
    alias = "cache"
  [[runners.docker.services]]
    name = "postgres:9"
    alias = "postgres-db"
  [runners.docker.sysctls]
    "net.ipv4.ip_forward" = "1"

[runners.docker]セクションのボリューム

ボリュームの詳細については、Dockerのドキュメントを参照してください。

次の例は、[runners.docker]セクションでボリュームを指定する方法を示しています。

例1: データボリュームを追加する

データボリュームは、1つ以上のコンテナ内で特別に指定されたディレクトリで、Union File Systemをバイパスします。データボリュームは、コンテナのライフサイクルに依存せず、データを永続化するように設計されています。

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/volume/in/container"]

この例では、コンテナ内の/path/to/volume/in/containerという場所に新しいボリュームが作成されます。

例2: ホストディレクトリをデータボリュームとしてマウントする

コンテナの外部にディレクトリを保存する場合は、Dockerデーモンのホストからコンテナにディレクトリをマウントできます。

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]

この例では、CI/CDホストの/path/to/bind/from/hostをコンテナ内の/path/to/bind/in/containerで使用します。

GitLab Runner 11.11以降では、定義されたサービスについても同様にホストディレクトリをマウントします。

プライベートコンテナレジストリを使用する

ジョブのイメージのソースとしてプライベートレジストリを使用するには、CI/CD変数DOCKER_AUTH_CONFIGを使用して認証を設定します。次のいずれかで変数を設定できます。

• プロジェクトのCI/CD設定内でfileタイプとして設定
• config.tomlファイル内で設定

if-not-presentプルポリシーでプライベートレジストリを使用すると、セキュリティ上の影響が生じる可能性があります。プルポリシーの仕組みの詳細については、Runnerがイメージをプルする方法を設定するを参照してください。

プライベートコンテナレジストリの使用に関する詳細については、以下を参照してください。

• プライベートコンテナレジストリからのイメージへのアクセス
• .gitlab-ci.ymlキーワードリファレンス

Runnerによって実行されるステップの要約を次に示します。

1. レジストリ名がイメージ名から検出されます。
2. 値が空でない場合、executorはこのレジストリに対する認証設定を検索します。
3. 最後に、指定されたレジストリに対応する認証が見つかった場合、以降のプルではその認証が使用されます。

GitLab統合レジストリのサポート

GitLabは、ジョブのデータとともに、統合レジストリの認証情報を送信します。これらの認証情報は、レジストリの認証パラメータリストに自動的に追加されます。

このステップの後、レジストリに対する認証は、DOCKER_AUTH_CONFIG変数で追加された設定と同様に進みます。

ジョブでは、GitLab統合レジストリのイメージがプライベートまたは保護されている場合でも、任意のイメージを使用できます。ジョブがアクセスできるイメージの詳細については、CI/CDジョブトークンのドキュメントを参照してください。

Docker認証解決の優先順位

前述のように、GitLab Runnerはさまざまな方法で送信される認証情報を使用して、レジストリに対してDockerを認証できます。適切なレジストリを見つけるために、次の優先順位が考慮されます。

1. DOCKER_AUTH_CONFIGで設定された認証情報
2. GitLab Runnerホストでローカルに設定された認証情報（~/.docker/config.jsonまたは~/.dockercfgファイルに保存）（例: ホストでdocker loginを実行した場合）。
3. ジョブのペイロードとともにデフォルトで送信される認証情報（例: 前述の統合レジストリの認証情報）。

レジストリに対して最初に検出された認証情報が使用されます。たとえば、DOCKER_AUTH_CONFIG変数を使用して統合レジストリの認証情報を追加すると、デフォルトの認証情報が上書きされます。

[runners.parallels]セクション

次にParallelsのパラメータを示します。

例:

[runners.parallels]
  base_name = "my-parallels-image"
  template_name = ""
  disable_snapshots = false

[runners.virtualbox]セクション

次にVirtualBoxのパラメータを示します。このexecutorは、VirtualBoxマシンを制御するためにvboxmanage実行可能ファイルに依存しています。そのため、WindowsホストではPATH環境変数を調整する必要があります（PATH=%PATH%;C:\Program Files\Oracle\VirtualBox）。

例:

[runners.virtualbox]
  base_name = "my-virtualbox-image"
  base_snapshot = "my-image-snapshot"
  disable_snapshots = false
  start_type = "headless"

start_typeパラメータは、仮想イメージの起動時に使用されるグラフィカルフロントエンドを決定します。有効な値は、ホストとゲストの組み合わせでサポートされているheadless（デフォルト）、gui、またはseparateです。

ベースVMイメージを上書きする

Parallels executorとVirtualBox executorの両方で、base_nameで指定されたベースVM名を上書きできます。そのためには、.gitlab-ci.ymlファイルのimageパラメータを使用します。

下位互換性のため、デフォルトではこの値を上書きできません。base_nameで指定されたイメージのみが許可されます。

ユーザーが.gitlab-ci.ymlのimageパラメータを使用してVMイメージを選択できるようにするには、次のようにします。

[runners.virtualbox]
  ...
  allowed_images = [".*"]

この例では、既存のVMイメージであればどれでも使用できます。

allowed_imagesパラメータは、正規表現のリストです。必要な精度に応じて設定を細かく指定できます。たとえば、特定のVMイメージのみを許可したい場合は、次のような正規表現を使用できます。

[runners.virtualbox]
  ...
  allowed_images = ["^allowed_vm[1-2]$"]

この例では、allowed_vm1とallowed_vm2のみが許可されます。その他の試行はすべてエラーになります。

[runners.ssh]セクション

次のパラメータは、SSH接続を定義します。

例:

[runners.ssh]
  host = "my-production-server"
  port = "22"
  user = "root"
  password = "production-server-password"
  identity_file = ""

[runners.machine]セクション

次のパラメータは、Docker Machineベースのオートスケール機能を定義します。詳細については、Docker Machine Executorのオートスケール設定を参照してください。

[[runners.machine.autoscaling]]セクション

次のパラメータは、Instance executorまたはDocker Autoscaler executorを使用する際に利用可能な設定を定義します。

例:

[runners.machine]
  IdleCount = 5
  IdleTime = 600
  MaxBuilds = 100
  MachineName = "auto-scale-%s"
  MachineDriver = "google" # Refer to Docker Machine docs on how to authenticate: https://docs.docker.com/machine/drivers/gce/#credentials
  MachineOptions = [
      # Additional machine options can be added using the Google Compute Engine driver.
      # If you experience problems with an unreachable host (ex. "Waiting for SSH"),
      # you should remove optional parameters to help with debugging.
      # https://docs.docker.com/machine/drivers/gce/
      "google-project=GOOGLE-PROJECT-ID",
      "google-zone=GOOGLE-ZONE", # e.g. 'us-central1-a', full list in https://cloud.google.com/compute/docs/regions-zones/
  ]
  [[runners.machine.autoscaling]]
    Periods = ["* * 9-17 * * mon-fri *"]
    IdleCount = 50
    IdleCountMin = 5
    IdleScaleFactor = 1.5 # Means that current number of Idle machines will be 1.5*in-use machines,
                          # no more than 50 (the value of IdleCount) and no less than 5 (the value of IdleCountMin)
    IdleTime = 3600
    Timezone = "UTC"
  [[runners.machine.autoscaling]]
    Periods = ["* * * * * sat,sun *"]
    IdleCount = 5
    IdleTime = 60
    Timezone = "UTC"

periods構文

Periods設定は、cron形式で表される時間帯の文字列パターンを集めた配列です。行は次のフィールドで構成されます。

[second] [minute] [hour] [day of month] [month] [day of week] [year]

標準のcron設定ファイルと同様に、これらのフィールドには単一値、範囲、リスト、およびアスタリスクを含めることができます。構文の詳細な説明を参照してください。

[runners.instance]セクション

[runners.autoscaler]セクション

次のパラメータは、オートスケーラー機能を設定します。これらのパラメータは、インスタンス executorとDocker Autoscaler executorでのみ使用できます。

[runners.autoscaler.plugin_config]セクション

このハッシュテーブルはJSONに再エンコードされ、設定済みのプラグインに直接渡されます。

フリートプラグインには通常、サポートされている設定に関するドキュメントが付いています。

[runners.autoscaler.scale_throttle]セクション

limitとburstの関係

スケールスロットルは、トークンクォータシステムを使用してインスタンスを作成します。このシステムは、次の2つの値で定義されます。

• burst: クォータの最大サイズ。
• limit: 1秒あたりのクォータ更新レート。

一度に作成できるインスタンスの数は、残りのクォータによって決まります。十分なクォータがある場合は、その量までインスタンスを作成できます。クォータがなくなった場合は、1秒あたりlimitの数のインスタンスを作成できます。インスタンスの作成が停止すると、クォータは1秒あたりlimitずつ、burstの値に達するまで増加します。

たとえば、limitが1でburstが60の場合は、次のようになります。

• 60個のインスタンスを即時に作成できますが、制限（スロットル）されます。
• 60秒待機すると、さらに60個のインスタンスを即時に作成できます。
• 待機しない場合は、1秒ごとに1つのインスタンスを作成できます。

[runners.autoscaler.connector_config]セクション

フリートプラグインには通常、サポートされている接続オプションに関するドキュメントが付いています。

プラグインはコネクタ設定を自動的に更新します。[runners.autoscaler.connector_config]を使用して、コネクタ設定の自動更新を上書きしたり、プラグインが判断できない空の値を入力したりできます。

[runners.autoscaler.state_storage]セクション

ステートストレージが無効になっている場合（デフォルト）、GitLab Runnerが起動すると、安全上の理由から既存のフリートインスタンスは直ちに削除されます。たとえば、max_use_countが1に設定されている場合、使用状態がわからないと、すでに使用されているインスタンスに誤ってジョブを割り当ててしまう可能性があります。

ステートストレージ機能を有効にすると、インスタンスの状態をローカルディスクに保持できます。この場合、GitLab Runnerの起動時にインスタンスが存在していても、そのインスタンスは削除されません。キャッシュされた接続の詳細、使用回数、およびその他の設定が復元されます。

ステートストレージ機能を有効にする場合は、次の点を考慮してください。

• インスタンスの認証の詳細（ユーザー名、パスワード、キー）はディスクに残ります。

• インスタンスがジョブをアクティブに実行しているときにそのインスタンスが復元されると、GitLab Runnerはデフォルトでそのインスタンスを削除します。GitLab Runnerがジョブを再開できないため、この動作により安全性が確保されます。インスタンスを維持するには、keep_instance_with_acquisitionsをtrueに設定します。

  インスタンスで進行中のジョブについて特に懸念していない場合には、keep_instance_with_acquisitionsをtrueに設定すると役立ちます。また、instance_ready_command設定オプションを使用して環境をクリーンアップし、インスタンスを維持することもできます。この場合、実行中のすべてのコマンドを停止したり、Dockerコンテナを強制的に削除したりすることがあります。

[[runners.autoscaler.policy]]セクション

注 - ここでのidle_countはジョブの数を示し、従来のオートスケール方式のようにオートスケールされたマシンの数ではありません。

アイドル状態のインスタンスを削除するかどうかを決定するために、taskscalerはidle_timeをインスタンスのアイドル期間と比較します。各インスタンスのアイドル期間は、インスタンスが次の操作を行った時点から計算されます。

• 最後にジョブを完了した時点（インスタンスが以前に使用されていた場合）。
• プロビジョニングされた時点（未使用の場合）。

このチェックは、スケーリングイベント中に発生します。設定されているidle_timeを超えるインスタンスは、必要なidle_countジョブキャパシティを維持するために必要な場合を除き、削除されます。

scale_factorを設定すると、idle_countが最小のidle容量になり、scaler_factor_limitが最大のidle容量になります。

複数のポリシーを定義できます。最後に一致したポリシーが使用されます。

次の例では、アイドルカウント1は、月曜日から金曜日の08:00から15:59の間に使用されます。それ以外の場合、アイドルカウントは0です。

[[runners.autoscaler.policy]]
  idle_count        = 0
  idle_time         = "0s"
  periods           = ["* * * * *"]

[[runners.autoscaler.policy]]
  idle_count        = 1
  idle_time         = "30m0s"
  periods           = ["* 8-15 * * mon-fri"]

periods構文

periods設定には、ポリシーが有効になっている期間を示す、unix-cron形式の文字列の配列が含まれています。cron形式は、次の5つのフィールドで構成されています。

 ┌────────── minute (0 - 59)
 │ ┌──────── hour (0 - 23)
 │ │ ┌────── day of month (1 - 31)
 │ │ │ ┌──── month (1 - 12)
 │ │ │ │ ┌── day of week (1 - 7 or MON-SUN, 0 is an alias for Sunday)
 * * * * *

• -は、2つの数値の間で範囲を指定するときに使用できます。
• *は、そのフィールドの有効な値の範囲全体を表すときに使用できます。
• /に続く数字は、範囲内でその数字ごとにスキップするときに範囲の後に使用できます。たとえば、hourフィールドに0-12/2と指定すると、00:00から00:12の間、2時間ごとに期間がアクティブになります。
• ,は、フィールドの有効な数値または範囲のリストを区切るときに使用できます。たとえば、1,2,6-9などです。

このcronジョブは時間の範囲を表していることを覚えておいてください。例:

[runners.autoscaler.vm_isolation]セクション

VM分離はnestingを使用し、これはmacOSでのみサポートされています。

[runners.autoscaler.vm_isolation.connector_config]セクション

[runners.autoscaler.vm_isolation.connector_config]セクションのパラメータは、[runners.autoscaler.connector_config]セクションと同じですが、オートスケールされたインスタンスではなく、nestingでプロビジョニングされた仮想マシンへの接続に使用されます。

[runners.custom]セクション

次のパラメータは、カスタムexecutorの設定を定義します。

[runners.cache]セクション

次のパラメータは、分散キャッシュ機能を定義します。詳細については、Runnerオートスケールに関するドキュメントを参照してください。

以下の環境変数を使用して、キャッシュの圧縮を設定できます:

tarzstd形式は、zipよりも優れた圧縮率を提供する、Zstandard圧縮でTARを使用します。圧縮レベルの範囲は、fastest（最大速度を実現するための最小圧縮）からslowest（最小ファイルサイズを実現するための最大圧縮）です。defaultレベルは、圧縮率と速度のバランスの取れたトレードオフを提供します。

例:

job:
  variables:
    CACHE_COMPRESSION_FORMAT: tarzstd
    CACHE_COMPRESSION_LEVEL: fast

キャッシュメカニズムは、事前署名付きURLを使用してキャッシュをアップロードおよびダウンロードします。GitLab Runnerがそれ自体のインスタンスでURLに署名します。ジョブのスクリプト（キャッシュのアップロード/ダウンロードスクリプトを含む）がローカルマシンまたは外部マシンで実行されるかどうかは関係ありません。たとえば、shell executorやdocker executorは、GitLab Runnerプロセスが実行されているマシンでスクリプトを実行します。一方でvirtualboxやdocker+machineは、別のVMに接続してスクリプトを実行します。このプロセスは、キャッシュアダプターの認証情報が漏洩する可能性を最小限に抑えるというセキュリティ上の理由によるものです。

S3キャッシュアダプターがIAMインスタンスプロファイルを使用するように設定されている場合、このアダプターはGitLab Runnerマシンに接続されているプロファイルを使用します。GCSキャッシュアダプターがCredentialsFileを使用するように設定されている場合も同様です。このファイルがGitLab Runnerマシンに存在している必要があります。

次の表に、config.toml、registerのCLIオプションおよび環境変数を示します。これらの環境変数を定義すると、新しいGitLab Runnerを登録した後に、値がconfig.tomlに保存されます。

config.tomlからS3の認証情報を省略し、環境変数から静的な認証情報を読み込む場合は、AWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEYを定義できます。詳細については、AWS SDKデフォルト認証情報チェーンセクションを参照してください。

キャッシュキーの処理

GitLab Runner 18.4.0以降では、FF_HASH_CACHE_KEYS 機能フラグを使用してキャッシュキーにハッシュを付けることができます。

FF_HASH_CACHE_KEYSがオフになっている場合（デフォルト）、GitLab Runnerはキャッシュキーをサニタイズしてから、ローカルのキャッシュファイルとストレージバケット内のオブジェクトの両方のパスをビルドするために使用します。サニタイズによってキャッシュキーが変更された場合、GitLab Runnerはこの変更をログに記録します。GitLab Runnerがキャッシュキーをサニタイズできない場合、これもログに記録し、この特定のキャッシュは使用しません。

この機能フラグをオンにすると、GitLab Runnerはキャッシュキーにハッシュを付けてから、ローカルのキャッシュアーティファクトとリモートストレージバケット内のオブジェクトのパスをビルドするために使用します。GitLab Runnerは、キャッシュキーをサニタイズしません。どのキャッシュキーが特定のキャッシュアーティファクトを作成したかを理解できるように、GitLab Runnerはメタデータを添付します:

• ローカルのキャッシュアーティファクトの場合、GitLab Runnerは、キャッシュアーティファクトcache.zipの横にmetadata.jsonファイルを配置し、次のコンテンツを含めます:

  {"cachekey": "the human readable cache key"}

• 分散キャッシュのキャッシュアーティファクトの場合、GitLab Runnerはメタデータをストレージオブジェクトblobに直接添付し、キーcachekeyを付与します。クラウドプロバイダーのメカニズムを使用してクエリできます。例については、AWS S3のユーザー定義オブジェクトメタデータを参照してください。

[runners.cache.s3]セクション

次のパラメータは、キャッシュ用のS3ストレージを定義します。

例:

[runners.cache]
  Type = "s3"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.s3]
    ServerAddress = "s3.amazonaws.com"
    AccessKey = "AWS_S3_ACCESS_KEY"
    SecretKey = "AWS_S3_SECRET_KEY"
    BucketName = "runners-cache"
    BucketLocation = "eu-west-1"
    Insecure = false
    ServerSideEncryption = "KMS"
    ServerSideEncryptionKeyID = "alias/my-key"

認証

GitLab Runnerは、設定に基づいてS3に異なる認証方法を使用します。

静的な認証情報

Runnerは、次の場合に静的アクセスキー認証を使用します:

• ServerAddress、AccessKey、およびSecretKeyパラメータが仕様されていますが、AuthenticationTypeは提供されていません。
• AuthenticationType = "access-key"が明示的に設定されています。

AWS SDKのデフォルト認証情報チェーン

Runnerは、次の場合にAWS SDKのデフォルト認証情報チェーンを使用します:

• ServerAddress、AccessKey、またはSecretKeyのいずれかが省略され、AuthenticationTypeが提供されていません。
• AuthenticationType = "iam"が明示的に設定されています。

この認証情報チェーンは、次の順序で認証を試みます:

1. 環境変数（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）
2. 共有認証情報ファイル（~/.aws/credentials）
3. IAMインスタンスプロファイル（EC2インスタンスの場合）
4. SDKでサポートされている他のAWS認証情報ソース

RoleARNが仕様されていない場合、デフォルトの認証情報チェーンはRunnerマネージャーによって実行されます。これは、ビルドが実行されるマシンと同じマシン上にあるとは限りません。たとえば、オートスケールするの設定では、ジョブは別のマシンで実行されます。同様に、Kubernetesエグゼキューターを使用すると、ビルドポッドもRunnerマネージャーとは異なるノードで実行できます。この動作により、Runnerマネージャーにのみバケットレベルのアクセス権を付与できます。

RoleARNが仕様されている場合、認証情報はヘルパーイメージの実行コンテキスト内で解決されます。詳細については、RoleARNを参照してください。

Helmチャートを使用してGitLab Runnerをインストールし、rbac.createがvalues.yamlファイルでtrueに設定されている場合、サービスアカウントが作成されます。サービスアカウントの注釈は、rbac.serviceAccountAnnotationsセクションから取得されます。

Amazon EKSのRunnerの場合、サービスアカウントに割り当てるIAMロールを指定できます。必要な特定のアノテーションはeks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>です。

このロールのIAMポリシーには、指定されたバケットに対して次のアクションを実行する権限が必要です。

• s3:PutObject
• s3:GetObjectVersion
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket

KMSタイプのServerSideEncryptionを使用する場合、このロールには、指定されたAWS KMSキーに対して次のアクションを実行する権限も必要です。

• kms:Encrypt
• kms:Decrypt
• kms:ReEncrypt*
• kms:GenerateDataKey*
• kms:DescribeKey

SSE-CタイプのServerSideEncryptionはサポートされていません。SSE-Cでは、事前署名付きURLに加えて、ユーザー提供のキーを含むヘッダーをダウンロードリクエストに対して指定する必要があります。これは、ジョブにキーマテリアルを渡すことになり、キーの安全を保証できません。これにより、復号化キーが漏洩する可能性があります。この問題に関するディスカッションについては、このマージリクエストを参照してください。

Runnerキャッシュ用のS3バケットでKMSキー暗号化を使用する

GenerateDataKey APIはKMS対称キーを使用して、クライアント側の暗号化（https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html）用のデータキーを作成します。KMSキーの正しい設定は次のとおりです。

rbac.serviceAccountNameで定義されたServiceAccountに割り当てられたロールのIAMポリシーには、KMSキーに対して次のアクションを実行する権限が必要です。

• kms:GetPublicKey
• kms:Decrypt
• kms:Encrypt
• kms:DescribeKey
• kms:GenerateDataKey

RoleARNでマルチパート転送を有効にする

キャッシュへのアクセスを制限するために、Runnerマネージャーは時間制限のある事前署名付きURLを生成し、ジョブがキャッシュからのダウンロードやキャッシュへアップロードを行えるようにします。ただし、AWS S3では1つのPUTリクエストが5 GBに制限されています。5 GBを超えるファイルの場合は、マルチパートアップロードAPIを使用する必要があります。

マルチパート転送は、AWS S3でのみサポートされており、他のS3プロバイダーではサポートされていません。Runnerマネージャーはさまざまなプロジェクトのジョブを処理することから、バケット全体の権限を含むS3認証情報を渡すことができません。代わりに、Runnerマネージャーは時間制限のある事前署名付きURLと範囲が限定された認証情報を使用して、特定のオブジェクトへのアクセスを制限します。

AWSでS3マルチパート転送を使用するには、RoleARNにarn:aws:iam:::<ACCOUNT ID>:<YOUR ROLE NAME>形式でIAMロールを指定します。このロールは、バケット内の特定のblobへの書き込みに限定された、時間制限のあるAWS認証情報を生成します。元のS3認証情報が、指定されたRoleARNのAssumeRoleにアクセスできることを確認してください。

RoleARNで指定されたIAMロールには、次の権限が必要です。

• BucketNameで指定されたバケットへのs3:GetObjectアクセス権。
• BucketNameで指定されたバケットへのs3:PutObjectアクセス権。
• BucketNameで指定されたバケットへのs3:ListBucketアクセス権。
• KMSまたはDSSE-KMSを使用したサーバー側の暗号化が有効になっている場合は、kms:Decryptとkms:GenerateDataKey権限。

たとえば、ARN arn:aws:iam::1234567890123:role/my-instance-roleを持つEC2インスタンスにmy-instance-roleという名前のIAMロールが添付されているとします。

この場合、BucketNameに対してs3:PutObject権限のみを持つ新しいロールarn:aws:iam::1234567890123:role/my-upload-roleを作成できます。my-instance-roleのAWS設定では、Trust relationshipsは次のようになります。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::1234567890123:role/my-upload-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

my-instance-roleをRoleARNとして再利用して、新しいロールの作成を回避することもできます。その場合は、my-instance-roleにAssumeRole権限があることを確認してください。たとえば、EC2インスタンスに関連付けられているIAMプロファイルのTrust relationshipsは次のようになります。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com",
                "AWS": "arn:aws:iam::1234567890123:role/my-instance-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

AWSコマンドラインインターフェースを使用して、インスタンスにAssumeRole権限があることを確認できます。例:

aws sts assume-role --role-arn arn:aws:iam::1234567890123:role/my-upload-role --role-session-name gitlab-runner-test1

RoleARNによるアップロードの仕組み

RoleARNが設定されている場合、Runnerがキャッシュにアップロードするたびに次の処理が行われます。

1. Runnerマネージャーは、（AuthenticationType、AccessKey、SecretKeyで指定された）元のS3認証情報を取得します。

2. RunnerマネージャーはこのS3認証情報を使用して、Amazon Security Token Service（STS）にRoleARNを使ったAssumeRoleのリクエストを送信します。ポリシーリクエストは次のようになります。

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": ["s3:PutObject"],
               "Resource": "arn:aws:s3:::<YOUR-BUCKET-NAME>/<CACHE-FILENAME>"
           }
       ]
   }

3. リクエストが成功した場合、Runnerマネージャーは制限付きセッションで一時的なAWS認証情報を取得します。

4. Runnerマネージャーは、これらの認証情報とURLをs3://<bucket name>/<filename>形式でキャッシュアーカイバーに渡し、キャッシュアーカイバーがファイルをアップロードします。

Kubernetes ServiceAccountリソース用のIAMロールを有効にする

サービスアカウントにIAMロールを使用するには、IAM OIDCプロバイダーがクラスター用に存在する必要があります。IAM OIDCプロバイダーがクラスターに関連付けられたら、IAMロールを作成してRunnerのサービスアカウントに関連付けることができます。

1. Create Role（ロール作成）画面のSelect type of trusted entity（信頼されたエンティティのタイプを選択）で、Web Identity（Web ID）を選択します。

2. ロールのTrusted Relationships（信頼関係）タブで次のようにします。

   • Trusted entities（信頼されたエンティティ）セクションの形式はarn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>である必要があります。OIDC IDは、Amazon EKSクラスターのConfiguration（設定）タブにあります。

   • Condition（条件）セクションには、rbac.serviceAccountNameで定義されたGitLab Runnerサービスアカウント、またはrbac.createがtrueに設定されている場合に作成されるデフォルトのサービスアカウントが必要です。

     条件	キー	値
     StringEquals	oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:sub	system:serviceaccount:<GITLAB_RUNNER_NAMESPACE>:<GITLAB_RUNNER_SERVICE_ACCOUNT>

S3 Express One Zoneバケットを使用する

1. Amazonのチュートリアルに従って、S3 Express One Zoneバケットを設定します。
2. BucketNameとBucketLocationを使用してconfig.tomlを設定します。
3. S3 Expressはデュアルスタックエンドポイントをサポートしていないため、DualStackをfalseに設定します。

config.tomlの例

[runners.cache]
  Type = "s3"
  [runners.cache.s3]
    BucketName = "example-express--usw2-az1--x-s3"
    BucketLocation = "us-west-2"
    DualStack = false

[runners.cache.gcs]セクション

次のパラメータは、Google Cloud Storageのネイティブサポートを定義します。これらの値の詳細については、Google Cloud Storage（GCS）の認証に関するドキュメントを参照してください。

例:

config.tomlファイルで直接設定された認証情報

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    AccessID = "cache-access-account@test-project-123456.iam.gserviceaccount.com"
    PrivateKey = "-----BEGIN PRIVATE KEY-----\nXXXXXX\n-----END PRIVATE KEY-----\n"
    BucketName = "runners-cache"

GCPからダウンロードしたJSONファイル内の認証情報

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    CredentialsFile = "/etc/gitlab-runner/service-account.json"
    BucketName = "runners-cache"

GCPのメタデータサーバーからのアプリケーションデフォルト認証情報（ADC）

GitLab RunnerとGoogle Cloud ADCを使用する場合、通常はデフォルトのサービスアカウントを使用します。その場合、インスタンスの認証情報を提供する必要はありません。

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    BucketName = "runners-cache"

ADCを使用する場合は、使用するサービスアカウントにiam.serviceAccounts.signBlob権限があることを確認してください。通常、これはサービスアカウントトークン作成者のロールをサービスアカウントに付与することで行われます。

GKEのワークロードアイデンティティフェデレーション

GKEのワークロードアイデンティティフェデレーションは、アプリケーションデフォルト認証情報（ADC）でサポートされています。ワークロードアイデンティティが機能しないイシューが発生した場合:

• ERROR: generating signed URLメッセージについては、Runnerポッドログ（ビルドログではなく）を確認してください。このエラーは、次のようなパーミッションのイシューを示している可能性があります:

  IAM returned 403 Forbidden: Permission 'iam.serviceAccounts.getAccessToken' denied on resource (or it may not exist).

• Runnerポッド内から次のcurlコマンドを試してください:

  curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/email

  このコマンドは、正しいKubernetesサービスアカウントを返すはずです。次に、アクセストークンを取得してみてください:

  curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token?scopes=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform

  コマンドが成功すると、結果はアクセストークンを含むJSONペイロードを返します。失敗した場合は、サービスアカウントの権限を確認してください。

[runners.cache.azure]セクション

次のパラメータは、Azure Blob Storageのネイティブサポートを定義します。詳細については、Azure Blob Storageのドキュメントを参照してください。S3やGCSではオブジェクトの集合にbucketという用語が使用されていますが、Azureではblobの集合にcontainerが使用されています。

例:

[runners.cache]
  Type = "azure"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.azure]
    AccountName = "<AZURE STORAGE ACCOUNT NAME>"
    AccountKey = "<AZURE STORAGE ACCOUNT KEY>"
    ContainerName = "runners-cache"
    StorageDomain = "blob.core.windows.net"

AzureワークロードIDとマネージドID

AzureワークロードまたはマネージドIDを使用するには、設定からAccountKeyを省略します。AccountKeyが空白の場合、Runnerは次の処理を試みます。

1. DefaultAzureCredentialを使用して一時的な認証情報を取得します。
2. ユーザー委任キーを取得します。
3. そのキーを使用して、ストレージアカウントのblobにアクセスするためのSASトークンを生成します。

インスタンスにStorage Blob Data Contributorロールが割り当てられていることを確認します。上記のアクションを実行するためのアクセス権がインスタンスにない場合、GitLab RunnerはAuthorizationPermissionMismatchエラーを報告します。

AzureワークロードIDを使用するには、IDに関連付けられているservice_accountを追加し、ポッドラベルazure.workload.identity/useをrunner.kubernetesセクションに追加します。たとえば、service_accountがgitlab-runnerの場合は次のようになります。

  [runners.kubernetes]
    service_account = "gitlab-runner"
    [runners.kubernetes.pod_labels]
      "azure.workload.identity/use" = "true"

service_accountに、azure.workload.identity/client-idアノテーションが関連付けられていることを確認します。

serviceAccount:
  annotations:
    azure.workload.identity/client-id: <YOUR CLIENT ID HERE>

GitLab 17.7以降では、ワークロードIDのセットアップにはこの設定で十分です。

ただし、GitLab Runner 17.5および17.6では、Runnerマネージャーにも以下の設定が必要です。

• azure.workload.identity/useポッドラベル
• ワークロードIDで使用するサービスアカウント

たとえば、GitLab Runner Helmチャートを使用する場合は次のようになります。

serviceAccount:
  name: "gitlab-runner"
podLabels:
  azure.workload.identity/use: "true"

認証情報は異なるソースから取得されるため、このラベルが必要です。キャッシュのダウンロードの場合、認証情報はRunnerマネージャーから取得されます。キャッシュのアップロードの場合、認証情報はヘルパーイメージを実行するポッドから取得されます。

詳細については、イシュー38330を参照してください。

[runners.kubernetes]セクション

次の表に、Kubernetes executorで使用できる設定パラメータを示します。その他のパラメータについては、Kubernetes executorのドキュメントを参照してください。

例:

[runners.kubernetes]
  host = "https://45.67.34.123:4892"
  cert_file = "/etc/ssl/kubernetes/api.crt"
  key_file = "/etc/ssl/kubernetes/api.key"
  ca_file = "/etc/ssl/kubernetes/ca.crt"
  image = "golang:1.8"
  privileged = true
  allow_privilege_escalation = true
  image_pull_secrets = ["docker-registry-credentials", "optional-additional-credentials"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9.4", "postgres:latest"]
  logs_base_dir = "/tmp"
  scripts_base_dir = "/tmp"
  [runners.kubernetes.node_selector]
    gitlab = "true"

ヘルパーイメージ

docker、docker+machine、またはkubernetes executorを使用すると、GitLab RunnerはGit、アーティファクト、およびキャッシュ操作の処理に特定のコンテナを使用します。このコンテナは、helper imageという名前のイメージから作成されます。

ヘルパーイメージは、amd64、ARM、arm64、s390x、ppc64le、およびriscv64アーキテクチャで使用できます。これには、GitLab Runnerバイナリの特別なコンパイルであるgitlab-runner-helperバイナリが含まれています。これには、利用可能なコマンドのサブセットと、Git、Git LFS、およびSSL証明書ストアのみが含まれています。

ヘルパーイメージには、alpine、alpine3.21、alpine-latest、ubi-fips、ubuntuのようないくつかの種類があります。alpineイメージはフットプリントが小さいため、デフォルトです。helper_image_flavor = "ubuntu"を使用すると、ヘルパーイメージのubuntuフレーバーが選択されます。

GitLab Runner 16.1から17.1では、alpineフレーバーはalpine3.18のエイリアスです。GitLab Runner 17.2から17.6では、alpine3.19のエイリアスです。GitLab Runner 17.7以降では、alpine3.21のエイリアスとなっています。GitLab Runner 18.4以降では、alpine-latestのエイリアスです。

alpine-latestフレーバーは、alpine:latestをベースイメージとして使用し、新しいアップストリームのバージョンがリリースされると、自動的にバージョンが上がります。

GitLab RunnerがDEBパッケージまたはRPMパッケージからインストールされると、サポートされているアーキテクチャ用のイメージがホストにインストールされます。Docker Engineが指定されたイメージバージョンを見つけられない場合、Runnerはジョブを実行する前に自動的にダウンロードします。docker executorとdocker+machine executorの両方がこのように動作します。

alpineフレーバーの場合、デフォルトのalpineフレーバーイメージのみがパッケージに含まれています。その他すべてのフレーバーは、レジストリからダウンロードされます。

GitLab Runnerの手動インストールとkubernetes executorは異なる動作をします。

• 手動インストールの場合は、gitlab-runner-helperバイナリは含まれていません。
• kubernetes executorの場合、Kubernetes APIはgitlab-runner-helperイメージをローカルアーカイブから読み込むことを許可しません。

いずれの場合も、GitLab Runnerはヘルパーイメージをダウンロードします。GitLab Runnerのリビジョンとアーキテクチャによって、ダウンロードするタグが決まります。

Arm上のKubernetes用ヘルパーイメージ設定

既定では、アーキテクチャに適したヘルパーイメージが選択されます。arm64 Kubernetesクラスターでarm64ヘルパーイメージを使用するためにカスタムhelper_imageパスを設定する必要がある場合は、設定ファイルで次の値を設定します:

[runners.kubernetes]
  helper_image = "my.registry.local/gitlab/gitlab-runner-helper:arm64-v${CI_RUNNER_VERSION}"

古いバージョンのAlpine Linuxを使用するRunnerイメージ

イメージは、複数のAlpine Linuxバージョンでビルドされています。新しいバージョンのAlpineを使用できますが、同時に古いバージョンも使用できます。

ヘルパーイメージの場合は、helper_image_flavorを変更するか、ヘルパーイメージセクションを参照してください。

GitLab Runnerイメージの場合は、alpine、alpine3.19、alpine3.21、またはalpine-latestがバージョンの前にイメージのプレフィックスとして使用されるように、同じロジックに従ってください:

docker pull gitlab/gitlab-runner:alpine3.19-v16.1.0

Alpine pwshイメージ

GitLab Runner 16.1以降、すべてのalpineヘルパーイメージにはpwshバリアントがあります。唯一の例外はalpine-latestです。これは、GitLab Runnerヘルパーイメージのベースとなるpowershell Dockerイメージがalpine:latestをサポートしていないためです。

例:

docker pull registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:alpine3.21-x86_64-v17.7.0-pwsh

ヘルパーイメージレジストリ

GitLab 15.0以前では、Docker Hubのイメージを使用するようにヘルパーイメージを設定します。

GitLab 15.1以降では、ヘルパーイメージは、GitLab.com上のGitLab Containerレジストリからregistry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}でプルされます。GitLab Self-Managedインスタンスも、既定でGitLab.com上のGitLab Containerレジストリからヘルパーイメージをプルします。GitLab.com上のGitLab Containerレジストリのステータスを確認するには、GitLabシステムのステータスを参照してください。

ヘルパーイメージを上書きする

場合によっては、次の理由でヘルパーイメージを上書きする必要があります。

1. ジョブ実行の高速化: インターネット接続の速度が遅い環境では、同じイメージを複数回ダウンロードすると、ジョブの実行に時間がかかる可能性があります。registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZの正確なコピーが保存されているローカルレジストリからヘルパーイメージをダウンロードすることで、処理を高速化できます。

2. セキュリティに関する懸念: 事前にチェックされていない外部依存関係をダウンロードしたくない場合があります。レビューが完了し、ローカルリポジトリに保存されている依存関係のみを使用するというビジネスルールが存在する可能性があります。

3. インターネットにアクセスできないビルド環境: オフライン環境にKubernetesクラスターをインストールしている場合は、ローカルイメージレジストリまたはパッケージリポジトリを使用して、CI/CDジョブで使用されるイメージをプルできます。

4. 追加のソフトウェア: git+httpの代わりにgit+sshを使用してアクセス可能なサブモジュールをサポートするために、opensshのような追加のソフトウェアをヘルパーイメージにインストールしたい場合があります。

このような場合は、docker、docker+machine、およびkubernetes executorで利用可能なhelper_image設定フィールドを使用して、カスタムイメージを設定できます。

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag"

ヘルパーイメージのバージョンは、GitLab Runnerのバージョンと緊密に結合されていると考えてください。これらのイメージを提供する主な理由の1つは、GitLab Runnerがgitlab-runner-helperバイナリを使用していることです。このバイナリは、GitLab Runnerソースの一部からコンパイルされます。このバイナリは、両方のバイナリで同じであることが期待される内部APIを使用しています。

デフォルトでは、GitLab Runnerはregistry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZイメージを参照します。ここで、XYZはGitLab RunnerのアーキテクチャとGitリビジョンに基づいています。バージョン変数のいずれかを使用することによって、イメージバージョンを定義することができます。

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

この設定により、GitLab Runnerはexecutorに対し、コンパイルデータに基づくバージョンx86_64-v${CI_RUNNER_VERSION}のイメージを使用するように指示します。GitLab Runnerが新しいバージョンに更新された後で、GitLab Runnerは適切なイメージをダウンロードしようとします。GitLab Runnerをアップグレードする前に、イメージをレジストリにアップロードする必要があります。そうしないと、ジョブが「No such image」（指定されたイメージが見つかりません）エラーで失敗し始めます。

ヘルパーイメージは、$CI_RUNNER_REVISIONに加えて$CI_RUNNER_VERSIONによってタグ付けされます。どちらのタグも有効であり、同じイメージを指しています。

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

PowerShell Coreを使用する場合

PowerShell Coreを含むLinux用のヘルパーイメージの追加バージョンは、registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ-pwshタグを使用して公開されます。

[runners.custom_build_dir]セクション

このセクションでは、カスタムビルドディレクトリパラメータを定義します。

この機能は、明示的に設定されていない場合でも、kubernetes、docker、docker+machine、docker autoscaler、およびinstance executorで、デフォルトで有効になっています。他のすべてのexecutorでは、デフォルトで無効になっています。

この機能を使用するには、runners.builds_dirで定義されたパスにGIT_CLONE_PATHが含まれている必要があります。builds_dirを使用するには、$CI_BUILDS_DIR変数を使用します。

デフォルトでは、この機能はdocker executorとkubernetes executorでのみ有効になっています。これは、これらのexecutorがリソースを分離するのに適した方法を提供するためです。この機能はどのexecutorでも明示的に有効にできますが、builds_dirを共有し、concurrent > 1が設定されたexecutorで使用する場合は注意が必要です。

例:

[runners.custom_build_dir]
  enabled = true

デフォルトのビルドディレクトリ

GitLab Runnerは、_ビルドディレクトリ_と呼ばれるベースパスの下に存在するパスにリポジトリをクローンします。このベースディレクトリのデフォルトの場所は、executorによって異なります。詳細は以下の説明を参照してください。

• Kubernetes、Docker、Docker Machine executorの場合は、コンテナ内の/buildsです。
• Instanceの場合は、ターゲットマシンへのSSH接続またはWinRM接続を処理するように設定されているユーザーのホームディレクトリにある~/buildsです。
• Docker Autoscalerの場合は、コンテナ内の/buildsです。
• Shell executorの場合は、$PWD/buildsです。
• SSH、VirtualBox、Parallels executorの場合は、ターゲットマシンへのSSH接続を処理するように設定されているユーザーのホームディレクトリにある~/buildsです。
• Custom executorの場合はデフォルトが提供されていないため、明示的に設定する必要があります。設定されていない場合、ジョブが失敗します。

使用される_ビルドディレクトリ_は、ユーザーがbuilds_dir設定で明示的に定義できます。

GitLab Runnerは、実行するすべてのジョブに_ビルドディレクトリ_を使用しますが、特定のパターン{builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_PROJECT_ID/$NAMESPACE/$PROJECT_NAMEを使用してそれらをネストします。例: /builds/2mn-ncv-/0/user/playground。

GitLab Runnerは、ユーザーが_ビルドディレクトリ_に保存することを妨げません。たとえば、CI実行中に使用できるツールを/builds/tools内に保存できます。この操作は極力控えてください。_ビルドディレクトリ_には何も保存しないでください。GitLab Runnerはこの動作を完全に制御する必要があり、そのような場合には安定性が保証されません。CIに必要な依存関係がある場合は、他の場所にインストールする必要があります。

Git設定をクリーンアップする

すべてのビルドの開始時と終了時に、GitLab Runnerはリポジトリとそのサブモジュールから次のファイルを削除します。

• Gitロックファイル（{index,shallow,HEAD,config}.lock）
• post-checkoutフック（hooks/post-checkout）

clean_git_configを有効にすると、リポジトリ、そのサブモジュール、およびGitテンプレートディレクトリから、次の追加ファイルまたはディレクトリが削除されます。

• .git/configファイル
• .git/hooksディレクトリ

このクリーンアップにより、カスタムGit設定、一時的なGit設定、または潜在的に悪意のあるGit設定がジョブ間でキャッシュされることを防ぎます。

GitLab Runner 17.10より前では、クリーンアップの動作が異なっていました。

• Gitロックファイルとpost-checkoutフックのクリーンアップは、ジョブの開始時にのみ行われ、終了時には行われませんでした。
• 他のGit設定（現在はclean_git_configで制御されるようになった設定）は、FF_ENABLE_JOB_CLEANUPが設定されていない場合には削除されませんでした。このフラグを設定すると、メインリポジトリの.git/configのみが削除されますが、サブモジュールの設定は削除されませんでした。

clean_git_config設定はデフォルトでtrueです。ただし、次の場合はデフォルトでfalseです。

• Shell executorが使用されている。
• Git戦略がnoneに設定されている。

明示的なclean_git_config設定は、デフォルト設定よりも優先されます。

[runners.referees]セクション

GitLab Runnerレフェリーを使用して、追加のジョブモニタリングデータをGitLabに渡します。レフェリーは、ジョブに関連する追加データの照会と収集を行うRunnerマネージャーのワーカーです。結果は、ジョブアーティファクトとしてGitLabにアップロードされます。

Metrics Runnerレフェリーを使用する

ジョブを実行しているマシンまたはコンテナがPrometheusメトリクスを公開している場合、GitLab Runnerはジョブ期間全体にわたってPrometheusサーバーに照会できます。受信したメトリクスはジョブアーティファクトとしてアップロードされ、後で分析に使用できます。

docker-machine executorのみがレフェリーをサポートしています。

GitLab Runner用のMetrics Runnerレフェリーを設定する

config.tomlファイルの[[runner]]セクションで[runner.referees]と[runner.referees.metrics]を定義し、次のフィールドを追加します。

node_exporterメトリクスの構成を網羅した設定例を次に示します。

[[runners]]
  [runners.referees]
    [runners.referees.metrics]
      prometheus_address = "http://localhost:9090"
      query_interval = 10
      metric_queries = [
        "arp_entries:rate(node_arp_entries{{selector}}[{interval}])",
        "context_switches:rate(node_context_switches_total{{selector}}[{interval}])",
        "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])",
        "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])",
        "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])",
        "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])",
        "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])",
        "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])",
        "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])",
        "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])",
        "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])",
        "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])",
        "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])",
        "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])",
        "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])",
        "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])",
        "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])"
      ]

メトリクスクエリの形式はcanonical_name:query_stringです。クエリ文字列は、実行中に置き換えられる2つの変数をサポートしています。

たとえば、docker-machine executorを使用する共有GitLab Runner環境では、{selector}がnode=shared-runner-123のようになります。