CI/CD YAML構文リファレンス

このドキュメントでは、GitLabの.gitlab-ci.ymlファイルの設定オプションについて説明します。このファイルでは、パイプラインを構成するCI/CDジョブを定義します。

• 基本的なCI/CDの概念をすでに理解している方は、シンプルまたは複雑なパイプラインの構築手順を示すチュートリアルに沿って、独自の.gitlab-ci.ymlファイルを作成してみてください。
• さまざまな例については、GitLab CI/CDの例を参照してください。
• エンタープライズで使用される大規模な.gitlab-ci.ymlファイルを確認するには、gitlabの.gitlab-ci.ymlファイルを参照してください。

.gitlab-ci.ymlファイルを編集しているときは、CI Lintツールでこのファイルを検証できます。

GitLab CI/CDの設定はYAML形式を使用するため、キーワードの順序は特に指定がない限り重要ではありません。

より動的なパイプライン設定オプションについては、CI/CD式を使用してください。

キーワード

GitLab CI/CDパイプラインの設定には、次の要素が含まれます。

• パイプラインの動作を設定するグローバルキーワード:

  キーワード	説明
  default	ジョブキーワードに対するカスタムデフォルト値。
  include	他のYAMLファイルから設定をインポートします。
  stages	パイプラインステージの名前と順序。
  variables	パイプラインのすべてのジョブのデフォルトCI/CD変数を定義します。
  workflow	実行するパイプラインのタイプを制御します。

• ヘッダーキーワード

  キーワード	説明
  spec	外部設定ファイルの仕様を定義します。

• ジョブキーワードを使用して設定されるジョブ:

  キーワード	説明
  after_script	ジョブの後に実行される一連のコマンドをオーバーライドします。
  allow_failure	ジョブの失敗を許容します。ジョブが失敗してもパイプライン全体の失敗とはなりません。
  artifacts	成功時にジョブに添付されるファイルとディレクトリのリスト。
  before_script	ジョブの前に実行される一連のコマンドをオーバーライドします。
  cache	後続の実行間でキャッシュされるファイルのリスト。
  coverage	指定されたジョブのコードカバレッジ設定。
  dast_configuration	ジョブレベルでDASTプロファイルの設定を使用します。
  dependencies	アーティファクトのフェッチ元のジョブのリストを指定することで、特定のジョブに渡されるアーティファクトを制限します。
  environment	ジョブのデプロイ先の環境の名前。
  extends	このジョブが継承する設定エントリ。
  identity	アイデンティティフェデレーションを使用したサードパーティサービスの認証を行います。
  image	Dockerイメージを使用します。
  inherit	すべてのジョブが継承するグローバルデフォルトを選択します。
  interruptible	より新しい実行によってジョブが冗長になった場合に、ジョブをキャンセルできるかどうかを定義します。
  manual_confirmation	手動ジョブのカスタム確認メッセージを定義します。
  needs	ステージの順序よりも早い時点でジョブを実行します。
  pages	GitLab Pagesで使用するためにジョブの結果をアップロードします。
  parallel	並列実行するジョブインスタンスの数。
  release	リリースオブジェクトを生成するようにRunnerに指示します。
  resource_group	ジョブの並行処理を制限します。
  retry	ジョブが失敗した場合に、ジョブを自動的に再試行できる条件と回数。
  rules	ジョブの一部の属性を評価し、そのジョブが作成されるかどうかを決定する条件のリスト。
  script	Runnerが実行するShellスクリプト。
  run	Runnerが実行する実行設定。
  secrets	ジョブに必要なCI/CDシークレット。
  services	Dockerサービスイメージを使用します。
  stage	ジョブステージを定義します。
  start_in	指定された期間、ジョブの実行を遅らせます。when: delayedが必要です。
  tags	Runnerを選択するために使用されるタグのリスト。
  timeout	プロジェクト全体の設定よりも優先される、カスタムのジョブレベルのタイムアウトを定義します。
  trigger	ダウンストリームパイプライントリガーを定義します。
  variables	個々のジョブのCI/CD変数を定義します。
  when	ジョブを実行するタイミング。

• 現在は使用が推奨されていない非推奨のキーワード。

グローバルキーワード

一部のキーワードはジョブでは定義されません。これらのキーワードは、パイプラインの動作を制御するか、追加のパイプライン設定をインポートします。

default

一部のキーワードではグローバルデフォルトを設定できます。各デフォルトキーワードは、まだそのキーワードが定義されていないすべてのジョブにコピーされます。

デフォルト設定はジョブの設定とマージされません。ジョブにキーワードがすでに定義されている場合、そのキーワードのジョブキーワードが優先され、そのキーワードのデフォルト設定は使用されません。

キーワードのタイプ: グローバルキーワード。

サポートされている値: 以下のキーワードにはカスタムデフォルトを設定できます。

• after_script
• artifacts
• before_script
• cache
• hooks
• id_tokens
• image
• interruptible
• retry
• services
• tags
• timeout。ただし、イシュー213634のためこのキーワードには効果がありません。

defaultの例:

default:
  image: ruby:3.0
  retry: 2

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: ruby:2.7
  script: bundle exec rspec

この例では:

• image: ruby:3.0とretry: 2は、パイプラインのすべてのジョブのデフォルトキーワードです。
• rspecジョブではimageとretryが定義されていないため、デフォルトのimage: ruby:3.0とretry: 2が使用されます。
• rspec 2.7ジョブではretryが定義されていませんが、imageが明示的に定義されています。そのため、デフォルトのretry: 2が使用されますが、デフォルトのimageは無視され、ジョブで定義されているimage: ruby:2.7が使用されます。

補足情報:

• inherit:defaultを使用することで、ジョブごとにデフォルトキーワードの継承を制御できます。
• グローバルデフォルトはダウンストリームパイプラインには引き継がれません。ダウンストリームパイプラインは、それをトリガーしたアップストリームパイプラインとは独立して実行されます。

include

includeを使用して、外部のYAMLファイルをCI/CD設定にインクルードすることができます。1つの長い.gitlab-ci.ymlファイルを複数のファイルに分割することで読みやすさを向上させたり、複数の場所で同じ設定が重複する状況を減らしたりすることができます。

テンプレートファイルを中央のリポジトリに保存し、プロジェクトにインクルードすることもできます。

includeファイルは次のように処理されます。

• .gitlab-ci.ymlファイルの内容とマージされます。
• includeキーワードの位置に関係なく、常に最初に評価され、.gitlab-ci.ymlファイルの内容とマージされます。

すべてのファイルを解決するための制限時間は30秒です。

キーワードのタイプ: グローバルキーワード。

サポートされている値: includeサブキー。

• include:component
• include:local
• include:project
• include:remote
• include:template

オプションで使用可能:

• include:inputs
• include:rules
• include:integrity

補足情報:

• includeキーワードでは特定のCI/CD変数のみを使用できます。
• マージを使用して、インクルードされるCI/CD設定をローカルでカスタマイズおよびオーバーライドできます。
• インクルードされる設定をオーバーライドするには、.gitlab-ci.ymlファイルに同じジョブ名またはグローバルキーワードを指定します。2つの設定がマージされ、インクルードされる設定よりも.gitlab-ci.ymlファイル内の設定が優先されます。
• 再実行する場合:
  • ジョブを再実行すると、includeファイルは再度フェッチされません。パイプラインのすべてのジョブは、パイプラインの作成時にフェッチされた設定を使用します。そのため、ソースincludeファイルが変更されても、ジョブの再実行には影響しません。
  • パイプラインを再実行すると、includeファイルが再度フェッチされます。前回のパイプライン実行後にこれらのファイルが変更されていた場合、新しいパイプラインは変更された設定を使用します。
• デフォルトでは、ネストされたインクルードを含めて、パイプラインごとに最大150個のインクルードを使用できます。補足情報を以下に示します。
  • GitLab 16.0以降、GitLab Self-Managedのユーザーは、最大インクルード数の値を変更できるようになりました。
  • GitLab 15.10以降、最大150個のインクルードを設定できます。ネストされたインクルードでは、同じファイルを複数回インクルードできますが、重複したインクルードもカウントの対象になります。
  • GitLab 14.9からGitLab 15.9では、最大100個のインクルードを使用できます。ネストされたインクルードでは同じファイルを複数回インクルードできますが、重複は無視されます。

include:component

include:componentを使用して、CI/CDコンポーネントをパイプライン設定に追加します。

キーワードのタイプ: グローバルキーワード。

サポートされている値: CI/CDコンポーネントの完全なアドレス（形式: <fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>）。

include:componentの例:

include:
  - component: $CI_SERVER_FQDN/my-org/security-components/secret-detection@1.0

関連トピック:

• CI/CDコンポーネントを使用する。

include:local

include:localを使用して、includeキーワードを含む設定ファイルと同じリポジトリおよびブランチにあるファイルをインクルードします。シンボリックリンクの代わりにinclude:localを使用します。

キーワードのタイプ: グローバルキーワード。

サポートされている値:

ルートディレクトリ（/）を基準にしたフルパス:

• YAMLファイルの拡張子は、.ymlまたは.yamlである必要があります。
• ファイルパスではワイルドカード*と**を使用できます。
• 特定のCI/CD変数を使用できます。

include:localの例:

include:
  - local: '/templates/.gitlab-ci-template.yml'

短縮構文を使用してパスを定義することもできます。

include: '.gitlab-ci-production.yml'

補足情報:

• .gitlab-ci.ymlファイルとローカルファイルは、同じブランチに存在している必要があります。
• Gitサブモジュールパスを使用してローカルファイルをインクルードすることはできません。
• include設定は常に、パイプラインを実行しているプロジェクトではなく、includeキーワードを含むファイルの場所を基準に評価されます。そのため、ネストされたincludeが別のプロジェクトの設定ファイル内にある場合、include: localはその別のプロジェクト内でファイルを確認します。

include:project

同じGitLabインスタンス上の別の非公開プロジェクトからファイルをインクルードするには、include:projectとinclude:fileを使用します。

キーワードのタイプ: グローバルキーワード。

サポートされている値:

• include:project: GitLabプロジェクトのフルパス。
• include:file: ルートディレクトリ（/）を基準にしたファイルのフルパス、またはファイルパスの配列。YAMLファイルの拡張子は.ymlまたは.yamlでなければなりません。
• include:ref: オプション。ファイルの取得元のref。指定しない場合、デフォルトはプロジェクトのHEADです。
• 特定のCI/CD変数を使用できます。

include:projectの例:

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-subgroup/my-project-2'
    file:
      - '/templates/.builds.yml'
      - '/templates/.tests.yml'

refを指定することもできます。

include:
  - project: 'my-group/my-project'
    ref: main                                      # Git branch
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: v1.0.0                                    # Git Tag
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

補足情報:

• include設定は常に、パイプラインを実行しているプロジェクトではなく、includeキーワードを含むファイルの場所を基準に評価されます。そのため、ネストされたincludeが別のプロジェクトの設定ファイル内にある場合、include: localはその別のプロジェクト内でファイルを確認します。
• パイプラインが開始されると、すべての方法によってインクルードされた.gitlab-ci.ymlファイルの設定が評価されます。この設定はその時点でのスナップショットであり、データベースに保持されます。GitLabは、参照先の.gitlab-ci.ymlファイルの設定が変更されても、次のパイプラインが開始されるまではその変更を反映しません。
• 別の非公開プロジェクトのYAMLファイルをインクルードする場合、パイプラインを実行するユーザーは両方のプロジェクトのメンバーであり、パイプラインを実行するための適切な権限を持っている必要があります。ユーザーがインクルード対象のファイルにアクセスできない場合、not found or access deniedエラーが表示されることがあります。
• 別のプロジェクトのCI/CD設定ファイルをインクルードする場合は注意してください。CI/CD設定ファイルが変更されても、パイプラインや通知はトリガーされません。セキュリティの観点では、これはサードパーティの依存関係をプルすることと似ています。refについては以下を検討してください。
  • 特定のSHAハッシュを使用する。これはもっとも安定したオプションです。目的のコミットが確実に参照されるように、40文字の完全なSHAハッシュを使用してください。refに短いSHAハッシュを使用すると、あいまいになる可能性があるためです。
  • 他のプロジェクトのrefに対して、保護ブランチと保護タグの両方のルールを適用する。保護タグと保護ブランチは、変更される前に変更管理を通過する可能性が高くなります。

include:remote

include:remoteと完全なURLを使用して、別の場所にあるファイルをインクルードします。

キーワードのタイプ: グローバルキーワード。

サポートされている値:

HTTP/HTTPS GETリクエストでアクセス可能な公開URL:

• リモートURLの認証はサポートされていません。
• YAMLファイルの拡張子は、.ymlまたは.yamlである必要があります。
• 特定のCI/CD変数を使用できます。

include:remoteの例:

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'

補足情報:

• すべてのネストされたインクルードは、公開ユーザーとしてコンテキストなしで実行されるため、公開プロジェクトまたはテンプレートのみをインクルードできます。ネストされたインクルードのincludeセクションでは、変数は使用できません。
• 別のプロジェクトのCI/CD設定ファイルをインクルードする場合は注意してください。他のプロジェクトのファイルが変更されても、パイプラインや通知はトリガーされません。セキュリティの観点では、これはサードパーティの依存関係をプルすることと似ています。インクルードするファイルの整合性を検証するには、integrityキーワードを使用することを検討してください。所有している別のGitLabプロジェクトにリンクする場合は、保護ブランチと保護タグの両方を使用して変更管理ルールを適用することを検討してください。

include:template

include:templateを使用して、.gitlab-ci.ymlテンプレートをインクルードします。

キーワードのタイプ: グローバルキーワード。

サポートされている値:

CI/CDテンプレート:

• すべてのテンプレートは、lib/gitlab/ci/templatesで確認できます。すべてのテンプレートがinclude:templateでの使用を前提として設計されているわけではないため、使用する前にテンプレートのコメントを確認してください。
• 特定のCI/CD変数を使用できます。

include:templateの例:

# File sourced from the GitLab template collection
include:
  - template: Auto-DevOps.gitlab-ci.yml

複数のinclude:templateファイル:

include:
  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml

補足情報:

• すべてのネストされたインクルードは、公開ユーザーとしてコンテキストなしで実行されるため、公開プロジェクトまたはテンプレートのみをインクルードできます。ネストされたインクルードのincludeセクションでは、変数は使用できません。

include:inputs

インクルードされた設定がspec:inputsを使用しパイプラインに追加される際、include:inputsを使用して入力パラメータの値を設定します。

キーワードのタイプ: グローバルキーワード。

サポートされている値: 文字列、数値、またはブール値。

include:inputsの例:

include:
  - local: 'custom_configuration.yml'
    inputs:
      website: "My website"

この例では:

• custom_configuration.ymlに含まれる設定がパイプラインに追加され、インクルードされる設定のwebsiteインプットにはMy websiteという値が設定されます。

補足情報:

• インクルードされる設定ファイルがspec:inputs:typeを使用している場合、インプット値は定義された型と一致している必要があります。
• インクルードされる設定ファイルがspec:inputs:optionsを使用している場合、インプット値はリストされているオプションのいずれかと一致している必要があります。

関連トピック:

• includeの使用時に入力値を設定する。

include:rules

rulesとincludeを組み合わせて使用すると、他の設定ファイルを条件付きでインクルードできます。

キーワードのタイプ: グローバルキーワード。

サポートされている値: 次のrulesサブキー:

• rules:if。
• rules:exists。
• rules:changes。

一部のCI/CD変数がサポートされています。

include:rulesの例:

include:
  - local: build_jobs.yml
    rules:
      - if: $INCLUDE_BUILDS == "true"

test-job:
  stage: test
  script: echo "This is a test job"

この例では、INCLUDE_BUILDS変数の値に応じて次のようになります。

• trueの場合、build_jobs.ymlの設定がパイプラインにインクルードされます。
• trueではない場合、または変数が存在しない場合は、build_jobs.ymlの設定はパイプラインにインクルードされません。

関連トピック:

• includeを使用した例:
  • rules:if。
  • rules:changes。
  • rules:exists。

include:integrity

integrityをinclude:remoteと組み合わせて使用して、インクルードされたリモートファイルのSHA256ハッシュを指定します。integrityの値が実際の内容と一致しない場合、そのリモートファイルは処理されず、パイプラインは失敗します。

キーワードのタイプ: グローバルキーワード。

サポートされている値: インクルードされるコンテンツのBase64エンコードされたSHA256ハッシュ。

include:integrityの例:

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'
    integrity: 'sha256-L3/GAoKaw0Arw6hDCKeKQlV1QPEgHYxGBHsH4zG1IY8='

stages

stagesを使用して、ジョブのグループを含むステージを定義します。ジョブにstageを指定することで、そのジョブを特定のステージで実行するように設定できます。

.gitlab-ci.ymlファイルでstagesが定義されていない場合、デフォルトのパイプラインステージは次のとおりです。

• .pre
• build
• test
• deploy
• .post

stagesに列挙された項目の順序によって、ジョブの実行順序が決まります。

• 同じステージ内のジョブは並列実行されます。
• 次のステージのジョブは、前のステージのジョブが正常に完了した後に実行されます。

パイプラインに.preステージまたは.postステージのジョブしか含まれていない場合、そのパイプラインは実行されません。これら以外のステージに少なくとも1つのジョブが必要です。

キーワードのタイプ: グローバルキーワード。

stagesの例:

stages:
  - build
  - test
  - deploy

この例では:

1. build内のすべてのジョブは並列実行されます。
2. build内のすべてのジョブが成功すると、test内のジョブが並列実行されます。
3. test内のすべてのジョブが成功すると、deploy内のジョブが並列実行されます。
4. deploy内のすべてのジョブが成功すると、パイプラインはpassedとしてマークされます。

いずれかのジョブが失敗すると、パイプラインはfailedとしてマークされ、後続ステージのジョブは開始されません。現在のステージのジョブは停止されず、引き続き実行されます。

補足情報:

• ジョブにstageが指定されていない場合、そのジョブにはtestステージが割り当てられます。
• ステージが定義されていても、そのステージを使用するジョブが存在しない場合、パイプラインには表示されません。これは、コンプライアンスパイプライン設定に役立ちます。
  • ステージはコンプライアンス設定で定義できますが、使用されなければ非表示のままになります。
  • 定義されたステージをデベロッパーがジョブ定義で使用すると、これらのステージが表示されます。

関連トピック:

• ジョブをより早い時点で開始し、ステージの順序を無視するには、needsキーワードを使用する。

workflow

workflowを使用して、パイプラインの動作を制御します。

workflowの設定では、一部の定義済みCI/CD変数を使用できますが、ジョブの開始時にのみ定義される変数は使用できません。

関連トピック:

• workflow: rulesの例
• ブランチパイプラインとマージリクエストパイプラインを切り替える

workflow:auto_cancel:on_new_commit

workflow:auto_cancel:on_new_commitを使用して、冗長なパイプラインを自動キャンセル機能の動作を設定します。

サポートされている値:

• conservative: パイプラインをキャンセルします。ただし、interruptible: falseが設定されたジョブがまだ開始されていない場合に限ります。定義されていない場合は、この値がデフォルトです。
• interruptible: interruptible: trueが設定されたジョブのみをキャンセルします。
• none: ジョブは自動キャンセルされません。

workflow:auto_cancel:on_new_commitの例:

workflow:
  auto_cancel:
    on_new_commit: interruptible

job1:
  interruptible: true
  script: sleep 60

job2:
  interruptible: false  # Default when not defined.
  script: sleep 60

この例では:

• 新しいコミットがブランチにプッシュされると、GitLabは新しいパイプラインを作成し、job1とjob2が開始されます。
• ジョブが完了する前に新しいコミットがブランチにプッシュされると、job1のみがキャンセルされます。

workflow:auto_cancel:on_job_failure

workflow:auto_cancel:on_job_failureを使用して、いずれかのジョブが失敗した場合にキャンセルするジョブを設定します。

サポートされている値:

• all: いずれかのジョブが失敗すると、パイプラインと実行中のすべてのジョブが直ちにキャンセルされます。
• none: ジョブは自動キャンセルされません。

workflow:auto_cancel:on_job_failureの例:

stages: [stage_a, stage_b]

workflow:
  auto_cancel:
    on_job_failure: all

job1:
  stage: stage_a
  script: sleep 60

job2:
  stage: stage_a
  script:
    - sleep 30
    - exit 1

job3:
  stage: stage_b
  script:
    - sleep 30

この例では、job2が失敗した場合、job1がまだ実行中であればキャンセルされ、job3は開始されません。

関連トピック:

• ダウンストリームパイプラインから親パイプラインを自動キャンセルする

workflow:name

workflow:でnameを使用して、パイプラインの名前を定義できます。

定義された名前はすべてのパイプラインに割り当てられます。名前の先頭または末尾のスペースは削除されます。

サポートされている値:

• 文字列。
• CI/CD変数。
• 両方の組み合わせ。

workflow:nameの例:

定義済み変数を使用した単純なパイプライン名:

workflow:
  name: 'Pipeline for branch: $CI_COMMIT_BRANCH'

パイプラインの条件に応じてパイプライン名が異なる設定:

variables:
  PROJECT1_PIPELINE_NAME: 'Default pipeline name'  # A default is not required

workflow:
  name: '$PROJECT1_PIPELINE_NAME'
  rules:
    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
      variables:
        PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PROJECT1_PIPELINE_NAME: 'MR pipeline: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # For default branch pipelines, use the default name

補足情報:

• 名前が空の文字列の場合、パイプラインには名前が割り当てられません。CI/CD変数のみで構成された名前は、それらの変数もすべて空の場合、空の文字列と評価される可能性があります。
• workflow:rules:variablesで定義された変数は、すべてのジョブで使用できるデフォルト変数になります。これには、デフォルトで変数をダウンストリームパイプラインに転送するtriggerジョブも含まれます。ダウンストリームパイプラインが同じ変数を使用する場合、アップストリーム変数の値によって変数が上書きされます。そのため、次のいずれかを必ず実施してください。
  • 各プロジェクトのパイプライン設定で一意の変数名を使用する（例: PROJECT1_PIPELINE_NAME）。
  • トリガージョブでinherit:variablesを使用し、ダウンストリームパイプラインに転送する正確な変数をリストする。

workflow:rules

workflowにおけるrulesキーワードは、ジョブで定義されるrulesに似ていますが、パイプライン全体を作成するかどうかを制御します。

trueと評価されるルールがない場合、パイプラインは実行されません。

サポートされている値: ジョブレベルのrulesと同じキーワードの一部を使用できます。

• rules: if。
• rules: changes。
• rules: exists。
• when。workflowとともに使用する場合はalwaysまたはneverのみ指定できます。
• variables。

workflow:rulesの例:

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

この例では、パイプラインが実行されるのは、コミットタイトル（コミットメッセージの1行目）が-draftで終わっておらず、パイプラインが次のいずれかに該当する場合です。

• マージリクエスト。
• デフォルトブランチ。

補足情報:

• ルールがブランチパイプライン（デフォルトブランチ以外）とマージリクエストパイプラインの両方に一致する場合、パイプラインが重複して作成される可能性があります。
• start_in、allow_failure、needsは、workflow:rulesでサポートされていませんが、構文違反にはなりません。効果はありませんが、将来的に構文エラーを引き起こす可能性があるため、workflow:rulesでは使用しないでください。詳細については、イシュー436473を参照してください。

関連トピック:

• workflow:rulesの一般的なif句。
• rulesを使用してマージリクエストパイプラインを実行する。

workflow:rules:variables

workflow:rulesでvariablesを使用して、特定のパイプライン条件の変数を定義します。

条件が一致すると変数が作成されます。この変数は、パイプライン内のすべてのジョブで使用できます。すでにその変数がデフォルト変数としてトップレベルで定義されている場合でも、workflow変数が優先され、デフォルト変数はオーバーライドされます。

キーワードのタイプ: グローバルキーワード。

サポートされている値: 変数名と値のペア:

• 名前には数字、英字、アンダースコア（_）のみを使用できます。
• 値は文字列でなければなりません。

workflow:rules:variablesの例:

variables:
  DEPLOY_VARIABLE: "default-deploy"

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        DEPLOY_VARIABLE: "deploy-production"  # Override globally-defined DEPLOY_VARIABLE
    - if: $CI_COMMIT_BRANCH =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
    - if: $CI_COMMIT_BRANCH                   # Run the pipeline in other cases

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:                                   # Override DEPLOY_VARIABLE defined
        DEPLOY_VARIABLE: "job1-deploy-production"  # at the job level.
    - when: on_success                             # Run the job in other cases
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

job2:
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

ブランチがデフォルトブランチの場合:

• job1のDEPLOY_VARIABLEはjob1-deploy-productionです。
• job2のDEPLOY_VARIABLEはdeploy-productionです。

ブランチがfeatureの場合:

• job1のDEPLOY_VARIABLEはjob1-default-deployであり、IS_A_FEATUREはtrueです。
• job2のDEPLOY_VARIABLEはdefault-deployであり、IS_A_FEATUREはtrueです。

ブランチがそれ以外の場合:

• job1のDEPLOY_VARIABLEはjob1-default-deployです。
• job2のDEPLOY_VARIABLEはdefault-deployです。

補足情報:

• workflow:rules:variablesで定義された変数は、すべてのジョブで使用できるデフォルト変数になります。これには、デフォルトで変数をダウンストリームパイプラインに転送するtriggerジョブも含まれます。ダウンストリームパイプラインが同じ変数を使用する場合、アップストリーム変数の値によって変数が上書きされます。そのため、次のいずれかを必ず実施してください。
  • 各プロジェクトのパイプライン設定で一意の変数名を使用する（例: PROJECT1_VARIABLE_NAME）。
  • トリガージョブでinherit:variablesを使用し、ダウンストリームパイプラインに転送する正確な変数をリストする。

workflow:rules:auto_cancel

workflow:rules:auto_cancelを使用して、workflow:auto_cancel:on_new_commit機能またはworkflow:auto_cancel:on_job_failure機能の動作を設定します。

サポートされている値:

• on_new_commit: workflow:auto_cancel:on_new_commit
• on_job_failure: workflow:auto_cancel:on_job_failure

workflow:rules:auto_cancelの例:

workflow:
  auto_cancel:
    on_new_commit: interruptible
    on_job_failure: all
  rules:
    - if: $CI_COMMIT_REF_PROTECTED == 'true'
      auto_cancel:
        on_new_commit: none
        on_job_failure: none
    - when: always                  # Run the pipeline in other cases

test-job1:
  script: sleep 10
  interruptible: false

test-job2:
  script: sleep 10
  interruptible: true

この例では、デフォルトですべてのジョブのworkflow:auto_cancel:on_new_commitがinterruptibleに設定され、workflow:auto_cancel:on_job_failureがallに設定されます。ただし、保護ブランチに対してパイプラインが実行される場合、ルールはデフォルトをon_new_commit: noneとon_job_failure: noneでオーバーライドします。たとえば、パイプラインの実行対象によって、動作は次のように変わります。

• 保護されていないブランチに対して実行される場合、新しいコミットがプッシュされると、test-job1の実行が継続され、test-job2はキャンセルされます。
• 保護ブランチに対して実行される場合、新しいコミットがプッシュされると、test-job1とtest-job2の両方の実行が継続されます。

ヘッダーキーワード

いくつかのキーワードは、YAML設定ファイルのヘッダーセクションで定義する必要があります。ヘッダーはファイルの先頭に配置し、設定の他の部分と---で区切る必要があります。

spec

YAMLファイルのヘッダーにspecセクションを追加すると、includeキーワードを使用して設定がパイプラインに追加されたときのパイプラインの動作を設定できます。

仕様は設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。このセクションは、設定の他の部分と---で区切られています。

spec:inputs

spec:inputsを使用して、CI/CD設定に対するインプットを定義できます。

ヘッダーセクションの外部でその値を参照するには、補間形式$[[ inputs.input-id ]]を使用します。インプットは、パイプライン作成時に設定がフェッチされる際に評価および補間されます。inputsを使用すると、設定が.gitlab-ci.ymlファイルの内容とマージされる前に補間が完了します。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: 予期される入力を表す文字列のハッシュ。

spec:inputsの例:

spec:
  inputs:
    environment:
    job-stage:
---

scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

補足情報:

• spec:inputs:defaultを使用してデフォルト値を設定しない限り、入力は必須です。include:inputsと組み合わせてインプットを使用する場合を除き、インプットを必須にするのは避けることをおすすめします。
• インプットは文字列を想定しています。ただし、spec:inputs:typeを使用して別の型を指定する場合を除きます。
• 補間ブロックを含む文字列は、1 MB以下にする必要があります。
• 補間ブロック内の文字列は、1 KB以下にする必要があります。
• 入力値は新しいパイプラインの実行時に定義できます。

関連トピック:

• spec:inputsで入力パラメータを定義する。

spec:inputs:default

spec:inputs:defaultを使用してデフォルト値を設定しない限り、仕様に含まれるインプットはすべて必須になります。

デフォルト値を設定しない場合はdefault: ''を使用します。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: デフォルト値を表す文字列、または''。

spec:inputs:defaultの例:

spec:
  inputs:
    website:
    user:
      default: 'test-user'
    flags:
      default: ''
---
# The pipeline configuration would follow...

この例では:

• websiteは必須であり、定義する必要があります。
• userはオプションです。定義されていない場合、値はtest-userになります。
• flagsはオプションです。定義されていない場合、値はありません。

補足情報:

• インプットが次の条件に該当する場合、パイプラインは検証エラーで失敗します。
  • defaultとoptionsの両方を使用しているが、デフォルト値が、リストされているオプションのいずれでもない。
  • defaultとregexの両方を使用しているが、デフォルト値が正規表現と一致しない。
  • 値がtypeと一致しない。

spec:inputs:description

descriptionを使用して、特定の入力に説明を付けます。説明はインプットの動作に影響を与えません。ファイルのユーザーがインプットを理解できるようにする目的でのみ使用されます。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: 説明を表す文字列。

spec:inputs:descriptionの例:

spec:
  inputs:
    flags:
      description: 'Sample description of the `flags` input details.'
---
# The pipeline configuration would follow...

spec:inputs:options

インプットでoptionsを使用して、インプットに許可される値のリストを指定できます。各入力に指定できるオプションの数は、最大50個までです。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: 入力オプションの配列。文字列と数値のtype入力のみをオプションで使用できます。

spec:inputs:optionsの例:

spec:
  inputs:
    environment:
      options:
        - development
        - staging
        - production
---
# The pipeline configuration would follow...

この例では:

• environmentは必須であり、リスト内のいずれかの値で定義する必要があります。

補足情報:

• 次の場合、パイプラインは検証エラーで失敗します。
  • インプットでoptionsとdefaultの両方を使用しているが、デフォルト値が、リストされているオプションのいずれでもない。
  • いずれかのインプットオプションがtypeと一致していない。optionsを使用する場合はstringまたはnumberを指定する必要があり、booleanは使用できない。

spec:inputs:regex

spec:inputs:regexを使用して、入力が一致する必要がある正規表現を指定します。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: 正規表現である必要があります。

spec:inputs:regexの例:

spec:
  inputs:
    version:
      regex: ^v\d\.\d+(\.\d+)?$
---
# The pipeline configuration would follow...

この例では、v1.0またはv1.2.3の入力は正規表現に一致し、検証に合格します。v1.A.B の入力v1.0は正規表現v1.0と一致せず、検証v1.0`に失敗します。

補足情報:

• inputs:regexは、typeがstringの場合にのみ使用できます。numberまたはbooleanの場合は使用できません。
• /文字で正規表現を囲まないでください。たとえば、/regex.*/ではなくregex.*を使用します。
• inputs:regexはRE2を使用して正規表現を解析します。
• 正規表現に対する入力の検証は、変数の展開前に行われます。入力テキストに変数の名前が含まれている場合、検証されるのは変数の値ではなく、入力のraw値（変数の名前）です。

spec:inputs:rules

spec:inputs:rulesを使用して、他の入力の値に基づいて、入力の条件付きのoptionsとdefaultの値を定義します。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: ルールオブジェクトの配列。各ルールには以下を含めることができます:

• if: $[[ inputs.input-id ]]構文を使用して、入力値をチェックする条件式。
• options: 入力に対して許可される値の配列。
• default: このルールに一致した場合の入力のデフォルト値。default: nullを使用して、ユーザーが入力に独自の値エントリを入力できるようにします。

spec:inputs:rulesの例:

spec:
  inputs:
    environment:
      options: ['development', 'production']
      default: 'development'

    instance_type:
      description: 'VM instance size'
      rules:
        - if: $[[ inputs.environment ]] == 'development'
          options: ['small', 'medium']
          default: 'small'
        - if: $[[ inputs.environment ]] == 'production'
          options: ['large', 'xlarge']
          default: 'large'
---

deploy:
  script: echo "Deploying $[[ inputs.instance_type ]] instance"

この例では、environmentがdevelopmentの場合、ユーザーはsmallまたはmediumインスタンスのみを選択できます。environmentがproductionの場合、largeまたはxlargeインスタンスのみ使用できます。

補足情報:

• ルールは順番に評価されます。一致するif条件を持つ最初のルールが使用されます。
• if条件のないルールは、他のルールが一致しない場合にフォールバックとして機能します。
• フォールバックルールは、少なくとも1つの値でoptionsを定義する必要があります。
• optionsを持つすべてのルールは、optionsリストに存在するdefault値も定義する必要があります。
• 同じ入力に対して、rulesとトップレベルのoptionsまたはdefaultの両方を使用することはできません。

関連トピック:

• spec:inputs:rulesを使用して条件付きの入力オプションを定義する。

spec:inputs:type

デフォルトでは、入力は文字列を想定しています。spec:inputs:typeを使用すると、入力に必要な別の型を指定できます。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: 次のいずれかです。

• array: 入力の配列を受け入れます。
• string: 文字列のインプットを受け入れます（定義されていない場合のデフォルト）。
• number: 数値の入力のみを受け入れます。
• boolean: trueまたはfalseの入力のみを受け入れます。

spec:inputs:typeの例:

spec:
  inputs:
    job_name:
    website:
      type: string
    port:
      type: number
    available:
      type: boolean
    array_input:
      type: array
---
# The pipeline configuration would follow...

spec:include

spec:includeを使用して、他のファイルから外部入力定義を含めます。複数のパイプライン設定で入力定義を共有して再利用できます。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: インクルード場所の配列。local、remote、およびprojectインクルードのみをサポートします。

spec:includeの例:

spec:
  include:
    - local: /shared-inputs.yml
  inputs:
    environment:
      default: production
---

deploy:
  script: echo "Deploying to $[[ inputs.environment ]]"

異なるソースからの複数のインクルードの場合:

spec:
  include:
    - local: /base-inputs.yml
    - remote: 'https://example.com/ci/common-inputs.yml'
    - project: 'my-group/shared-configs'
      ref: main
      file: '/ci/team-inputs.yml'
  inputs:
    environment:
      default: production
---

deploy:
  script: echo "Deploying to $[[ inputs.environment ]]"

補足情報:

• CI/CDコンポーネントでspec:includeを使用することはできません。
• 外部入力ファイルには、inputsキーのみが含まれている必要があります。他のキーは検証エラーを引き起こします。
• 最初に外部入力がマージされ、次にインライン入力が適用されます。
• インライン入力は、同じ名前の外部入力よりも優先されます。
• 複数の入力ファイルを含める場合、指定された順序でマージされます。
• local 、remote 、およびprojectインクルードタイプをサポートします。template、component、またはartifactインクルードはサポートされていません。

関連トピック:

• 外部ファイルから入力を使用する。

spec:component

spec:componentを使用して、CI/CDコンポーネントで補間に使用できるコンポーネントコンテキストデータを定義します。

コンポーネントコンテキストは、コンポーネント自体のメタデータ（名前、バージョン、コミットSHAなど）を提供します。これにより、コンポーネントテンプレートが独自のメタデータを動的に参照できるようになります。

補間形式$[[ component.field-name ]]を使用して、コンポーネントテンプレートでコンポーネントコンテキスト値を参照します。

キーワードのタイプ: ヘッダーキーワード。specは、設定ファイルの先頭にあるヘッダーセクションで宣言する必要があります。

サポートされている値: 文字列の配列。各文字列は、次のいずれかである必要があります:

• name: コンポーネントパスで指定されているコンポーネント名。
• sha: コンポーネントのコミットSHA。
• version: カタログリソースから解決されたセマンティックバージョン。次の場合にnullを返します:
  • コンポーネントがカタログリソースではない。
  • 参照がブランチ名またはコミットSHA（リリースされたバージョンではない）である。
• reference: コンポーネントパスの@の後に指定された元の参照。たとえば、1.0、~latest、ブランチ名、またはコミットSHA。

spec:componentの例:

spec:
  component: [name, version, reference]
  inputs:
    image_tag:
      default: latest
---

build-image:
  image: registry.example.com/$[[ component.name ]]:$[[ component.version ]]
  script:
    - echo "Building with component version $[[ component.version ]]"
    - echo "Component reference: $[[ component.reference ]]"

補足情報:

• versionフィールドは、以下を使用する場合に実際のセマンティックバージョンに解決されます:
  • @1.0.0のような完全なバージョン（1.0.0を返します）
  • @1.0のような部分的なバージョン（たとえば、1.0.2のように、一致する最新のバージョンを返します）
  • @~latest （最新のバージョンを返します）
• referenceフィールドは、@の後に指定された正確な値を常に返します:
  • @1.0は1.0を返します（versionが1.0.2を返す場合があります）
  • @~latestは~latestを返します（versionは実際のバージョン番号を返します）
  • @abc123はabc123を返します（versionがnullを返す場合）

関連トピック:

• コンポーネントでコンポーネントコンテキストを使用する。

ジョブキーワード

以降のトピックでは、キーワードを使用してCI/CDパイプラインを設定する方法について説明します。

after_script

after_scriptを使用して、ジョブのbefore_scriptセクションとscriptセクションの完了後に最後に実行するコマンドの配列を定義します。after_scriptのコマンドは、次の条件に該当する場合にも実行されます。

• before_scriptセクションまたはscriptセクションの実行中に、ジョブがキャンセルされた場合。
• ジョブでscript_failureという種類の失敗が発生した場合（ただし、それ以外の種類の失敗では実行されません）。

ジョブの設定とデフォルト設定は一緒にマージされません。パイプラインにdefault:after_scriptが定義されていて、ジョブにもafter_scriptがある場合、ジョブの設定が優先され、デフォルト設定は使用されません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値: 次の内容を含む配列。

• 1行のコマンド。
• 複数行に分割された長いコマンド。
• YAMLアンカー。

CI/CD変数がサポートされています。

after_scriptの例:

job:
  script:
    - echo "An example script section."
  after_script:
    - echo "Execute this command after the `script` section completes."

補足情報:

after_scriptで指定するスクリプトは、before_scriptコマンドまたはscriptコマンドとは別のShellで実行されます。その結果、スクリプトは次のようになります。

• 現在のワーキングディレクトリがデフォルトにリセットされます（デフォルト値は、RunnerがGitリクエストをどのように処理するかを定義する変数に基づいて決まります）。
• before_scriptまたはscriptで定義されたコマンドによる変更にはアクセスできません。これには以下が含まれます。
  • scriptスクリプトでエクスポートされたコマンドエイリアスと変数。
  • ワークツリー外の変更（Runnerのexecutorによってアクセス可否が異なります）。たとえば、before_scriptまたはscriptスクリプトによってインストールされたソフトウェアなどが該当します。
• 個別のタイムアウトが設定されます。GitLab Runner 16.4以降では、デフォルトは5分で、RUNNER_AFTER_SCRIPT_TIMEOUT変数で設定できます。GitLab 16.3以前では、タイムアウトは5分にハードコードされています。
• ジョブの終了コードには影響しません。scriptセクションが成功し、after_scriptがタイムアウトになるか失敗した場合、ジョブはコード0（Job Succeeded）で終了します。
• after_scriptでCI/CDジョブトークンを使用する場合の既知の問題があります。after_scriptコマンドでの認証にジョブトークンを使用することはできますが、ジョブがキャンセルされるとそのトークンは直ちに無効になります。詳細については、イシューを参照してください。
• ジョブがタイムアウトした場合:
  • after_scriptコマンドはデフォルトでは実行されません。
  • タイムアウト値を設定することで、after_scriptを確実に実行させることができます。そのためには、ジョブのタイムアウトを超えないように、RUNNER_SCRIPT_TIMEOUTとRUNNER_AFTER_SCRIPT_TIMEOUTに適切な値を設定します。
• トップレベルでafter_scriptを使用しても、defaultセクションでは使用しない場合、非推奨になります。

Execution timing and file inclusion:

after_scriptコマンドは、キャッシュおよびアーティファクトのアップロード操作の前に実行されます。

• アーティファクトコレクションを構成した場合:
  • after_scriptで作成または変更されたファイルは、アーティファクトに含まれます。
  • after_scriptで行われた変更は、キャッシュのアップロードに含まれます。
• after_scriptが指定されたキャッシュまたはアーティファクトパスで作成または変更するファイルはすべてキャプチャされ、アップロードされます。このタイミングは、次のようなシナリオに使用できます:
  • メインスクリプトの後にテストレポートまたはカバレッジデータを生成する。
  • サマリーファイルまたはログを作成する。
  • ビルド出力のポスト処理。

次の例では、含まれていないファイルは、アーティファクトまたはキャッシュのアップロードステージの後に作成または変更されたファイルのみです:

job:
  script:
    - echo "main" > output.txt
    - build_something

  after_script:
    - echo "modified in after_script" >> output.txt  # This WILL be in the artifact
    - generate_test_report > report.html            # This WILL be in the artifact

  artifacts:
    paths:
      - output.txt
      - report.html

  cache:
    paths:
      - output.txt  # Will include the "modified in after_script" line

詳細については、ジョブ実行フローを参照してください。

関連トピック:

• after_scriptをdefaultと組み合わせて使用すると、すべてのジョブの後に実行されるコマンドのデフォルト配列を定義できます。
• ジョブがキャンセルされた場合にafter_scriptコマンドをスキップするようにジョブを設定できます。
• ゼロ以外の終了コードを無視できます。
• after_scriptでカラーコードを使用すると、ジョブログのレビューが容易になります。
• カスタムの折りたたみ可能なセクションを作成して、ジョブログ出力をシンプルにできます。
• after_scriptのエラーを無視できます。

allow_failure

allow_failureを使用して、ジョブが失敗した場合にパイプラインの実行を継続するかどうかを決定します。

• パイプラインで後続のジョブを継続して実行させるには、allow_failure: trueを使用します。
• パイプラインで後続のジョブの実行を停止させるには、allow_failure: falseを使用します。

ジョブの失敗が許容されている場合（allow_failure: true）、オレンジ色の警告（ ）はジョブが失敗したことを示します。ただしパイプラインは成功し、関連するコミットは警告なしで成功としてマークされます。

このような警告は、次の場合に表示されます。

• ステージ内の他のすべてのジョブが成功した場合。
• パイプライン内の他のすべてのジョブが成功した場合。

allow_failureのデフォルト値は次のとおりです。

• 手動ジョブ: true。
• rules内でwhen: manualを使用しているジョブ: false。
• その他すべてのケース: false。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値:

• trueまたはfalse。

allow_failureの例:

job1:
  stage: test
  script:
    - execute_script_1

job2:
  stage: test
  script:
    - execute_script_2
  allow_failure: true

job3:
  stage: deploy
  script:
    - deploy_to_staging
  environment: staging

この例では、job1とjob2は並列実行されます。

• job1が失敗した場合、deployステージのジョブは開始されません。
• job2が失敗した場合、deployステージのジョブは開始できます。

補足情報:

• allow_failureをrulesのサブキーとして使用できます。
• allow_failure: trueが設定されている場合、そのジョブは常に成功と見なされます。そのため、そのジョブが失敗しても、when: on_failureが設定された後続のジョブは開始されません。
• 手動ジョブにallow_failure: falseを設定することで、ブロック手動ジョブを作成できます。ブロックされたパイプラインは、その手動ジョブが開始されて正常に完了するまで、後続ステージのジョブを実行しません。

allow_failure:exit_codes

allow_failure:exit_codesを使用して、ジョブの失敗を許容する条件を制御します。ジョブは、リストされた終了コードのいずれかの場合はallow_failure: true、それ以外の終了コードに対してはallow_failureがfalseとなります。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値:

• 1つの終了コード。
• 終了コードの配列。

allow_failureの例:

test_job_1:
  script:
    - echo "Run a script that results in exit code 1. This job fails."
    - exit 1
  allow_failure:
    exit_codes: 137

test_job_2:
  script:
    - echo "Run a script that results in exit code 137. This job is allowed to fail."
    - exit 137
  allow_failure:
    exit_codes:
      - 137
      - 255

artifacts

artifactsを使用して、ジョブアーティファクトとして保存するファイルを指定します。ジョブアーティファクトは、ジョブが成功した場合、失敗した場合、または常に、ジョブに添付されるファイルとディレクトリのリストです。

アーティファクトは、ジョブの完了後にGitLabに送信されます。サイズが最大アーティファクトサイズよりも小さい場合、GitLab UIでダウンロードできます。

デフォルトでは、後続ステージのジョブは、前のステージのジョブによって作成されたすべてのアーティファクトを自動的にダウンロードします。dependenciesを使用すると、ジョブにおけるアーティファクトのダウンロード動作を制御できます。

needsキーワードを使用している場合、ジョブはneeds設定で定義されたジョブからのみアーティファクトをダウンロードできます。

デフォルトでは、成功したジョブのジョブアーティファクトのみが収集されます。キャッシュが復元された後に、アーティファクトが復元されます。

ジョブの設定とデフォルト設定は一緒にマージされません。パイプラインにdefault:artifactsが定義されていて、ジョブにもartifactsがある場合、ジョブの設定が優先され、デフォルト設定は使用されません。

アーティファクトの詳細についてはこちらを参照してください。

artifacts:paths

パスはプロジェクトディレクトリ（$CI_PROJECT_DIR）を基準にした相対パスであり、プロジェクトディレクトリの外部に直接リンクすることはできません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• プロジェクトディレクトリを基準にしたファイルパスの配列。
• globパターンおよびdoublestar.Globパターンを使用するワイルドカードを使用できます。
• GitLab Pagesジョブの場合:
  • GitLab 17.10以降では、pages.publishパスは自動的にartifacts:pathsに付加されるため、再度指定する必要はありません。
  • GitLab 17.10以降では、pages.publishパスが指定されていない場合、publicディレクトリが自動的にartifacts:pathsに付加されます。

CI/CD変数がサポートされています。

artifacts:pathsの例:

job:
  artifacts:
    paths:
      - binaries/
      - .config

この例では、.configと、binariesディレクトリ内にあるすべてのファイルを含むアーティファクトを作成します。

補足情報:

• artifacts:nameと組み合わせて使用しない場合、アーティファクトファイルの名前はartifactsになり、ダウンロード時にartifacts.zipになります。

関連トピック:

• 特定のジョブがどのジョブからアーティファクトをフェッチするかを制限するには、dependenciesを参照してください。
• ジョブアーティファクトを作成する。

artifacts:exclude

artifacts:excludeを使用して、ファイルがアーティファクトアーカイブに追加されないようにします。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• プロジェクトディレクトリを基準にしたファイルパスの配列。
• globパターンまたはdoublestar.PathMatchパターンを使用するワイルドカードを使用できます。

artifacts:excludeの例:

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o

この例では、binaries/内のすべてのファイルが保存されますが、binaries/以下のサブディレクトリにある*.oファイルは保存されません。

補足情報:

• artifacts:excludeで指定されたパスは再帰的には検索されません。
• artifacts:untrackedで一致したファイルもartifacts:excludeを使用して除外できます。

関連トピック:

• ジョブアーティファクトからファイルを除外する。

artifacts:expire_in

expire_inを使用して、ジョブアーティファクトが期限切れになり削除されるまでに保存される期間を指定します。expire_inの設定は、以下には影響しません。

• 最新ジョブのアーティファクト（ただし、プロジェクトレベルまたはインスタンス全体で最新ジョブのアーティファクトの保持が無効になっている場合を除く）。

期限が切れたアーティファクトは、デフォルトでは毎時（cronジョブを使用して）削除され、アクセスできなくなります。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値: 有効期間。単位が指定されていない場合は秒単位です。有効な値の例は以下のとおりです。

• '42'
• 42 seconds
• 3 mins 4 sec
• 2 hrs 20 min
• 2h20min
• 6 mos 1 day
• 47 yrs 6 mos and 4d
• 3 weeks and 2 days
• never

artifacts:expire_inの例:

job:
  artifacts:
    expire_in: 1 week

補足情報:

• 有効期間は、アーティファクトがGitLabにアップロードされて保存された時点から始まります。有効期間が定義されていない場合は、インスタンス全体の設定がデフォルトで使用されます。
• 有効期間をオーバーライドし、アーティファクトが自動的に削除されないように保護するには、次のようにします。
  • ジョブページで維持を選択します。
  • expire_inの値をneverに設定します。
• 有効期間が短すぎると、長いパイプラインの後半のステージにあるジョブが、前半のジョブから期限切れのアーティファクトをフェッチしようとする可能性があります。アーティファクトが期限切れになっている場合、それらをフェッチしようとしたジョブはcould not retrieve the needed artifactsエラーで失敗します。有効期間を長く設定するか、後続のジョブでdependenciesを使用して、期限切れのアーティファクトをフェッチしないようにしてください。
• artifacts:expire_inは、GitLab Pagesのデプロイには影響しません。Pagesのデプロイの有効期間を設定するには、pages.expire_inを使用します。

artifacts:expose_as

artifacts:expose_asキーワードを使用して、マージリクエストUIでアーティファクトを公開します。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• マージリクエストUIに表示する、アーティファクトのダウンロードリンクの名前。artifacts:pathsと組み合わせて使用する必要があります。

artifacts:expose_asの例:

test:
  script: ["echo 'test' > file.txt"]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['file.txt']

補足情報:

• マージリクエストごとに最大10個のジョブで、expose_asをジョブごとに1回だけ使用できます。
• Globパターンはサポートされていません。
• アーティファクトは常にGitLabに送信されます。artifacts:paths値がない限り、UIに表示されます:
  • CI/CD変数を使用している。
  • ディレクトリを定義しているが、パスの末尾が/ではない。たとえば、artifacts:expose_asでdirectory/は機能しますが、directoryは機能しません。
• artifacts:pathsに単一のファイルのみが含まれている場合、リンクはそのファイルを直接開きます。それ以外の場合はすべて、リンクはアーティファクトブラウザーを開きます。
• リンクされたファイルはデフォルトでダウンロードされます。GitLab Pagesが有効になっている場合は、ブラウザで一部のアーティファクトのファイル拡張子を直接プレビューできます。詳細については、アーティファクトアーカイブの内容の参照を参照してください。

関連トピック:

• マージリクエストUIでジョブアーティファクトを公開する。

artifacts:name

artifacts:nameキーワードを使用して、作成されたアーティファクトアーカイブの名前を定義します。アーカイブごとに一意の名前を指定できます。

定義されていない場合、デフォルトの名前はartifactsであり、ダウンロード時にartifacts.zipになります。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• アーティファクトアーカイブの名前。CI/CD変数がサポートされています。artifacts:pathsと組み合わせて使用する必要があります。

artifacts:nameの例:

現在のジョブの名前でアーカイブを作成するには:

job:
  artifacts:
    name: "job1-artifacts-file"
    paths:
      - binaries/

関連トピック:

• CI/CD変数を使用してアーティファクト設定を定義する

artifacts:public

artifacts:publicを使用して、パブリックパイプライン内のジョブアーティファクトが匿名ユーザー、またはゲストロールとレポーターロールによってGitLab UIおよびAPIでダウンロードできるかどうかを制御します。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• true（デフォルト）: パブリックパイプラインのジョブのアーティファクトは、匿名ユーザー、またはゲストロールとレポーターロールを含む、誰でもダウンロードできます。
• false: ジョブ内のアーティファクトは、少なくともデベロッパーロールを持つユーザーのみがダウンロードできます。

artifacts:publicの例:

job:
  artifacts:
    public: false

artifacts:access

artifacts:accessを使用して、GitLab UIまたはAPIからジョブアーティファクトにアクセスできるユーザーを決定します。このオプションを使用しても、アーティファクトをダウンストリームパイプラインに転送できなくなることはありません。

同じジョブ内でartifacts:publicとartifacts:accessを併用することはできません。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値:

• all（デフォルト）: 公開パイプラインのジョブのアーティファクトは、匿名ユーザー、ゲストユーザー、レポーターユーザーなど誰でもダウンロードできます。
• developer: ジョブ内のアーティファクトは、少なくともデベロッパーロールを持つユーザーのみがダウンロードできます。
• maintainer: ジョブ内のアーティファクトは、少なくともメンテナーロールを持つユーザーのみがダウンロードできます。
• none: 誰もジョブのアーティファクトをダウンロードできません。

artifacts:accessの例:

job:
  artifacts:
    access: 'developer'

補足情報:

• artifacts:accessはすべてのartifacts:reportsにも影響するため、レポートのアーティファクトへのアクセスを制限することもできます。

artifacts:reports

artifacts:reportsを使用して、ジョブにインクルードされたテンプレートによって生成されたアーティファクトを収集します。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• 利用可能なアーティファクトレポートのタイプのリストを参照してください。

artifacts:reportsの例:

rspec:
  stage: test
  script:
    - bundle install
    - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml

補足情報:

• 子パイプラインからのアーティファクトを使用して、親パイプラインでレポートを組み合わせる操作はサポートされていません。サポートの追加については、このイシューで進捗を追跡できます。
• レポートの出力ファイルを参照してダウンロードできるようにするには、artifacts:pathsキーワードを含めます。これにより、アーティファクトのアップロードと保存が2回実行されます。
• artifacts: reportsのために作成されたアーティファクトは、ジョブの結果（成功または失敗）にかかわらず、常にアップロードされます。artifacts:expire_inを使用して、アーティファクトの有効期限を設定できます。

artifacts:untracked

artifacts:untrackedを使用して、（artifacts:pathsで定義されたパスとともに）すべての追跡していないGitファイルをアーティファクトとして追加します。artifacts:untrackedはリポジトリの.gitignoreの設定を無視するため、.gitignore内の一致するアーティファクトがインクルードされます。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• trueまたはfalse（定義されていない場合はデフォルト）。

artifacts:untrackedの例:

追跡していないGitファイルをすべて保存します。

job:
  artifacts:
    untracked: true

関連トピック:

• 追跡していないファイルをアーティファクトに追加する。

artifacts:when

artifacts:whenを使用して、ジョブの失敗時、または失敗にかかわらずアーティファクトをアップロードします。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• on_success（デフォルト）: ジョブが成功した場合にのみアーティファクトをアップロードします。
• on_failure: ジョブが失敗した場合にのみアーティファクトをアップロードします。
• always: 常にアーティファクトをアップロードします（ジョブがタイムアウトになった場合を除く）。たとえば、失敗したテストの問題解決に必要なアーティファクトをアップロードする場合などです。

artifacts:whenの例:

job:
  artifacts:
    when: on_failure

補足情報:

• artifacts:reportsで作成されたアーティファクトは、ジョブの結果（成功または失敗）に関係なく常にアップロードされます。artifacts:whenはこの動作を変更しません。

before_script

before_scriptを使用して、アーティファクトが復元された後、各ジョブのscriptコマンドの前に実行するコマンドの配列を定義します。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値: 次の内容を含む配列。

• 1行のコマンド。
• 複数行に分割された長いコマンド。
• YAMLアンカー。

CI/CD変数がサポートされています。

before_scriptの例:

job:
  before_script:
    - echo "Execute this command before any 'script:' commands."
  script:
    - echo "This command executes after the job's 'before_script' commands."

補足情報:

• before_scriptで指定したスクリプトが、メインのscriptで指定したスクリプトと連結されます。連結されたスクリプトは、1つのShellでまとめて実行されます。
• before_scriptをdefaultセクションではなくトップレベルで使用することは、非推奨です。

関連トピック:

• before_scriptをdefaultと組み合わせて使用すると、すべてのジョブでscriptコマンドの前に実行されるコマンドのデフォルトの配列を定義できます。
  • ジョブの設定とデフォルト設定は一緒にマージされません。パイプラインにdefault:before_scriptが定義されていて、ジョブにもbefore_scriptがある場合、ジョブの設定が優先され、デフォルト設定は使用されません。
• ゼロ以外の終了コードを無視できます。
• before_scriptでカラーコードを使用すると、ジョブログのレビューが容易になります。
• カスタムの折りたたみ可能なセクションを作成して、ジョブログ出力をシンプルにできます。

cache

cacheを使用して、ジョブ間でキャッシュするファイルとディレクトリのリストを指定します。ローカルの実行コピーにあるパスのみを使用できます。

キャッシュは次のようになります。

• パイプラインとジョブ間で共有されます。
• デフォルトでは、保護ブランチと保護されていないブランチの間では共有されません。
• アーティファクトの前に復元されます。
• 最大4つのキャッシュに制限されています。

特定のジョブのキャッシュを無効にできます。たとえば、以下をオーバーライドする場合です。

• defaultで定義されたデフォルトのキャッシュ。
• includeで追加されたジョブの設定。

ジョブの設定とデフォルト設定は一緒にマージされません。パイプラインにdefault:cacheが定義されていて、ジョブにもcacheがある場合、ジョブの設定が優先され、デフォルト設定は使用されません。

キャッシュの詳細については、GitLab CI/CDでのキャッシュを参照してください。

トップレベルでcacheを使用しても、defaultセクションでは使用しない場合、非推奨になります。

cache:paths

cache:pathsキーワードを使用して、キャッシュするファイルまたはディレクトリを選択します。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• プロジェクトディレクトリ（$CI_PROJECT_DIR）を基準にしたパスの配列。globパターンおよびdoublestar.Globパターンを使用するワイルドカードを使用できます。

CI/CD変数がサポートされています。

cache:pathsの例:

binariesにある.apkで終わるすべてのファイルと、.configファイルをキャッシュします。

rspec:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache
    paths:
      - binaries/*.apk
      - .config

補足情報:

• cache:pathsキーワードでは、追跡していないファイルや.gitignoreファイルに記載されているファイルもキャッシュの対象になります。

関連トピック:

• 詳細なcache:paths例については、CI/CDキャッシュの例を参照してください。

cache:key

cache:keyキーワードを使用して、各キャッシュに一意の識別キーを指定します。同じキャッシュキーを使用するすべてのジョブは、異なるパイプラインでも同じキャッシュを使用します。

設定されていない場合のデフォルトのキーはdefaultです。cacheキーワードを指定していてもcache:keyを指定していないジョブはすべて、defaultキャッシュを共有します。

cache: pathsと組み合わせて使用する必要があります。そうしないと、何もキャッシュされません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• 文字列。
• 定義済みCI/CD変数。
• 両方の組み合わせ。

cache:keyの例:

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache-$CI_COMMIT_REF_SLUG
    paths:
      - binaries/

補足情報:

• Windowsバッチを使用してShellスクリプトを実行する場合は、$を%に置き換える必要があります。例: key: %CI_COMMIT_REF_SLUG%

• cache:keyの値に次の文字を含めることはできません。

  • /、またはそのURIエンコード形式である%2F。
  • .のみ（任意の数）、またはそのURIエンコード形式である%2E。

• キャッシュはジョブ間で共有されるため、ジョブごとに異なるパスを使用している場合は、それぞれ異なるcache:keyも設定する必要があります。そうしないと、キャッシュの内容が上書きされる可能性があります。

関連トピック:

• 指定されたcache:keyが見つからない場合に使用するフォールバックキャッシュキーを指定できます。
• 1つのジョブで複数のキャッシュキーを使用できます。
• 詳細なcache:key例については、CI/CDキャッシュの例を参照してください。

cache:key:files

指定されたファイルの内容が変更されたときに、cache:key:filesを使用して新しいキャッシュキーを生成します。コンテンツが変更されない場合、キャッシュキーはブランチおよびパイプライン全体で一貫性を保ちます。キャッシュを再利用して再構築する頻度を減らすことができるため、後続のパイプラインの実行が高速化されます。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• 最大2つのファイルパスまたはパターンの配列。

CI/CD変数はサポートされていません。

cache:key:filesの例:

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
        - package.json
    paths:
      - vendor/ruby
      - node_modules

この例では、RubyとNode.jsの依存関係のキャッシュを作成します。キャッシュは、Gemfile.lockファイルとpackage.jsonファイルの現行バージョンに関連付けられています。これらのファイルのいずれかが変更されると、新しいキャッシュキーが計算され、新しいキャッシュが作成されます。後続のジョブの実行でcache:key:filesが使用され、同じGemfile.lockおよびpackage.jsonを参照している場合には、依存関係を再構築せずに新しいキャッシュが使用されます。

補足情報:

• キャッシュkeyは、リストされたファイルの内容から計算されたSHAです。ファイルが存在しない場合、キーの計算では無視されます。指定されたファイルが存在しない場合、フォールバックキーはdefaultです。
• **/package.jsonなどのワイルドカードパターンを使用できます。キャッシュキーに指定できるパスまたはパターンの数を増やすためのイシューが存在します。

cache:key:files_commits

指定されたファイルの最新のコミットが変更されたときに、cache:key:files_commitsを使用して新しいキャッシュキーを生成します。cache:key:files_commitsキャッシュキーは、ファイルの内容が同一のままであっても、指定されたファイルに新しいコミットがある場合は常に変更されます。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• 最大2つのファイルパスまたはパターンの配列。

cache:key:files_commitsの例:

cache-job:
  script:
    - echo "This job uses a commit-based cache."
  cache:
    key:
      files_commits:
        - package.json
        - yarn.lock
    paths:
      - node_modules

この例では、package.jsonとyarn.lockのコミット履歴に基づいてキャッシュを作成します。これらのファイルのコミット履歴が変更された場合、新しいキャッシュキーが計算され、新しいキャッシュが作成されます。

補足情報:

• キャッシュkeyは、指定されたファイルごとに最新のコミットから計算されたSHAです。
• ファイルが存在しない場合、キーの計算では無視されます。
• 指定されたファイルが存在しない場合、フォールバックキーはdefaultです。
• 同じキャッシュ構成でcache:key:filesと一緒に使用することはできません。

cache:key:prefix

cache:key:prefixを使用して、cache:key:filesで計算されたSHAとプレフィックスを組み合わせます。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• 文字列。
• 定義済みCI/CD変数。
• 両方の組み合わせ。

cache:key:prefixの例:

rspec:
  script:
    - echo "This rspec job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
      prefix: $CI_JOB_NAME
    paths:
      - vendor/ruby

たとえば$CI_JOB_NAMEというprefixを追加すると、キーはrspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5のようになります。ブランチでGemfile.lockが変更されると、そのブランチにはcache:key:filesに対する新しいSHAチェックサムが設定されます。これにより、新しいキャッシュキーが生成され、そのキーに対する新しいキャッシュが作成されます。Gemfile.lockが見つからない場合、defaultにプレフィックスが追加されます。この例では、キーはrspec-defaultになります。

補足情報:

• cache:key:filesに指定されたファイルがコミットで変更されていない場合は、defaultキーにプレフィックスが追加されます。

cache:untracked

untracked: trueを使用して、Gitリポジトリで追跡していないすべてのファイルをキャッシュします。追跡していないファイルには、次のファイルが含まれます。

• .gitignore設定が原因で無視されているファイル。
• 作成されたが、git addでステージングされていないファイル。

追跡していないファイルをキャッシュすると、ジョブが次のようなものをダウンロードした際に、予期せず大きなキャッシュが作成される可能性があります。

• 通常は追跡されない依存関係（gemやノードモジュールなど）。
• 別のジョブからのアーティファクト。デフォルトでは、アーティファクトから抽出されたファイルは追跡されません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• trueまたはfalse（デフォルト）。

cache:untrackedの例:

rspec:
  script: test
  cache:
    untracked: true

補足情報:

• cache:untrackedとcache:pathsを組み合わせて指定すると、追跡していないすべてのファイルと、設定されたパス内のファイルをキャッシュできます。cache:pathsは、追跡したファイルや作業ディレクトリの外部にあるファイルを含む、特定のファイルをキャッシュするために使用します。cache: untrackedを使用することで、追跡していないファイルもすべてキャッシュすることができます。例:

  rspec:
    script: test
    cache:
      untracked: true
      paths:
        - binaries/

  この例では、ジョブはリポジトリ内の追跡していないすべてのファイルと、binaries/内のすべてのファイルをキャッシュします。binaries/内に追跡していないファイルがある場合、それらはこの両方のキーワードでカバーされます。

cache:unprotect

cache:unprotectを使用して、保護ブランチと保護されていないブランチの間でキャッシュが共有されるように設定します。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• trueまたはfalse（デフォルト）。

cache:unprotectの例:

rspec:
  script: test
  cache:
    unprotect: true

cache:when

cache:whenを使用して、ジョブのステータスに基づいてキャッシュを保存するタイミングを定義します。

cache: pathsと組み合わせて使用する必要があります。そうしないと、何もキャッシュされません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• on_success（デフォルト）: ジョブが成功した場合にのみキャッシュを保存します。
• on_failure: ジョブが失敗した場合にのみキャッシュを保存します。
• always: キャッシュを常に保存します。

cache:whenの例:

rspec:
  script: rspec
  cache:
    paths:
      - rspec/
    when: 'always'

この例では、ジョブの成功または失敗にかかわらずキャッシュを保存します。

cache:policy

キャッシュのアップロードとダウンロードの動作を変更するには、cache:policyキーワードを使用します。デフォルトでは、ジョブはジョブの開始時にキャッシュをダウンロードし、ジョブの終了時に変更をキャッシュにアップロードします。このキャッシュスタイルはpull-pushポリシー（デフォルト）です。

ジョブの開始時にキャッシュをダウンロードするだけで、ジョブの終了時に変更をアップロードしないようにジョブを設定するには、cache:policy:pullを使用します。

ジョブの終了時にキャッシュをアップロードするだけで、ジョブの開始時にキャッシュをダウンロードしないようにジョブを設定するには、cache:policy:pushを使用します。

同じキャッシュを使用する多数のジョブが並列実行される場合は、pullポリシーを使用します。このポリシーにより、ジョブの実行が高速化され、キャッシュサーバーの負荷も軽減されます。キャッシュを構築するために、pushポリシーを指定したジョブを使用できます。

cache: pathsと組み合わせて使用する必要があります。そうしないと、何もキャッシュされません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• pull
• push
• pull-push（デフォルト）
• CI/CD変数。

cache:policyの例:

prepare-dependencies-job:
  stage: build
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: push
  script:
    - echo "This job only downloads dependencies and builds the cache."
    - echo "Downloading dependencies..."

faster-test-job:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - echo "This job script uses the cache, but does not update it."
    - echo "Running tests..."

関連トピック:

• 変数を使用して、ジョブのキャッシュポリシーを制御できます。

cache:fallback_keys

cache:fallback_keysを使用して、cache:keyに対応するキャッシュが見つからない場合に、キャッシュの復元を試行するキーのリストを指定します。キャッシュは、fallback_keysセクションで指定された順序で取得されます。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• キャッシュキーの配列

cache:fallback_keysの例:

rspec:
  script: rspec
  cache:
    key: gems-$CI_COMMIT_REF_SLUG
    paths:
      - rspec/
    fallback_keys:
      - gems
    when: 'always'

coverage

coverageとカスタム正規表現を使用して、ジョブの出力からコードカバレッジを抽出する方法を設定します。ジョブの出力に、正規表現と一致する行が1行以上含まれている場合、カバレッジがUIに表示されます。

一致した文字列からコードカバレッジの値を抽出するために、GitLabは短い正規表現\d+(?:\.\d+)?を使用します。

サポートされている値:

• RE2正規表現。冒頭と末尾の両方が/である必要があります。カバレッジの数値と一致する必要があります。周囲のテキストも含めて一致しても問題ありません。そのため、正確な数値をキャプチャするために正規表現の文字グループを使用する必要はありません。RE2構文を使用するため、すべてグループは非キャプチャグループでなければなりません。

coverageの例:

job1:
  script: rspec
  coverage: '/Code coverage: \d+(?:\.\d+)?/'

この例では:

1. GitLabが、ジョブログに対して正規表現が一致するかどうかをチェックします。Code coverage: 67.89% of lines coveredのような行が一致します。
2. GitLabは、一致した部分をチェックして、正規表現\d+(?:\.\d+)?と一致する箇所を見つけます。この例の正規表現は、コードカバレッジの値67.89に一致します。

補足情報:

• 正規表現の例はコードカバレッジに記載されています。
• ジョブの出力に一致する行が複数ある場合は、最後の行が使用されます（逆方向検索で最初に一致した結果）。
• 1行内に一致した箇所が複数ある場合は、最後に一致した部分からカバレッジの数値が抽出されます。
• 一致した部分から複数のカバレッジの数値が見つかった場合は、最初の数値が使用されます。
• 先頭のゼロは削除されます。
• 子パイプラインからのカバレッジ出力は、記録または表示されません。詳細については、関連イシューを確認してください。

dast_configuration

dast_configurationキーワードを使用して、CI/CD設定で使用するサイトプロファイルとスキャナープロファイルを指定します。両方のプロファイルが、あらかじめプロジェクトで作成されている必要があります。ジョブのステージはdastである必要があります。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値: site_profileとscanner_profile（それぞれ1つずつ）。

• ジョブで使用するサイトプロファイルを指定するには、site_profileを使用します。
• ジョブで使用するスキャナープロファイルを指定するには、scanner_profileを使用します。

dast_configurationの例:

stages:
  - build
  - dast

include:
  - template: DAST.gitlab-ci.yml

dast:
  dast_configuration:
    site_profile: "Example Co"
    scanner_profile: "Quick Passive Test"

この例では、dastジョブが、includeキーワードで追加されたdast設定を拡張し、特定のサイトプロファイルおよびスキャナープロファイルを選択しています。

補足情報:

• サイトプロファイルまたはスキャナープロファイルに含まれる設定は、DASTテンプレートに含まれる設定よりも優先されます。

関連トピック:

• サイトプロファイル。
• スキャナープロファイル。

dependencies

dependenciesキーワードを使用して、アーティファクトのフェッチ元のジョブのリストを定義します。指定されたジョブはすべて、先行するステージに存在する必要があります。アーティファクトをまったくダウンロードしないようにジョブを設定することもできます。

ジョブでdependenciesが定義されていない場合、前のステージにあるすべてのジョブが依存対象と見なされ、ジョブはそれらのジョブからすべてのアーティファクトをフェッチします。

同じステージ内のジョブからアーティファクトをフェッチするには、needs:artifactsを使用する必要があります。同じジョブの中でdependenciesをneedsと組み合わせて使用しないでください。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値:

• アーティファクトのフェッチ元のジョブの名前。
• 空の配列（[]）。アーティファクトをダウンロードしないようにジョブを設定します。

dependenciesの例:

build osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
      - binaries/

build linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/

test osx:
  stage: test
  script: make test:osx
  dependencies:
    - build osx

test linux:
  stage: test
  script: make test:linux
  dependencies:
    - build linux

deploy:
  stage: deploy
  script: make deploy
  environment: production

この例では、build osxとbuild linuxの2つのジョブがアーティファクトを生成します。test osxが実行されると、build osxからのアーティファクトがダウンロードされ、ビルドのコンテキストで抽出されます。test linuxも同様に、build linuxからのアーティファクトを取得します。

deployジョブは、ステージの優先順位に従って、それ以前のすべてのジョブからアーティファクトをダウンロードします。

補足情報:

• ジョブステータスは関係ありません。ジョブが失敗した場合、またはトリガーされていない手動ジョブである場合、エラーは発生しません。
• 依存先のジョブのアーティファクトが期限切れであるか削除されている場合、ジョブは失敗します。

environment

environmentを使用して、ジョブがデプロイされる環境を定義します。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値: ジョブのデプロイ先の環境の名前。次のいずれかの形式で指定します。

• 平文（英字、数字、スペース、および文字-、_、/、$、{、}を含む）。
• CI/CD変数（定義済みの変数、プロジェクト、グループ、インスタンスの変数、または.gitlab-ci.ymlファイルで定義された変数を含む）。scriptセクションで定義された変数は使用できません。

environmentの例:

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment: production

補足情報:

• environmentを指定しても、その名前の環境が存在しない場合は、環境が作成されます。

environment:name

環境の名前を設定します。

一般的な環境名はqa、staging、productionですが、任意の名前を使用できます。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値: ジョブのデプロイ先の環境の名前。次のいずれかの形式で指定します。

• 平文（英字、数字、スペース、および文字-、_、/、$、{、}を含む）。
• CI/CD変数（定義済みの変数、プロジェクト、グループ、インスタンスの変数、または.gitlab-ci.ymlファイルで定義された変数を含む）。scriptセクションで定義された変数は使用できません。

environment:nameの例:

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production

environment:url

環境のURLを設定します。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値: 単一のURL。次のいずれかの形式で指定します。

• 平文（例: https://prod.example.com）。
• CI/CD変数（定義済みの変数、プロジェクト、グループ、インスタンスの変数、または.gitlab-ci.ymlファイルで定義された変数を含む）。scriptセクションで定義された変数は使用できません。

environment:urlの例:

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production
    url: https://prod.example.com

補足情報:

• ジョブが完了したら、URLにアクセスできます。URLにアクセスするには、マージリクエスト、環境、またはデプロイページでボタンを選択します。

environment:on_stop

environmentで定義されているon_stopキーワードを使用して、環境を閉じる（停止する）ことができます。これは、環境を閉じるために実行される別のジョブを宣言します。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

補足情報:

• 詳細と例については、environment:actionを参照してください。

environment:action

actionキーワードを使用して、ジョブが環境をどのように操作するかを指定します。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値: 次のキーワードのいずれか。

environment:actionの例:

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

environment:auto_stop_in

auto_stop_inキーワードは、環境のライフタイムを指定します。環境の有効期限が切れると、GitLabは自動的にその環境を停止します。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値: 自然言語で記述された期間。たとえば、以下の表記はすべて同等です。

• 168 hours
• 7 days
• one week
• never

CI/CD変数がサポートされています。

environment:auto_stop_inの例:

review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    auto_stop_in: 1 day

review_appの環境が作成されると、その環境のライフタイムは1 dayに設定されます。レビューアプリがデプロイされるたびに、そのライフタイムも1 dayにリセットされます。

auto_stop_inキーワードは、stopを除くすべての環境アクションに使用できます。一部のアクションは、環境のスケジュールされた停止時間をリセットするために使用できます。詳細については、準備または検証目的で環境にアクセスするを参照してください。

関連トピック:

• 環境の自動停止に関するドキュメント。

environment:kubernetes

kubernetesキーワードを使用して、環境のKubernetesのダッシュボードとGitLabで管理されるKubernetesリソースを構成します。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値:

• agent: Kubernetes向けGitLabエージェントを指定する文字列。形式はpath/to/agent/project:agent-nameです。エージェントがパイプラインを実行しているプロジェクトに接続されている場合は、$CI_PROJECT_PATH:agent-nameを使用します。
• dashboard:namespace: 環境がデプロイされるKubernetesネームスペースを表す文字列。ネームスペースは、agentキーワードと一緒に設定する必要があります。namespaceは非推奨です。
• dashboard:flux_resource_path: HelmReleaseなどの、Fluxリソースへのフルパスを表す文字列。Fluxリソースは、agentキーワード、dashboard:namespaceキーワードと一緒に設定する必要があります。flux_resource_pathは非推奨です。
• managed_resources: 環境のGitLabで管理されるKubernetesリソースを構成するためのenabledキーワードを使用したハッシュ。
  • managed_resources:enabled: GitLabで管理されるKubernetesリソースが環境で有効になっているかどうかを示すブール値。
• dashboard: 環境のKubernetesのダッシュボードを構成するためのdashboard:namespaceキーワードとdashboard:flux_resource_pathキーワードを使用したハッシュ。

environment:kubernetesの例:

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      agent: path/to/agent/project:agent-name
      dashboard:
        namespace: my-namespace
        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

管理対象リソースを無効にする場合のExample of:

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      agent: path/to/agent/project:agent-name
      managed_resources:
        enabled: false
      dashboard:
        namespace: my-namespace
        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

この設定では:

• deployジョブをセットアップして、production環境にデプロイします。
• エージェントという名前のagent-nameを環境に関連付けます。
• ネームスペースがmy-namespaceに設定され、flux_resource_pathにhelm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resourceが指定された環境向けに、Kubernetesのダッシュボードを設定します。

補足情報:

• ダッシュボードを使用するには、Kubernetes向けGitLabエージェントをインストールし、環境のプロジェクトまたはその親グループのuser_accessを設定する必要があります。
• ジョブを実行するユーザーには、クラスターエージェントへのアクセス権限が必要です。権限がない場合、ダッシュボードはagent、namespace、flux_resource_path属性を無視します。
• agentのみを設定する場合は、namespaceを設定する必要はなく、flux_resource_pathを設定することはできません。ただし、この設定では、Kubernetesのダッシュボードにクラスター内のすべてのネームスペースが一覧表示されます。

environment:deployment_tier

deployment_tierキーワードを使用して、デプロイメント環境のプランを指定します。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値: 次のいずれか。

• production
• staging
• testing
• development
• other
• CI/CD変数（定義済みの変数、プロジェクト、グループ、インスタンスの変数、または.gitlab-ci.ymlファイルで定義された変数を含む）。scriptセクションで定義された変数は使用できません。

environment:deployment_tierの例:

deploy:
  script: echo
  environment:
    name: customer-portal
    deployment_tier: production

補足情報:

• このジョブ定義から作成された環境には、この値に基づいてプランが割り当てられます。
• この値が後で追加された場合、既存の環境のプランは更新されません。既存の環境のプランを更新するには、Environments APIを使用する必要があります。

関連トピック:

• 環境のデプロイプラン。

動的環境

CI/CD変数を使用して、環境名を動的に指定します。

例:

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

deploy as review appジョブは、review/$CI_COMMIT_REF_SLUG環境を動的に作成するためのデプロイとしてマークされます。$CI_COMMIT_REF_SLUGは、Runnerによって設定されるCI/CD変数です。$CI_ENVIRONMENT_SLUG変数は環境名に基づいていますが、URLに含めるのに適しています。powというブランチでdeploy as review appジョブが実行される場合、この環境はhttps://review-pow.example.com/のようなURLでアクセスできるようになります。

一般的なユースケースは、ブランチの動的環境を作成し、それらをレビューアプリとして使用することです。レビューアプリの使用例は、https://gitlab.com/gitlab-examples/review-apps-nginx/で確認できます。

extends

extendsを使用して、設定セクションを再利用します。これはYAMLアンカーの代替手段であり、わずかに柔軟性が高く、読みやすくなっています。

キーワードのタイプ: ジョブキーワード。ジョブの一部としてのみ使用できます。

サポートされている値:

• パイプライン内の別のジョブの名前。
• パイプライン内の他のジョブの名前のリスト（配列）。

extendsの例:

.tests:
  stage: test
  image: ruby:3.0

rspec:
  extends: .tests
  script: rake rspec

rubocop:
  extends: .tests
  script: bundle exec rubocop

この例では、rspecジョブが.testsテンプレートジョブの設定を使用します。パイプラインの作成時に、GitLabは次の処理を行います。

• キーに基づいて逆ディープマージを実行します。
• .testsの内容をrspecジョブとマージします。
• キーの値はマージしません。

結合された設定は、以下のジョブと同等です。

rspec:
  stage: test
  image: ruby:3.0
  script: rake rspec

rubocop:
  stage: test
  image: ruby:3.0
  script: bundle exec rubocop

補足情報:

• extendsには複数の親を使用できます。
• extendsキーワードは最大11レベルの継承をサポートしていますが、4レベル以上を使用することは避けてください。
• 前述の例では、.testsは非表示ジョブですが、通常のジョブから設定を拡張することもできます。

関連トピック:

• extendsを使用して設定セクションを再利用する。
• extendsを使用して、インクルードされた設定ファイルの設定を再利用する。

hooks

hooksを使用して、ジョブ実行の特定のステージ（Gitリポジトリを取得する前など）で、Runnerで実行するコマンドのリストを指定します。

ジョブの設定とデフォルト設定は一緒にマージされません。パイプラインにdefault:hooksが定義されていて、ジョブにもhooksがある場合、ジョブの設定が優先され、デフォルト設定は使用されません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• フックとそのコマンドのハッシュ。利用可能なフック: pre_get_sources_script。

hooks:pre_get_sources_script

hooks:pre_get_sources_scriptを使用して、Gitリポジトリとサブモジュールをクローンする前にRunnerで実行するコマンドのリストを指定します。たとえば、次のような用途に使用できます。

• Git設定を調整する。
• トレーシング変数をエクスポートする。

サポートされている値: 次の内容を含む配列。

• 1行のコマンド。
• 複数行に分割された長いコマンド。
• YAMLアンカー。

CI/CD変数がサポートされています。

hooks:pre_get_sources_scriptの例:

job1:
  hooks:
    pre_get_sources_script:
      - echo 'hello job1 pre_get_sources_script'
  script: echo 'hello job1 script'

関連トピック:

• GitLab Runnerの設定

identity

この機能はベータ版です。

identityを使用して、アイデンティティフェデレーションを使用したサードパーティサービスの認証を行います。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefault:セクションでのみ使用できます。

サポートされている値: 識別子。サポートされているプロバイダーは以下のとおりです。

• google_cloud: Google Cloud。Google Cloud IAMインテグレーションを使用して設定する必要があります。

identityの例:

job_with_workload_identity:
  identity: google_cloud
  script:
    - gcloud compute instances list

関連トピック:

• Workload Identity連携。
• Google Cloud IAMインテグレーション。

id_tokens

id_tokensを使用して、サードパーティサービスで認証するためのIDトークンを作成します。この方法で作成されたすべてのJSON Webトークンは、OIDC認証をサポートしています。JSON Webトークンのaudクレームを設定するために、必須のサブキーワードaudを使用します。

ジョブの設定とデフォルト設定は一緒にマージされません。パイプラインにdefault:id_tokensが定義されていて、ジョブにもid_tokensがある場合、ジョブの設定が優先され、デフォルト設定は使用されません。

サポートされている値:

• トークン名と、そのaudクレーム。audでは以下がサポートされています。
  • 単一の文字列。
  • 文字列の配列。
  • CI/CD変数。

id_tokensの例:

job_with_id_tokens:
  id_tokens:
    ID_TOKEN_1:
      aud: https://vault.example.com
    ID_TOKEN_2:
      aud:
        - https://gcp.com
        - https://aws.com
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - command_to_authenticate_with_vault $ID_TOKEN_1
    - command_to_authenticate_with_aws $ID_TOKEN_2
    - command_to_authenticate_with_gcp $ID_TOKEN_2

関連トピック:

• IDトークン認証。
• クラウドサービスに接続する。
• キーレス署名にSigstoreを使用する。

image

imageを使用して、ジョブが実行されるDockerイメージを指定します。

ジョブの設定とデフォルト設定は一緒にマージされません。パイプラインにdefault:imageが定義されていて、ジョブにもimageがある場合、ジョブの設定が優先され、デフォルト設定は使用されません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値: イメージ名（必要に応じてレジストリパスを含む）。次のいずれかの形式で指定します。

• <image-name>（<image-name>にlatestタグを付けた場合と同じ）
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD変数がサポートされています。

imageの例:

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: registry.example.com/my-group/my-project/ruby:2.7
  script: bundle exec rspec

この例では、ruby:3.0イメージがパイプライン内のすべてのジョブに対するデフォルトです。rspec 2.7ジョブは、ジョブ固有のimageセクションでデフォルトをオーバーライドするため、デフォルトを使用しません。

補足情報:

• トップレベルでimageを使用しても、defaultセクションでは使用しない場合、非推奨になります。

関連トピック:

• DockerコンテナでCI/CDジョブを実行する。

image:name

ジョブが実行されるDockerイメージの名前。imageを単独で使用した場合と同様に機能します。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値: イメージ名（必要に応じてレジストリパスを含む）。次のいずれかの形式で指定します。

• <image-name>（<image-name>にlatestタグを付けた場合と同じ）
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD変数がサポートされています。

image:nameの例:

test-job:
  image:
    name: "registry.example.com/my/image:latest"
  script: echo "Hello world"

関連トピック:

• DockerコンテナでCI/CDジョブを実行する。

image:entrypoint

コンテナのエントリポイントとして実行するコマンドまたはスクリプト。

Dockerコンテナの作成時に、entrypointはDockerの--entrypointオプションに変換されます。構文はDockerfileのENTRYPOINTディレクティブに似ており、各Shellトークンは配列内の個別の文字列です。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• 文字列。

image:entrypointの例:

test-job:
  image:
    name: super/sql:experimental
    entrypoint: [""]
  script: echo "Hello world"

関連トピック:

• イメージのエントリポイントをオーバーライドする。

image:docker

image:dockerを使用して、DockerエグゼキュータまたはKubernetesエグゼキュータを使用するRunnerにオプションを渡します。このキーワードは、他のexecutorタイプでは機能しません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

Docker executorのオプションを定義するハッシュ。以下を含めることができます。

• platform: プルするイメージのアーキテクチャを選択します。指定しない場合、デフォルトはホストRunnerと同じプラットフォームです。
• user: コンテナの実行時に使用するユーザー名またはUIDを指定します。

image:dockerの例:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    docker:
      platform: arm64/v8
      user: dave

補足情報:

• image:docker:platformは、docker pull --platformオプションにマップされます。
• image:docker:userは、docker run --userオプションにマップされます。

image:kubernetes

image:kubernetesを使用して、GitLab Runner Kubernetes executorにオプションを渡します。このキーワードは、他のexecutorタイプでは機能しません。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

Kubernetes executorのオプションを定義するハッシュ。以下を含めることができます。

• user: コンテナの実行時に使用するユーザー名またはUIDを指定します。UID:GID形式を使用して、GIDを設定することもできます。

UIDのみを使用したimage:kubernetesの例:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001"

UIDとGIDの両方を使用したimage:kubernetesの例:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001:1001"

image:pull_policy

RunnerがDockerイメージをフェッチするために使用するプルポリシー。

キーワードのタイプ: ジョブキーワード。ジョブの一部として、またはdefaultセクションでのみ使用できます。

サポートされている値:

• 1つのプルポリシー、または配列で指定する複数のプルポリシー。always、if-not-present、neverのいずれかを指定できます。

image:pull_policyの例:

job1:
  script: echo "A single pull policy."
  image:
    name: ruby:3.0
    pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  image:
    name: ruby:3.0
    pull_policy: [always, if-not-present]