• 手動でランナーキャッシュをクリア
• ランナーの最大ジョブタイムアウトの設定
• 機密情報の保護
  • ランナーが機密情報を漏らさないようにします。
  • フォークされたプロジェクトでの共有ランナーの使用
  • プロジェクトのランナー登録トークンのリセット（非推奨）
  • ランナー認証トークンのリセット
• タグを使用して、Runnerが実行できるジョブを制御します。
  • タグなしジョブを実行するRunnerの設定
  • Runnerはタグ付けされたジョブのみを実行します。
  • Runnerはタグのないジョブを実行することができます。
  • ランナーとジョブが複数のタグを持つ場合
  • 異なるプラットフォームでジョブを実行するためのタグの使用
  • タグでCI/CD変数を使う
• 変数によるランナーの動作設定
  • Git strategy
  • Git submodule strategy
  • Git checkout
  • Git clean flags
  • Git fetch extra flags
  • CI ジョブから特定のサブモジュールを同期または除外します。
  • Git サブモジュールの更新フラグ
  • サブモジュールの URL を HTTPS に書き換えましょう
  • Shallow cloning
  • Git サブモジュールの深さ
  • カスタムビルドディレクトリ
    • 並行処理を行う
    • ネストされたパス
  • Job stages attempts
• GitLab.com 共有ランナーで利用できないシステムコール
• アーティファクトとキャッシュの設定
• アーティファクト認証
  • 認証フォーマット
  • ステージングディレクトリ
  • パフォーマンスを向上させるためのfastzip の設定
• 認証トークンのセキュリティ
  • ランナー認証トークンの自動ローテーション

ランナーの設定

独自のRunnerをインストールした場合は、GitLabで設定とセキュリティを行うことができます。

GitLab RunnerをインストールしたマシンでRunnerを設定する必要がある場合は、GitLab Runnerのドキュメントを参照してください。

手動でランナーキャッシュをクリア

キャッシュのクリアを読む

ランナーの最大ジョブタイムアウトの設定

各ランナーに対して、最大ジョブタイムアウトを指定できます。このタイムアウトは、プロジェクトで定義されたタイムアウトよりも小さい場合、優先されます。

この機能は、長いタイムアウト（たとえば1週間）のジョブを持つプロジェクトによって共有ランナーが圧倒されるのを防ぐために使用できます。

GitLab.comでは、共有ランナーのジョブのタイムアウトを上書きすることはできず、プロジェクトで定義されたタイムアウトを使う必要があります。

ジョブの最大タイムアウトを設定するには

1. プロジェクトで、[Settings] > [CI/CD] > [Runner] に進みます。
2. プロジェクトランナーを選択して、設定を編集します。
3. 最大ジョブタイムアウト］に値を入力します。10分以上でなければなりません。定義されていない場合は、プロジェクトのジョブタイムアウト設定が使用されます。
4. 変更を保存を選択します。

この機能の仕組み

例 1 - Runnerのタイムアウトがプロジェクトのタイムアウトより大きい場合

1. ランナーの_最大ジョブタイムアウトを_24時間に設定します。
2. プロジェクトの_CI/CDタイムアウトを_ 2時間に設定した場合
3. ジョブを開始する場合
4. ジョブの実行時間が長い場合、2時間後にタイムアウトします。

例 2 - Runner タイムアウトが設定されていない場合

1. ランナーから_最大ジョブのタイムアウト_設定を削除します。
2. プロジェクトの_CI/CDタイムアウトを_ 2時間に設定した場合
3. ジョブを開始する場合
4. ジョブの実行時間が長い場合、2時間後にタイムアウトします。

例3 - Runnerのタイムアウトがプロジェクトのタイムアウトより小さい場合

1. Runnerの_最大ジョブタイムアウトを_ 30分に設定します。
2. プロジェクトの_CI/CDタイムアウトを_2時間に設定します。
3. ジョブを開始する場合
4. ジョブの実行時間が長い場合、30分後にタイムアウトします。

機密情報の保護

機密情報の漏洩を避けるために、大規模なGitLabインスタンスでの共有Runnerの使用を制限することができます。これにより、GitLabインスタンスへのアクセスを制御し、安全なRunner Executorを確保することができます。

特定の Executor がジョブを実行すると、ファイルシステム、Runner が実行するコード、Runner 認証トークンが公開される可能性があります。これは、_共有ランナー_上でジョブを実行する誰もが、ランナー上で実行される他のユーザーのコードにアクセスできることを意味します。ランナー認証トークンにアクセスできるユーザーは、それを使用してランナーのクローンを作成し、ベクトル攻撃で偽のジョブを送信することができます。詳細については、「セキュリティに関する考慮事項」を参照してください。

ランナーが機密情報を漏らさないようにします。

ランナーが機密情報を漏らさないようにするには、保護されたブランチ、または保護されたタグを持つジョブにのみジョブを実行するように設定します。

ランナーが機密情報を漏らさないようにするには

1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
2. Settings > CI/CDを選択します。
3. Runnerを展開します。
4. 保護または保護解除するランナーを見つけます。ランナーが有効になっていることを確認します。
5. 編集（{pencil}）を選択します。
6. 保護チェックボックスを選択します。
7. 変更を保存を選択します。

フォークされたプロジェクトでの共有ランナーの使用

プロジェクトがフォークされると、ジョブに関連するジョブ設定がコピーされます。あるプロジェクトに共有ランナーを設定し、ユーザーがそのプロジェクトをフォークした場合、共有ランナーはそのプロジェクトのジョブを処理します。

既知のイシューにより、フォークされたプロジェクトのランナー設定が新しいプロジェクトの名前空間と一致しない場合、次のメッセージが表示されます：An error occurred while forking the project. Please try again..

このイシューを回避するには、フォークされたプロジェクトと新しいネームスペースで共有ランナーの設定が一致していることを確認します。

• フォークしたプロジェクトで共有ランナーが有効になっている場合は、新しいネームスペースでも有効にする必要があります。
• フォークされたプロジェクトで共有Runnerが無効になっている場合、新しい名前空間でも無効にする必要があります。

プロジェクトのランナー登録トークンのリセット（非推奨）

プロジェクトの登録トークンが漏れてしまった場合は、リセットしてください。登録トークンを使用して、プロジェクトに別のランナーを登録することができます。その新しいRunnerを使用して、シークレット変数の値を取得したり、プロジェクトコードのクローンを作成したりすることができます。

登録トークンをリセットするには

1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
2. Settings > CI/CDを選択します。
3. Runnerを展開します。
4. New project runner（新規プロジェクトランナー）の右側にある垂直の省略記号（{ellipsis_v}）を選択します。
5. Reset registration token（登録トークンのリセット）を選択します。
6. トークンのリセット」を選択します。

登録トークンをリセットすると、そのトークンは無効となり、プロジェクトに新しい Runner を登録することはできません。新しい値のプロビジョニングや登録に使用するツールでも、登録トークンを更新する必要があります。

ランナー認証トークンのリセット

ランナー認証トークンが公開されると、攻撃者はそのトークンを使ってランナーのクローンを作成することができます。

ランナー認証トークンをリセットするには

1. ランナーを削除します：
   • 共有ランナーを削除します。
   • グループランナーの削除。
   • プロジェクトランナーを削除します。
2. 新しいランナーを作成し、新しいランナー認証トークンを割り当てます：
   • 共有ランナーを作成します。
   • グループランナーを作成します。
   • プロジェクト・ランナーを作成してください。
3. オプション。以前のランナー認証トークンが失効していることを確認するには、Runners APIを使用します。

タグを使用して、Runnerが実行できるジョブを制御します。

タグを使用して、Runnerが実行可能なジョブのみを実行できるようにすることができます。たとえば、Rails テストスイートを実行するための依存関係を持つ Runner に対してrails タグを指定できます。

GitLab CI/CDタグはGitタグとは異なります。GitLab CI/CDタグはRunnerに関連付けられています。Git タグはコミットに関連付けられています。

タグなしジョブを実行するRunnerの設定

ランナーを登録すると、デフォルトの動作はタグ付きジョブのみを選択します。これを変更するには、プロジェクトのオーナーロールを持つ必要があります。

Runnerにタグなしジョブを選択させるには、次のようにします：

1. プロジェクトの[設定]>[CI/CD]に移動し、[ランナー]セクションを展開します。
2. タグなしジョブを選択したいRunnerを探し、有効になっていることを確認してください。
3. 鉛筆ボタンを選択します。
4. タグなしジョブの実行オプションをチェックします。
5. 変更を有効にするには、[Save changes]を選択します。

以下は異なるバリエーションのシナリオ例です。

Runnerはタグ付けされたジョブのみを実行します。

次の例は、タグ付きジョブのみを実行するようにRunnerを設定した場合の潜在的な影響を示しています。

例 1：

1. Runnerはタグ付きジョブのみを実行するように設定されており、docker タグが付いています。
2. hello タグを持つジョブは実行され、スタックします。

例 2：

1. Runnerはタグ付きジョブのみを実行するように設定されており、docker タグが付いています。
2. docker タグを持つジョブが実行され、実行されます。

例 3：

1. Runnerはタグ付きジョブのみを実行するように設定されており、docker タグが付いています。
2. タグが定義されていないジョブは実行され、スタックします。

Runnerはタグのないジョブを実行することができます。

次の例は、タグ付きおよびタグなしジョブを実行するように設定されたランナーの潜在的な影響を示しています。

例 1：

1. Runnerはタグなしジョブを実行するように設定されており、docker タグがあります。
2. タグが定義されていないジョブが実行されます。
3. docker タグが定義された2つ目のジョブが実行されます。

例 2：

1. ランナーはタグなしジョブを実行するように設定されており、タグは定義されていません。
2. タグが定義されていないジョブが実行されます。
3. docker タグが定義されている 2 番目のジョブはスタックします。

ランナーとジョブが複数のタグを持つ場合

ジョブとランナーをマッチさせる選択ロジックは、ジョブで定義されたtags のリストに基づいています。

次の例は、複数のタグを持つランナーとジョブの影響を示しています。ジョブを実行するためにランナーを選択するには、ジョブのスクリプトブロックに定義されているすべてのタグを持つ必要があります。

例 1：

1. ランナーは、[docker, shell, gpu] のタグで設定されています。
2. ジョブはタグ[docker, shell, gpu] 、実行され実行されます。

例 2：

1. ランナーは、[docker, shell, gpu] のタグで設定されています。
2. ジョブはタグ[docker, shell,] 、実行され実行されます。

例 3：

1. ランナーは、[docker, shell] のタグで設定されています。
2. ジョブは[docker, shell, gpu] 、実行されません。

異なるプラットフォームでジョブを実行するためのタグの使用

タグを使用して、異なるプラットフォームで異なるジョブを実行することができます。たとえば、タグosx を持つ OS X ランナーとタグwindows を持つ Windows ランナーがある場合、それぞれのプラットフォームでジョブを実行できます：

windows job:
  stage: build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage: build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"

タグでCI/CD変数を使う

GitLab 14.1 で導入されました。

CI/CD 変数を tags で使用し、動的な Runner の選択ができるようになりました：

variables:
  KUBERNETES_RUNNER: kubernetes

  job:
    tags:
      - docker
      - $KUBERNETES_RUNNER
    script:
      - echo "Hello runner selector feature"

変数によるランナーの動作設定

CI/CD 変数を使って、ランナーの Git の動作をグローバルに、あるいは個々のジョブに対して設定することができます：

• GIT_STRATEGY
• GIT_SUBMODULE_STRATEGY
• GIT_CHECKOUT
• GIT_CLEAN_FLAGS
• GIT_FETCH_EXTRA_FLAGS
• GIT_SUBMODULE_UPDATE_FLAGS
• GIT_SUBMODULE_FORCE_HTTPS
• GIT_DEPTH (浅いクローニング)
• GIT_SUBMODULE_DEPTH
• GIT_CLONE_PATH (カスタムビルドディレクトリ)
• TRANSFER_METER_FREQUENCY （アーティファクト/キャッシュメーターの更新頻度）
• ARTIFACT_COMPRESSION_LEVEL （アーティファクト・アーカイバー圧縮レベル）
• CACHE_COMPRESSION_LEVEL (キャッシュアーカイバの圧縮レベル）
• CACHE_REQUEST_TIMEOUT (キャッシュリクエストタイムアウト)

変数を使用して、ランナーがジョブ実行の特定のステージを試行する回数を設定することもできます。

Kubernetesエクゼキュータを使用する場合、変数を使用してKubernetesのリクエストと制限に対するCPUとメモリの割り当てをオーバーライドできます。

Git strategy

リポジトリのコンテンツを取得する際に使用するGIT_STRATEGY は、variables セクションでグローバルまたはジョブごとに設定できます：

variables:
  GIT_STRATEGY: clone

設定できる値は3つあります：clone fetch none指定しない場合、ジョブはプロジェクトのパイプライン設定を使用します。

clone は最も遅いオプションです。ジョブごとにリポジトリをゼロからクローンし、ローカルの作業コピーが常にまっさらであることを保証します。既存のワークツリーが見つかった場合は、クローン作成前に削除されます。

fetch はローカルの作業コピーを再利用するので高速です（存在しない場合はclone にフォールバックします）。git clean は最後のジョブによる変更を取り消すために使用され、git fetch は最後のジョブが実行された後に行われたコミットを取得するために使用されます。

しかし、fetch は以前のワークツリーにアクセスする必要があります。shell 、docker のエクゼキューターは、デフォルトでワークツリーを保持し、再利用しようとするため、これはうまく機能します。

Docker Machine Executorを使用する場合、これには制限があります。

none 、Git戦略もローカルの作業コピーを再利用しますが、通常GitLabによって行われるすべてのGitオペレーションをスキップします。GitLab Runnerのpre-cloneスクリプトも、もしあればスキップされます。この戦略は、 .gitlab-ci.yml スクリプトにfetch とcheckout コマンドを追加する必要があることを意味します。

デプロイジョブのように、アーティファクトだけをオペレーションするジョブに使用できます。Git リポジトリのデータは存在するかもしれませんが、古い可能性が高いです。キャッシュやアーティファクトからローカルの作業コピーに取り込まれたファイルだけに頼るべきです。

Git submodule strategy

GIT_SUBMODULE_STRATEGY 変数は、ビルドの前にコードを取得するときに git サブモジュールを含めるかどうか/含める方法を制御するために使われます。variables セクションで、グローバルもしくはジョブごとに設定することができます。

設定可能な値は、none、normal、recursiveの3つです：

• none はプロジェクトコードを取得するときにサブモジュールを含めないことを意味します。これはデフォルトで、v1.10以前の動作と同じです。

• normal はトップレベルのサブモジュールだけが含まれることを意味します。と同じです：

   git submodule sync
   git submodule update --init
  

• recursive は、すべてのサブモジュール (サブモジュールのサブモジュールを含む) が含まれることを意味します。この機能はGit v1.8.1以降が必要です。DockerベースでないExecutorでGitLab Runnerを使用する場合は、Gitのバージョンがその要件を満たしていることを確認してください。と同等です：

   git submodule sync --recursive
   git submodule update --init --recursive
  

この機能を正しく動作させるには、サブモジュールを（.gitmodules ）で設定する必要があります：

• 公開リポジトリの HTTP(S) URL、または
• 同じ GitLab サーバー上の別のリポジトリへの相対パス。Git サブモジュールのドキュメントを参照。

GIT_SUBMODULE_UPDATE_FLAGSを使って追加のフラグを指定し、高度な動作を制御することができます。

Git checkout

GIT_STRATEGY がclone またはfetch に設定されている場合、GIT_CHECKOUT 変数を使用して、git checkout を実行するかどうかを指定できます。指定されていない場合、デフォルトは true です。variables セクションでグローバルまたはジョブごとに設定できます。

false に設定されている場合、Runner：

• fetch を実行する場合 - リポジトリを更新し、作業コピーを現在のリビジョンに残します、
• clone を実行した場合 - リポジトリをクローンし、作業コピーをデフォルトブランチに残します。

GIT_CHECKOUT がtrue に設定されている場合、clone とfetch の両方が同じように動作します。Runner は CI パイプラインに関連するリビジョンの作業コピーをチェックアウトします：

variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: "false"
script:
  - git checkout -B master origin/master
  - git merge $CI_COMMIT_SHA

Git clean flags

GIT_CLEAN_FLAGS 変数は、ソースをチェックアウトした後のgit clean のデフォルトの動作を制御するために使用されます。グローバルまたはジョブごとにvariables セクションで設定できます。

GIT_CLEAN_FLAGS は、git cleanコマンドで可能なすべてのオプションを受け付けます。

git clean は、GIT_CHECKOUT: "false" を指定すると無効になります。

もし GIT_CLEAN_FLAGS が：

• 指定がない場合、git clean フラグのデフォルトは-ffdxとなります。
• 値noneを指定すると、git clean は実行されません。

使用例：

variables:
  GIT_CLEAN_FLAGS: -ffdx -e cache/
script:
  - ls -al cache/

Git fetch extra flags

git fetch の挙動を制御するにはGIT_FETCH_EXTRA_FLAGS 変数を使います。グローバルに設定することも、variables セクションでジョブごとに設定することもできます。

GIT_FETCH_EXTRA_FLAGS はgit fetch コマンドのすべてのオプションを受け入れます。ただし、GIT_FETCH_EXTRA_FLAGS フラグは、変更できないデフォルト・フラグの後に追加されます。

デフォルトのフラグは以下の通りです。

• GIT_DEPTH.
• refspecsのリストです。
• originというリモート。

もし GIT_FETCH_EXTRA_FLAGS が：

• 指定がない場合、git fetch フラグのデフォルトは--prune --quiet となります。
• 値noneを指定すると、git fetch はデフォルトのフラグでのみ実行されます。

例えば、デフォルトのフラグは--prune --quietですので、これを--pruneだけにオーバーライドすることで、git fetch をより冗長にすることができます：

variables:
  GIT_FETCH_EXTRA_FLAGS: --prune
script:
  - ls -al cache/

上記の設定では、git fetch がこのように呼び出されます：

git fetch origin $REFSPECS --depth 50  --prune

$REFSPECS は GitLab が内部で Runner に提供する値です。

CI ジョブから特定のサブモジュールを同期または除外します。

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

GIT_SUBMODULE_PATHS 変数を使って、同期や更新が必要なサブモジュールを制御します。variables セクションでグローバルまたはジョブごとに設定できます。

パスの構文はgit submoduleと同じです：

• 特定のパスを同期・更新するには：

   variables:
      GIT_SUBMODULE_PATHS: submoduleA submoduleB
  

• 特定のパスを除外するには

   variables:
      GIT_SUBMODULE_PATHS: :(exclude)submoduleA :(exclude)submoduleB
  

Git サブモジュールの更新フラグ

GIT_SUBMODULE_STRATEGY がnormal あるいはrecursiveのいずれかに設定されたときのgit submodule update の振る舞いを制御するには、GIT_SUBMODULE_UPDATE_FLAGS 変数を使います。variables セクションでグローバルに設定することも、ジョブごとに設定することもできます。

GIT_SUBMODULE_UPDATE_FLAGS は、git submodule update サブコマンドのすべてのオプションを受け入れます。ただし、GIT_SUBMODULE_UPDATE_FLAGS のフラグは、いくつかのデフォルト・フラグの後に追加されます：

• --init GIT_SUBMODULE_STRATEGY がnormal またはrecursive に設定されている場合は、このフラグが付加されます。
• --recursive GIT_SUBMODULE_STRATEGY がrecursive に設定されている場合。
• GIT_DEPTH.以下のデフォルト値を参照してください。

Git は引数のリストでフラグが最後に現れたものを優先するので、GIT_SUBMODULE_UPDATE_FLAGS で手動でフラグを指定するとデフォルトのフラグが上書きされます。

この変数を使うことで、リポジトリ内のコミット追跡ではなく最新のリモートHEAD を取得したり、複数の並列ジョブでサブモジュールを取得してチェックアウトを高速化したりすることができます：

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_UPDATE_FLAGS: --remote --jobs 4
script:
  - ls -al .git/modules/

上記の設定では、git submodule update がこのように呼び出されます：

git submodule update --init --depth 50 --recursive --remote --jobs 4

サブモジュールの URL を HTTPS に書き換えましょう

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

GIT_SUBMODULE_FORCE_HTTPS 変数を使うと、すべての Git と SSH サブモジュールの URL を HTTPS に強制的に書き換えることができます。これにより、GitやSSHプロトコルで設定されていたとしても、絶対URLを使っている同じGitLabインスタンス上のサブモジュールをクローンできるようになります。

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_FORCE_HTTPS: "true"

有効にすると、GitLab Runnerはジョブを実行するユーザーの権限でサブモジュールをクローンするためにCI/CDジョブトークンを使用し、SSH認証情報を必要としません。

Shallow cloning

GIT_DEPTH. GIT_DEPTHcloneはリポジトリの浅いクローンを作成し、クローンの作成速度を大幅に向上させます。コミット数の多いリポジトリや、古くて大きなバイナリの場合に役立ちます。この値はgit fetch とgit clone に渡されます。

GitLab 12.0 以降では、新しく作成されたプロジェクトは自動的にデフォルト値git depth 50 を持ちます。

深さを1 にしてジョブのキューを作ったりジョブを再試行したりすると、ジョブが失敗することがあります。

Git の取得やクローンの作成はブランチ名などの参照に基づいて行われるので、Runner が特定のコミット SHA をクローンすることはできません。複数のジョブがキューに入っている場合や古いジョブを再試行する場合は、テストするコミットがクローンする Git の履歴内になければなりません。GIT_DEPTH の値を小さくしすぎると古いコミットを実行できなくなり、ジョブログにunresolved reference が表示されるようになります。その場合はGIT_DEPTH を大きな値に変更することを再考しましょう。

git describe に依存しているジョブは、GIT_DEPTH が設定されている場合、Git 履歴の一部しか存在しないため、正しく動作しない可能性があります。

最後の3つのコミットのみをフェッチまたはクローンするには：

variables:
  GIT_DEPTH: "3"

variables セクションで、グローバルまたはジョブごとに設定できます。

Git サブモジュールの深さ

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

GIT_SUBMODULE_STRATEGY がnormal かrecursiveのどちらかに設定されている場合に、GIT_SUBMODULE_DEPTH 変数を使ってサブモジュールのフェッチとクローンの深さを指定します。グローバルに設定することも、variables セクションで特定のジョブに対して設定することもできます。

GIT_SUBMODULE_DEPTH 変数を設定すると、サブモジュールにのみGIT_DEPTH 設定が上書きされます。

最後の3つのコミットのみをフェッチまたはクローンするには：

variables:
  GIT_SUBMODULE_DEPTH: 3

カスタムビルドディレクトリ

デフォルトでは、GitLab Runnerは$CI_BUILDS_DIR ディレクトリのユニークなサブパスにリポジトリをクローンします。しかし、プロジェクトによっては特定のディレクトリにコードを置く必要があるかもしれません（Go プロジェクトなど）。その場合、GIT_CLONE_PATH 変数を指定して、リポジトリをクローンするディレクトリを Runner に指定することができます：

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name

test:
  script:
    - pwd

GIT_CLONE_PATH は常に$CI_BUILDS_DIR内になければなりません。$CI_BUILDS_DIR に設定されるディレクトリは、Executor とrunner.builds_dirの設定に依存します。

これは、ランナーの設定でcustom_build_dir が有効になっている場合にのみ使用できます。

並行処理を行う

1 を超える同時実行数を使用する Executor は失敗する可能性があります。builds_dir がジョブ間で共有されている場合、複数のジョブが同じディレクトリで作業している可能性があります。

Runnerはこのような状況を防ごうとはしません。Runner設定の要件に従うかどうかは、管理者と開発者次第です。

このシナリオを回避するために、$CI_BUILDS_DIR 、内部でユニークなパスを使用することができます。Runnerは、同時実行のユニークなID を提供する2つの追加変数を公開しているからです：

• $CI_CONCURRENT_ID: 指定された executor 内で実行されているすべてのジョブのユニーク ID。
• $CI_CONCURRENT_PROJECT_ID: 指定された executor とプロジェクト内で実行されているすべてのジョブのユニーク ID。

どのようなシナリオでも、どのようなexecutorでもうまく動作する最も安定したコンフィギュレーションは、GIT_CLONE_PATHで$CI_CONCURRENT_ID を使うことです。 例えば、以下のような設定です：

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name

test:
  script:
    - pwd -P

$CI_PROJECT_PATHはリポジトリのパス（ つまり、group/subgroup/project）を提供するので、$CI_CONCURRENT_PROJECT_ID は$CI_PROJECT_PATHと併せて使用する必要があります。例えば、次のようになります：

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH

test:
  script:
    - pwd -P

ネストされたパス

GIT_CLONE_PATH の値は一度だけ展開され、内部での変数のネストはサポートされません。

例えば、.gitlab-ci.yml ファイルに以下の2つの変数を定義します：

variables:
  GOPATH: $CI_BUILDS_DIR/go
  GIT_CLONE_PATH: $GOPATH/src/namespace/project

GIT_CLONE_PATH の値が$CI_BUILDS_DIR/go/src/namespace/projectに一度展開されますが、$CI_BUILDS_DIR が展開されないため、失敗となります。

Job stages attempts

実行中のジョブが以下のステージの実行を試みる回数を設定できます：

デフォルトは1回の試行です。

使用例：

variables:
  GET_SOURCES_ATTEMPTS: 3

variables セクションで、グローバルまたはジョブごとに設定できます。

GitLab.com 共有ランナーで利用できないシステムコール

GitLab.com共有ランナーはCoreOS上で動作します。つまり、C標準ライブラリのgetlogin のようなシステムコールが使えないということです。

アーティファクトとキャッシュの設定

アーティファクトとキャッシュの設定は、アーティファクトとキャッシュの圧縮率を制御します。これらの設定を使用して、ジョブによって生成されるアーカイブのサイズを指定します。

• 低速なネットワークでは、小さいアーカイブの方がアップロードが速くなる場合があります。
• 帯域幅とストレージが気にならない高速ネットワークでは、生成されるアーカイブが大きくなるにもかかわらず、最も速い圧縮率を使用するとアップロードが速くなるかもしれません。

GitLab PagesがHTTP Range リクエストに対応するためには、アーティファクトはARTIFACT_COMPRESSION_LEVEL: fastest の設定を使うべきです。非圧縮の zip アーカイブだけがこの機能をサポートしているからです。

メーターを有効にして、アップロードとダウンロードの転送レートを提供することができます。

CACHE_REQUEST_TIMEOUT 設定で、キャッシュのアップロードとダウンロードの最大時間を設定できます。この設定は、キャッシュのアップロードに時間がかかるとジョブの時間が大幅に長くなる場合に便利です。

variables:
  # output upload and download progress every 2 seconds
  TRANSFER_METER_FREQUENCY: "2s"

  # Use fast compression for artifacts, resulting in larger archives
  ARTIFACT_COMPRESSION_LEVEL: "fast"

  # Use no compression for caches
  CACHE_COMPRESSION_LEVEL: "fastest"

  # Set maximum duration of cache upload and download
  CACHE_REQUEST_TIMEOUT: 5

アーティファクト認証

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

GitLab Runnerは、すべてのビルドアーティファクトに対して認証メタデータを生成して作成することができます。この機能を有効にするには、RUNNER_GENERATE_ARTIFACTS_METADATA 環境変数をtrueに設定する必要があります。この変数はグローバルに設定することも、個々のジョブに設定することもできます。メタデータは、アーティファクトとともに保存されるプレーンテキストファイル（.json ）にレンダリングされます。ファイル名は次のようになります:{ARTIFACT_NAME}-metadata.json ここで、ARTIFACT_NAME はCIファイルでアーティファクトの名前として定義されたものです。ただし、ビルドアーティファクトに名前が与えられていない場合、ファイル名のデフォルトはartifacts-metadata.json になります。

認証フォーマット

認証メタデータは、spec versionv0.1のin-toto認証形式で生成されます。以下のフィールドはデフォルトで入力されています：

GitLab Runnerが生成する可能性のある認証の例を以下に示します：

{
    "_type": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/v15.1.0/PROVENANCE.md",
    "subject": [
        {
            "name": "script.sh",
            "digest": {
                "sha256": "f5ae5ced234922eebe6461d32228ba8ab9c3d0c0f3983a3bef707e6e1a1ab52a"
            }
        }
    ],
    "predicateType": "https://slsa.dev/provenance/v0.2",
    "predicate": {
        "buildType": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/v15.1.0/PROVENANCE.md",
        "builder": {
            "id": "https://gitlab.com/ggeorgiev_gitlab/playground/-/runners/14811533"
        },
        "invocation": {
            "configSource": {
                "uri": "https://gitlab.com/ggeorgiev_gitlab/playground",
                "digest": {
                    "sha256": "f0582e2c9a16b5cc2cde90e8be8f1b50fd67c631"
                },
                "entryPoint": "whoami shell"
            },
            "environment": {
                "name": "local",
                "executor": "shell",
                "architecture": "amd64"
            },
            "parameters": {
                "CI_PIPELINE_ID": "",
                "CI_PIPELINE_URL": "",
                // All other CI variable names are listed here. Values are always represented as empty strings to avoid leaking secrets.
            }
        },
        "metadata": {
            "buildStartedOn": "2022-06-17T00:47:27+03:00",
            "buildFinishedOn": "2022-06-17T00:47:28+03:00",
            "completeness": {
                "parameters": true,
                "environment": true,
                "materials": false
            },
            "reproducible": false
        },
        "materials": []
    }
}

ステージングディレクトリ

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

システムのデフォルトの一時ディレクトリにキャッシュやアーティファクトをアーカイブしたくない場合は、別のディレクトリを指定することができます。

システムのデフォルトの一時パスに制約がある場合は、ディレクトリを変更する必要があるかもしれません。ディレクトリの場所に高速ディスクを使用すると、パフォーマンスも向上します。

ディレクトリを変更するには、CIジョブでARCHIVER_STAGING_DIR を変数として設定するか、ランナーを登録するときにランナー変数を使用します(gitlab register --env ARCHIVER_STAGING_DIR=<dir>)。

指定したディレクトリは、抽出前にアーティファクトをダウンロードする場所として使用されます。fastzip アーカイバを使用する場合、この場所はアーカイブ時のスクラッチスペースとしても使用されます。

パフォーマンスを向上させるためのfastzip の設定

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

fastzip を調整するには、FF_USE_FASTZIP フラグが有効になっていることを確認します。次に、以下の環境変数のいずれかを使います。

zip アーカイブのファイルは順次追加されます。このため、同時圧縮は困難です。fastzip はこの制限を回避するために、 まずディスクに同時圧縮し、その結果を zip アーカイブに順次コピーします。

ディスクへの書き込みと小さなファイルへの読み込みを避けるために、 同時圧縮ごとに小さなバッファが使用されます。この設定はFASTZIP_ARCHIVER_BUFFER_SIZE で制御できます。このバッファのデフォルトのサイズは 2 MiB ですので、同時実行数が 16 の場合は 32 MiB が割り当てられます。バッファサイズを超えるデータはディスクに書き込まれ、ディスクから読み戻されます。したがって、バッファを使用せず、FASTZIP_ARCHIVER_BUFFER_SIZE: 0、スクラッチ領域のみを使用することも有効なオプションです。

FASTZIP_ARCHIVER_CONCURRENCY は、コンカレンシー圧縮されるファイル数を制御します。上述したように、この設定はメモリ使用量を増加させるだけでなく、スクラッチ領域に書き込まれる一時データの量も増加させます。デフォルトは使用可能なCPUの数ですが、メモリの影響を考えると、これが常に最良の設定とは限りません。

FASTZIP_EXTRACTOR_CONCURRENCY 一度に解凍されるファイルの数を制御します。zip アーカイブのファイルはネイティブで同時読み込みが可能なので、 展開器が必要とするメモリ以外に追加のメモリは割り当てられません。デフォルトは使用可能な CPU の数です。

認証トークンのセキュリティ

• GitLab 15.3 でenforce_runner_token_expires_atというフラグで導入されました。デフォルトでは無効です。
• GitLab 15.5で一般的に利用可能。機能フラグenforce_runner_token_expires_at を削除しました。

各 Runner は GitLab インスタンスと接続するためのRunner 認証トークンを持ちます。

トークンの漏洩を防ぐために、トークンを指定した間隔で自動的にローテーションさせることができます。トークンがローテーションされると、ランナーのステータス（online またはoffline）に関係なく、各ランナーごとに更新されます。

手動による操作は必要なく、実行中のジョブにも影響はありません。

手動でRunner認証トークンを更新する必要がある場合は、トークンをリセットするコマンドを実行できます。

ランナー認証トークンの自動ローテーション

ランナー認証トークンのローテーション間隔を指定できます。このローテーションは、ランナーに割り当てられたトークンのセキュリティを確保するのに役立ちます。

前提条件：

• GitLab Runner 15.3 以降を使用していることを確認してください。

Runner 認証トークンを自動的にローテーションするには：

1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
2. 管理エリアを選択します。
3. 左サイドバーで、Settings > CI/CDを選択します。
4. 継続的インテグレーションとデプロイを展開します。
5. ランナーの有効期限を設定します。有効期限なしの場合は空のままにします。
6. Save を選択します。

インターバルが切れる前に、ランナーは自動的に新しいランナー認証トークンを要求します。