• 設定の検証
• グローバルセクション
  • log_format 例 (切り捨て)
    • runner
    • text
    • json
  • check_interval の仕組み
• [session_server] セクション
• [[runners]] セクション
  • clone_url の仕組み
• エクゼキューター
• シェル
  • POSIX 準拠のシェルを使用してください。
• [runners.docker] セクション
  • [[runners.docker.services]] セクション
  • [runners.docker] セクションのボリューム
    • 例1：データボリュームの追加
    • 例2: ホストディレクトリをデータボリュームとしてマウントします。
  • 非公開コンテナレジストリを使う
    • GitLab 統合レジストリのサポート
    • Docker作成者の権限解決の優先順位
• [runners.parallels] セクション
• [runners.virtualbox] セクション
• ベース VM イメージのオーバーライド
• [runners.ssh] セクション
• [runners.machine] セクション
  • [[runners.machine.autoscaling]] 。
  • ピリオドの構文
• [runners.instance] セクション (Alpha)
• [runners.autoscaler] セクション
• [runners.autoscaler.plugin_config] セクション
• [runners.autoscaler.connector_config] セクション
• [[runners.autoscaler.policy]] 。
  • ピリオドの構文
• [runners.custom] セクション
• [runners.cache] セクション
  • [runners.cache.s3] セクション
    • Runner キャッシュ用の S3 バケットで KMS キー暗号化を使用します。
    • Kubernetes ServiceAccountリソースに対するIAMロールの有効化
  • [runners.cache.gcs] セクション
  • [runners.cache.azure] セクション
• [runners.kubernetes] セクション
• ヘルパーイメージ
  • Arm上のKubernetesのヘルパーイメージ設定
  • 古いバージョンのAlpine Linuxを使用するRunnerイメージ
  • アルパインpwshイメージ
  • ヘルパーイメージのレジストリ
  • ヘルパーイメージを上書き
    • PowerShell Core を使う場合
• [runners.custom_build_dir] セクション
  • デフォルトのビルドディレクトリ
• [runners.referees] セクション
  • メトリクスRunnerレフリーを使う
  • GitLab Runner用のメトリクスRunnerレフリーの設定

高度な設定

GitLab Runnerや個々の登録Runnerの動作を変更することができます。

これを行うには、config.toml というTOMLフォーマットを使ったファイルを変更します。

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

GitLab Runnerは3秒ごとに設定の変更をチェックし、必要であればリロードします。GitLab Runner はまた、SIGHUP シグナルに応答して設定をリロードします。

config.toml ファイルは以下にあります：

• /etc/gitlab-runner/ GitLab Runnerがrootとして実行されている場合（これはサービス設定のためのパスでもあります）。
• ~/.gitlab-runner/ GitLab Runnerをroot以外で実行した場合。
• ./ その他のシステムでは

設定の検証

GitLab Runner 15.10 で導入されました。

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

設定検証は_ベストエフォート_であり、現在は情報提供のみを目的としています。ユーザーによるRunner設定の潜在的な問題の特定を支援します。可能性のあるすべての問題を検出できるわけではありませんし、メッセージがないからといって、config.toml ファイルに欠陥がないことを保証するものでもありません。

時間の経過とともに、検証プロセスはより正確で包括的、かつ有用なフィードバックを提供できるように改良される予定です。最新の改善や拡張の恩恵を受けるために、GitLab Runnerを常にアップデートしておく必要があります。

グローバルセクション

これらの設定はグローバルです。すべてのランナーに適用されます。

設定例：

concurrent = 4
log_level = "warning"

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":"2020-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2020-06-05T15:57:35+02:00"}

check_interval の仕組み

config.toml に[[runners]] セクションが複数存在する場合、GitLab へのリクエスト間隔は予想以上に頻繁になります。GitLab Runnerには、設定されたGitLabインスタンスへのリクエストを常にスケジュールするループがあります。

GitLab Runnerは、各Runnerの後続のリクエストが指定された間隔で行われるようにします。そのために、check_interval の値を[[runners]] セクションの数で割ります。ループはすべてのセクションを繰り返し、それぞれのリクエストをスケジュールし、計算された時間スリープします。ランナーが別の GitLab インスタンスに結びついていると、面白いことが起こります。次の例を見てみましょう。

check_interval = 10 を設定し、2 つの Runner (runner-1 とrunner-2) がある場合、10 秒ごとにリクエストが行われます。この場合のループの例を示します：

1. check_interval の値 (10s) を取得します。
2. ランナーのリストを取得 (runner-1,runner-2).
3. 睡眠間隔の計算 (10s / 2 = 5s).
4. 無限ループを開始します：
   1. runner-1 のジョブをリクエスト。
   2. 5s 。
   3. runner-2 のジョブをリクエスト。
   4. 5s 。
   5. 繰り返します。

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

に対する最初のrunner-1 リクエストと2回目のリクエストの runner-1間には、2つのスリープ期間があります。それぞれ5秒ずつかかるので、runner-1 に対するその後のリクエストの間はおよそ10秒です。runner-2 についても同様です。

より多くのRunnerを定義する場合、スリープ間隔はより小さくなります。しかし、ランナーへのリクエストは、他のランナーへのすべてのリクエストとそのスリープ期間が呼び出された後に繰り返されます。

[session_server] セクション

[session_server] セクションは、ユーザーが対話型ウェブターミナルなどでジョブと対話できるようにします。

[session_server] セクションは、ランナーごとではなく、ルート・レベルで指定する必要があります。[[runners]] セクションの内部で定義する必要があります。

[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証明書を作成します。
• ウェブブラウザがadvertise_address に接続できることを確認してください。ライブセッションはウェブブラウザによって開始されます。
• アプリケーション設定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つのランナーを定義します。

使用例：

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

clone_url の仕組み

GitLab インスタンスが Runner が使えない URL で利用可能な場合は、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を構築します。

エクゼキューター

以下のエクゼキューターがあります。

シェル

利用可能なシェルは異なるプラットフォーム上で動作します。

shell オプションがbash またはsh に設定されている場合、Bash のANSI-C クォートがジョブスクリプトのシェルエスケープに使用されます。

POSIX 準拠のシェルを使用してください。

GitLab Runner 14.9 以降では、FF_POSIXLY_CORRECT_ESCAPES という機能フラグを有効にしてPOSIX 準拠のシェル（dash のようなもの）を使うようにします。有効にすると、POSIX準拠のシェルのエスケープメカニズムである“二重引用符 “が使用されます。

[runners.docker] セクション

以下の設定はDockerコンテナのパラメータを定義します。

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

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

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

使用例：

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  memory = "128m"
  memory_swap = "256m"
  memory_reservation = "64m"
  oom_kill_disable = false
  cpuset_cpus = "0,1"
  cpus = "2"
  dns = ["8.8.8.8"]
  dns_search = [""]
  privileged = false
  userns_mode = "host"
  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つまたは複数のコンテナ内の特別に指定されたディレクトリです。データボリュームは、コンテナのライフサイクルとは無関係にデータを永続化するように設計されています。

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  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:2.7"
  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 以降では、定義されたサービスの ホストディレクトリもマウントします。

非公開コンテナレジストリを使う

ジョブのイメージソースとして非公開レジストリを使用するには、DOCKER_AUTH_CONFIG という名前のCI/CD 変数に作成者設定を設定します。この変数は、プロジェクトの CI/CD 設定で型File として設定するか、config.toml ファイルで設定します。

if-not-present プルポリシーで非公開レジストリを使用すると、セキュリティ上の問題が発生する可能性があります。プルポリシーがどのように機能するかを完全に理解するには、プルポリシーのドキュメントを読んでください。

詳細な例については、Using Docker imagesのドキュメントを参照してください。

Runnerが実行するステップをまとめると、次のようになります：

1. 画像名からレジストリ名を検索します。
2. この値が空でなければ、 Executor はこのレジストリの認証設定を検索します。
3. 指定したレジストリに対応する認証が見つかった場合は、 それを使用します。

Runnerが非公開レジストリに対して認証するように設定されたので、そのレジストリを使用するために.gitlab-ci.yml ファイル](https://docs.gitlab.com/ee/ci/yaml/index.html#image) を設定する方法を[。

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 イメージのオーバーライド

GitLab Runner 14.2 で導入されました。

Parallels と 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] セクション

GitLab Runner v1.1.0で追加されました。

以下のパラメータはDocker Machineベースのオートスケール機能を定義します。詳細については、別のRunner autoscale ドキュメントを参照してください。

[[runners.machine.autoscaling]] 。

使用例：

[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 設定には、cronスタイルのフォーマットで表現された期間の文字列パターンの配列が含まれます。行には以下のコンテナが含まれます：

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

標準的なcron設定ファイルのように、フィールドは単一の値、範囲、リスト、アスタリスクを含むことができます。構文の詳細な説明をご覧下さい。

[runners.instance] セクション (Alpha)

以下のパラメータはインスタンスエグゼキュータの設定を定義します。

[runners.autoscaler] セクション

GitLab Runner v15.10.0で追加されました。

以下のパラメータは、新しい実験的なオートスケーラ機能を設定するもので、インスタンスと Docker AutoscalerExecutorでのみ使用できます。

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

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

fleetingプラグインには通常、サポートされる設定に関する付属のドキュメントがあります。

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

fleetingプラグインは通常、サポートされている接続オプションに関する付属のドキュメントを持っています。

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

[[runners.autoscaler.policy]] 。

注- この文脈でのidle_count はジョブの数を意味し、従来のオートスケーリング手法のようにオートスケールされたマシンの数を意味するものではありません。

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

ピリオドの構文

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.custom] セクション

以下のパラメータはカスタムエグゼキュータの設定を定義します。

[runners.cache] セクション

GitLab Runner 1.1.0 で導入されました。

以下のパラメータがディストリビューションキャッシュ機能を定義します。詳細はRunner autoscale ドキュメントをご覧ください。

キャッシュメカニズムは、キャッシュのアップロードとダウンロードに署名済みのURLを使用します。URLはGitLab Runner自身のインスタンスによって署名されます。ジョブのスクリプト（キャッシュのアップロード/ダウンロードスクリプトを含む）がローカルまたは外部のマシンで実行されるかは関係ありません。例えば、shell またはdocker の Executor は GitLab Runner プロセスが実行されている同じマシン上でスクリプトを実行します。同時に、virtualbox またはdocker+machine はスクリプトを実行するために別の VM に接続します。このプロセスはセキュリティ上の理由によるもので、キャッシュアダプターの認証情報が漏れる可能性を最小限にするためです。

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

この表は、config.toml 、CLI オプション、register の ENV 変数の一覧です。

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

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

GitLab Runner 11.2以前では、これらの設定はグローバル[runners.cache] 。

使用例：

[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"

例:ServerAddress 、AccessKey 、SecretKey のいずれかが指定されず、AuthenticationType が提供されない場合、S3 クライアントはgitlab-runner インスタンスで利用可能な IAM インスタンスプロファイルを使用します。オートスケール設定では、これはジョブが実行されるオンデマンドマシンではありません。ServerAddress、AccessKey 、SecretKey がすべて指定されていて、AuthenticationType が指定されていない場合、access-key が認証タイプとして使用されます。

Helmチャートを使ってGitLab Runnerをインストールし、values.yaml ファイルでrbac.create をtrueに設定すると、ServiceAccountが作成されます。この ServiceAccount のアノテーションは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”

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

• “kms:Encrypt”
• “kms:復号化”
• “kms:ReEncrypt*”
• “kms:GenerateDataKey*”
• “kms:DescribeKey”

ServerSideEncryption タイプのヘッダはSSE-C 現在サポートされていません。 SSE-Cこれは、鍵が安全に保たれないジョブに鍵の材料を渡すことを意味します。これは復号鍵を漏洩させる可能性があります。この問題に関する議論はこのマージリクエストにあります。

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

GenerateDataKey API は、クライアント側暗号化 (https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) 用のデータキーを作成するために KMS 共通キーを使用します。KMSキーの設定は以下のようにする必要があります：

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

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

Kubernetes ServiceAccountリソースに対するIAMロールの有効化

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

1. Create Role］ウィンドウの［Select type of trusted entity］で［Windows Identity］を選択します。

2. ロールの「Trusted Relationships」タブで、「Web Identity」を選択します：

   • Trusted entitiesセクションは、arn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID> の形式である必要があります。OIDC IDは、EKSクラスターの設定タブで確認できます。

   • 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>

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

GitLab Runner 11.3.0 で導入されました。

以下のパラメータはGoogle Cloud Storageのネイティブサポートを定義します。これらの値の出典については、Google Cloud Storage(GCS) Authentication のドキュメントをご覧ください。

例：

** 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"

Application Default Credentials(ADC) GCP のメタデータサーバから：

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 の権限を持っていることを確認してください。通常は、サービスアカウントに Service Account Token Creator ロールを付与します。

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

GitLab Runner 13.4.0 で導入されました。

以下のパラメータは、Azure Blob Storageのネイティブサポートを定義します。詳細については、Azure Blob Storageのドキュメントを参照してください。S3 と GCS がbucket という単語をオブジェクトのコレクションに使用するのに対し、Azure はcontainer という単語を Blob のコレクションに使用します。

使用例：

[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"

[runners.kubernetes] セクション

GitLab Runner v1.6.0 で導入されました。

以下のパラメータがKubernetesの動作を定義します。その他のパラメータについては、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"]
  [runners.kubernetes.node_selector]
    gitlab = "true"

ヘルパーイメージ

docker,docker+machine,kubernetes の Executor を使う場合、GitLab Runner は Git、アーティファクト、キャッシュオペレーションを処理するために特定のコンテナを使います。このコンテナはhelper image という名前のイメージから作成されます。

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

ヘルパーイメージにはいくつかの種類があります：alpine alpine3.15,alpine3.16,alpine3.17,alpine3.18,alpine-latest,ubi-fips andubuntu.alpine イメージはフットプリントが小さいため、現在のところデフォルトですが、環境によってはDNSのイシューが発生することがあります。helper_image_flavor = "ubuntu" を使用すると、ubuntu のヘルパーイメージが選択されます。

GitLab Runner 16.1 以降では、alpine はalpine3.18 のエイリアスです。

alpine-latest フレーバーはベースイメージとしてalpine:latest を使っています。

GitLab RunnerがDEB/RPMパッケージからインストールされると、サポートされているアーキテクチャのイメージがホストにインストールされます。Runnerがジョブの実行を準備するとき、指定されたバージョン（RunnerのGitリビジョンに基づく）のイメージがDocker Engineに見つからない場合は、自動的にロードされます。docker とdocker+machine の両 Executor はこの方法で動作します。

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

GitLab Runnerのkubernetes Executorと手動インストールでは動作が異なります。

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

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

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

Kubernetesクラarm64 スターでヘルパーイメージを arm64使用するには、設定ファイルに以下の値を設定します。

[runners.kubernetes]
        helper_image = "gitlab/gitlab-runner-helper:arm64-latest"

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

GitLab Runner 14.5 で導入されました。

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

ヘルパーイメージについては、helper_image_flavor を変更するか、ヘルパーイメージのセクションを読んでください。

GitLab Runnerイメージも同じように、alpine、alpine3.15、alpine3.16、alpine3.17、alpine3.18、またはalpine-latestをイメージのプレフィックスとして、バージョンの前に付けてください：

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

アルパインpwshイメージ

GitLab Runner 16.1以降では、すべてのalpine ヘルパーイメージにpwsh 。唯一の例外はalpine-latest で、GitLab Runner のヘルパーイメージがベースにしているpwsh Docker イメージはalpine:latestをサポートしていません。

使用例：

docker pull gitlab/gitlab-runner-helper:alpine3.18-x86_64-v16.1.0-pwsh

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

GitLab 15.0以降では、ヘルパーイメージはGitLabコンテナレジストリから取得されます。

GitLab 15.0以前では、Docker Hubからイメージを使うようにヘルパーイメージを設定します。GitLabレジストリからベースとなるgitlab-runner-helper イメージを取得するには、helper-image 値を使用します:registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}.

セルフマネージドインスタンスも、GitLab.comのGitLabコンテナレジストリからヘルパーイメージを取得します。GitLab Container Registryのステータスを確認するには、GitLab System Statusをご覧ください。

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

場合によっては、ヘルパー画像を上書きする必要があるかもしれません。これを行う理由はたくさんあります：

1. ジョブの実行速度を上げるため：インターネット接続が遅い環境では、同じイメージを何度もダウンロードすると、ジョブの実行時間が長くなる可能性があります。gitlab/gitlab-runner-helper:XYZ の正確なコピーが保存されている内部レジストリからヘルパーイメージをダウンロードすることで、スピードアップできます。

2. セキュリティ上の問題：事前にチェックされていない外部の依存関係をダウンロードしたくない場合があります。レビューされ、ローカルリポジトリに保存された依存関係のみを使用するというビジネスルールがあるかもしれません。

3. インターネットアクセスのないビルド環境：場合によっては、ジョブは専用の閉じたネットワークがある環境で実行されます。これはkubernetes Executorには当てはまらず、Kubernetesクラスタが利用可能な外部レジストリからイメージをダウンロードする必要があります。

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

このような場合、docker 、docker+machine 、kubernetes のエクゼキューターで利用できるhelper_image 設定フィールドを使って、カスタムイメージを設定できます：

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

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

デフォルトでは、GitLab Runner はgitlab/gitlab-runner-helper:XYZ イメージを参照します。XYZ は GitLab Runner のアーキテクチャと Git リビジョンに基づいています。GitLab Runner 11.3 以降では、バージョン変数の一つを使ってイメージのバージョンを定義することができます：

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

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

GitLab Runner 13.2以降では、ヘルパーイメージは$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 を使う場合

GitLab 13.9 で導入されました。

PowerShell Core を含む Linux 用ヘルパーイメージの追加バージョンがgitlab/gitlab-runner-helper:XYZ-pwsh タグで公開されています。

[runners.custom_build_dir] セクション

GitLab Runner 11.10 で導入されました。

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

この機能は、明示的に設定されていない場合、kubernetes 、docker 、docker+machine のエクゼキュータではデフォルトで有効になっています。その他のエクゼキュータでは、デフォルトで無効になっています。

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

デフォルトでは、この機能はdocker とkubernetes のエクゼキュータに対してのみ有効になっています。この機能はどのエクゼキュータでも明示的に有効にすることができますが、builds_dir を共有し、concurrent > 1 を持つエクゼキュータで使用する場合には注意が必要です。

使用例：

[runners.custom_build_dir]
  enabled = true

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

GitLab Runnerは、_Builds Directoryとして_よく知られているベースパスの下に存在するパスにリポジトリをクローンします。このベースディレクトリのデフォルトの場所は Executor によって異なります。例えば

• Kubernetes、Docker、Docker MachineExecutorの場合、コンテナ内部/builds 。
• Shellエクゼキュータ、それは$PWD/builds 。
• SSH、VirtualBox、ParallelsのExecutorは、~/builds 、ターゲットマシンへのSSH接続を処理するように設定されたユーザーのホームディレクトリにあります。
• カスタムエグゼキュータの場合、デフォルトは提供されず、明示的に設定する必要があります。

使用する_Builds Directory_はbuilds_dir の設定でユーザーが明示的に定義できます。

GitLab Runnerは実行するすべてのジョブに_Buildsディレクトリを_使いますが、特定のパターン{builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_ID/$NAMESPACE/$PROJECT_NAME を使ってネストします。例：/builds/2mn-ncv-/0/user/playground.

GitLab Runnerは_Builds_ Directoryの中に何かを保存することを止めません。例えば、/builds/tools の内部に CI 実行時に使用するツールを格納することができます。Builds_Directoryの_中には何も保存してはいけません。GitLab Runnerはそれを完全にコントロールする必要があり、そのようなケースでは安定性を提供しません。CIに必要な依存関係がある場合は、別の場所にインストールすることをお勧めします。

[runners.referees] セクション

• GitLab Runner 12.7 で導入されました。
• GitLab v12.6以降が必要です。

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

メトリクスRunnerレフリーを使う

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

docker-machine Executor だけがレフェリーをサポートしています。

GitLab Runner用のメトリクス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 環境では、node=shared-runner-123 のような{selector} を持つことになります。