.gitlab-ci.yml キーワードリファレンス

このドキュメントは、GitLab.gitlab-ci.yml ファイルの設定オプションを示します。

  • GitLab CI/CDの簡単な紹介は、クイックスタートガイドに従ってください。
  • サンプル集については、GitLab CI/CDの使用例を参照してください。
  • 企業で使われている大きな.gitlab-ci.yml ファイルを見るには、gitlab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab-ci.yml)の[.gitlab-ci.yml ファイルをご覧ください。

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

このページの内容を編集する場合は、キーワードの文書化の指示に従ってください。

キーワード

GitLab CI/CDパイプライン設定には以下が含まれます：

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

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

  • ジョブキーワードによるジョブ設定：

    キーワード説明
    after_scriptジョブの後に実行されるコマンドを上書きします。
    allow_failureジョブの失敗を許可します。ジョブが失敗してもパイプラインは失敗しません。
    artifacts成功した場合にジョブに添付するファイルとディレクトリのリストです。
    before_scriptジョブの前に実行されるコマンドを上書きします。
    cache後続の処理でキャッシュされるべきファイルのリストです。。
    coverageジョブのコードカバレッジを設定します。
    dast_configurationジョブレベルでDASTプロファイルの設定を使用します。
    dependenciesアーティファクトを取得するジョブのリストを与えることで、アーティファクトが渡されるジョブを制限します。
    environmentジョブをデプロイする環境の名前です。
    exceptジョブが作成されない場合の制御。
    extendsこのジョブが継承する設定エントリ。
    imageDockerイメージを使用します。
    inheritすべてのジョブが継承するグローバルデフォルトを選択します。
    interruptible新しいジョブによって、冗長なジョブをキャンセルできるかどうかを定義します。
    needsステージ順序よりも前のジョブを実行します。
    onlyジョブが作成されるタイミングを制御します。
    pagesGitLab Pagesで使用するために、ジョブの結果をアップロードします。
    parallelジョブを並列に実行するインスタンス数を定義します。
    releaseRunnerにリリースオブジェクトを生成するように指示します。
    resource_groupジョブの同時実行を制限します。
    retryジョブが失敗した場合に、ジョブをいつ、何回自動リトライするかを設定します。
    rulesジョブを作成する、または作成しないかどうかを判断するために評価する条件の一覧です。
    scriptRunnerによって実行されるShellスクリプト。
    secretsジョブが必要とするCI/CDシークレット。
    servicesDockerサービスのイメージを使用します。
    stageジョブステージを定義します。
    tagsランナーの選択に使用されるタグのリスト。
    timeoutプロジェクト全体の設定よりも優先される、ジョブレベルのタイムアウトを定義します。
    triggerダウンストリームのパイプライントリガーを定義します。
    variablesジョブレベルでジョブ変数を定義します。
    whenいつジョブを実行するかを決めます。

グローバルキーワード

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

default

いくつかのキーワードにはグローバルデフォルトを設定できます。リストされたキーワードの1つ以上が定義されていないジョブでは、default セクションで定義された値が使用されます。

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

可能な入力：これらのキーワードはカスタム・デフォルトを持つことができます：

default の例：

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

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

image この例では、ruby:3.0 はパイプラインのすべてのジョブのデフォルト値です。rspec 2.7 ジョブはデフォルトを使用しません。なぜなら、ジョブ固有のimage セクションでデフォルトを上書きするからです：

その他の詳細：

  • パイプラインが作成されると、各デフォルトは、そのキーワードが定義されていないすべてのジョブにコピーされます。
  • ジョブが既にキーワードの1つを設定している場合、ジョブ内の設定が優先され、デフォルトに置き換えられません。
  • inherit:default を用いて、ジョブ内のデフォルトキーワードの継承を制御してください。

include

11.4でGitLab Freeに移動しました。

include を使って、CI/CD 設定に外部の YAML ファイルをインクルードします。1つの長い.gitlab-ci.yml ファイルを複数のファイルに分割して可読性を高めたり、同じ設定の重複を複数の場所で減らしたりできます。

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

include ファイルは以下のとおりです：

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

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

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

可能な入力：include のサブキー：

その他の詳細：

  • include キーワードで使用できるCI/CD 変数は限られています。
  • CI/CDに含まれる設定をカスタマイズして上書きするには、マージを使ってローカルの
  • .gitlab-ci.yml ファイルに .gitlab-ci.yml同じジョブ名またはグローバルキーワードを持つことで、インクルードされた設定を上書きできます。.gitlab-ci.yml 2つの設定はマージさ .gitlab-ci.ymlれ、ファイル.gitlab-ci.yml 内の .gitlab-ci.yml設定はインクルードされた設定よりも優先されます。
  • を再実行した場合：
    • ジョブを再実行する場合、include ファイルは再度取得されません。パイプライン内のすべてのジョブは、パイプラインの作成時にフェッチされた設定を使用します。ソースinclude ファイルに変更があっても、ジョブの再実行には影響しません。
    • パイプラインでは、include ファイルが再度フェッチされます。最後のパイプライン実行後に変更された場合、新しいパイプラインは変更された設定を使用します。
  • デフォルトでは、ネストされたものを含め、パイプラインごとに最大150個のインクルードが可能です。さらに
    • GitLab 16.0以降のセルフマネージドユーザーは、インクルードファイルの最大値を変更することができます。
    • GitLab 15.10以降では、150個までincludeできます。ネストされたインクルードでは、同じファイルを複数回インクルードすることができますが、重複したインクルードは上限にカウントされます。
    • GitLab 14.9からGitLab 15.9では、100個までインクルードできます。ネストされたインクルードでは同じファイルを複数回インクルードできますが、重複は無視されます。
    • GitLab 14.9以前では100個までインクルードできますが、同じファイルを複数回インクルードすることはできません。

関連トピック：

include:local

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

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

可能な入力：

ルートディレクトリ (/) からの相対フルパス：

include:local の例：

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

より短い構文を使ってパスを定義することもできます：

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

その他の詳細 ：

  • .gitlab-ci.yml ファイルと内部ファイルは同じブランチになければなりません。
  • Git サブモジュールのパスを通してローカルファイルをインクルードすることはできません。
  • ネストされたインクルードはすべて、パイプラインを実行しているプロジェクトではなく、include キーワードを指定した設定ファイルを含むプロジェクトのスコープで実行されます。ローカルインクルード、プロジェクトインクルード、リモートインクルード、テンプレートインクルードが使えます。

include:project

GitLab 13.6で導入された、同じプロジェクトからの複数ファイルのインクルード。GitLab 13.8で機能フラグが削除されました。

同じGitLabインスタンスにある別の非公開プロジェクトのファイルをインクルードするには、include:project とinclude:file.

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

可能な入力：

  • include:project:GitLab プロジェクトのフルパス。
  • include:file ルートディレクトリ (/) からの相対パス。YAMLファイルの拡張子は.yml または.yaml でなければなりません。
  • include: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 キーワードを持つ設定ファイルを含むプロジェクトのスコープ内で実行されます。local （include キーワードを持つ設定ファイルを含むプロジェクトからの相対）、project、remote、またはtemplate インクルードを使用できます。
  • パイプラインが開始すると、.gitlab-ci.yml すべてのメソッドでインクルードされたファイル設定が評価さ .gitlab-ci.ymlれます。.gitlab-ci.yml 設定は時間のスナップショットであり、データベースに永続します。GitLabは .gitlab-ci.yml、次のパイプラインが開始するまで、.gitlab-ci.yml 参照された .gitlab-ci.ymlファイル.gitlab-ci.yml 設定への変更を反映 .gitlab-ci.ymlしません。
  • 別の非公開プロジェクトの YAML ファイルをインクルードする場合、パイプラインを実行するユーザーは両方のプロジェクトのメンバーであり、パイプラインを実行する適切な権限を持っている必要があります。ユーザーがインクルードされたファイルへのアクセス権を持っていない場合、not found or access denied エラーが表示されることがあります。
  • 別のプロジェクトの CI/CD 設定ファイルをインクルードする場合は注意してください。CI/CD設定ファイルが変更されても、パイプラインや通知はトリガーされません。セキュリティの観点からは、これはサードパーティの依存関係を引き出すのと似ています。ref について考えてみましょう：
    • 特定のSHAハッシュを使うこと。
    • 他のプロジェクトのref に、保護ブランチと 保護タグの両方のルールを適用します。保護されたタグとブランチは、変更する前に変更管理を通過する可能性が高くなります。

include:remote

include:remote に完全な URL を指定して、別の場所のファイルをインクルードします。

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

可能な入力：

HTTP/HTTPSGET リクエストでアクセス可能な公開 URL：

  • リモート URL での認証はサポートされていません。
  • YAML ファイルの拡張子は.yml もしくは.yaml です。
  • 特定のCI/CD変数を使うことができます。

include:remote の例：

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

その他の詳細 ：

  • すべてのネストされたインクルードは、公開ユーザーとしてコンテキストなしで実行されるため、公開プロジェクトまたはテンプレートのみをインクルードできます。ネストされたインクルードのinclude セクションでは変数は使用できません。
  • 他のプロジェクトの CI/CD 設定ファイルをインクルードするときは注意してください。他のプロジェクトのファイルが変更されても、パイプラインや通知はトリガーされません。セキュリティの観点から言えば、これはサードパーティの依存関係を引っ張ってくるのと同じです。あなたが所有する他の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 セクションでは変数は使用できません。

stages

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

stages が.gitlab-ci.yml ファイルで定義されていない場合、デフォルトのパイプラインステージは以下のようになります：

stages の項目の順序は、ジョブの実行順序を定義します：

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

パイプラインに.pre または.post ステージのジョブのみが含まれている場合、そのパイプラインは実行されません。.pre と.post ステージは、プロジェクトパイプラインジョブの前または後に実行する必要があるコンプライアンスジョブを定義するために、必要なパイプライン設定で使用できます。

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

stages の例：

stages:
  - build
  - test
  - deploy

この例では:

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

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

その他の詳細：

  • ジョブがstage を指定していない場合、そのジョブにはtest ステージが割り当てられます。
  • ステージが定義されているにもかかわらず、それを使用するジョブがない場合、ステージはパイプラインに表示されないため、コンプライアンスのパイプライン設定に役立ちます：
    • ステージはコンプライアンス設定で定義できますが、使用されない場合は非表示のままです。
    • 定義されたステージは、開発者がジョブ定義で使用すると見えるようになります。

関連トピック：

  • ジョブの開始を早め、ステージ順を無視するには、needs キーワードを使用します。

workflow

GitLab 12.5で導入されました

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

関連トピック：

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_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PROJECT1_PIPELINE_NAME: 'MR pipeline: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
      variables:
        PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline'

その他の詳細 ：

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

workflow:rules

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

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

可能な入力：ジョブレベルrules と同じキーワードを使用できます：

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

この例では、コミットタイトル(コミットメッセージの最初の行)の末尾が-draft 、パイプラインの対象がどちらかでない場合にパイプラインが実行されます：

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

その他の詳細：

  • ルールがブランチパイプライン（デフォルトブランチ以外）とマージリクエストパイプラインの両方に一致する場合、パイプラインの重複が発生する可能性があります。

関連トピック：

workflow:rules:variables

workflow:rules でvariables を使って、特定のパイプライン条件の変数を定義することができます。

条件が一致すると変数が作成され、パイプライン内のすべてのジョブで使用できるようになります。変数がすでにグローバルレベルで定義されている場合は、workflow 変数が優先され、グローバル変数が上書きされます。

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

可能な入力：変数名と値のペア：

  • 名前には数字、アルファベット、アンダースコア (_) のみを使用できます。
  • 値は文字列でなければなりません。

workflow:rules:variables の例：

variables:
  DEPLOY_VARIABLE: "default-deploy"

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

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $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 を使用し、ダウンストリームパイプラインに転送したい変数を正確にリストします。

ジョブのキーワード

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

after_script

after_script を使用して、失敗したジョブを含む各ジョブの後に実行されるコマンドの配列を定義します。

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

可能な入力：を含む配列：

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 のコマンドとは別に、新しいシェルで実行されます。その結果

  • ランナーが Git リクエストをどのように処理するかを定義する変数に従って）現在の作業ディレクトリがデフォルトに設定されます。
  • before_script やscript で定義されたコマンドによる変更にはアクセスできません：
    • script のスクリプトでエクスポートされた変数やコマンドのエイリアス。
    • before_script またはscript スクリプトによってインストールされたソフトウェアのような、作業ツリーの外部での変更 (Runner Executor に依存します)。
  • タイムアウトはハードコードで5分に設定されています。
  • ジョブの終了コードには影響しません。script セクションが成功し、after_script がタイムアウトまたは失敗した場合、ジョブはコード0 (Job Succeeded) で終了します。

ジョブがタイムアウトまたはキャンセルされた場合、after_script コマンドは実行さ after_scriptれません。タイムアウトまたはキャンセルされたジョブに対するコマンドafter_script 実行のサポートを追加する after_scriptイシューがafter_script 存在 after_scriptします。

関連トピック：

allow_failure

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

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

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

この同じ警告は次のような場合に表示されます：

  • ステージ内の他のジョブはすべて成功しています。
  • パイプライン内の他のジョブはすべて成功。

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

  • true 手動ジョブの場合。
  • false rules内部でwhen: manual を使用するジョブの場合。
  • 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 ステージのジョブは開始できます。

その他の詳細：

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

allow_failure:exit_codes

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

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 単一の終了コード。
  • 終了コードの配列。

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 設定で定義されたジョブからのみアーティファクトをダウンロードできます。

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

アーティファクトの詳細。

artifacts:paths

パスはプロジェクトディレクトリ ($CI_PROJECT_DIR) からの相対パスであり、外部への直接リンクはできません。

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

可能な入力：

artifacts:paths の例：

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

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

その他の詳細：

  • artifacts:name と併用しない場合、アーティファクト・ファイルはartifacts という名前になり、ダウンロードされるとartifacts.zip になります。

関連トピック：

artifacts:exclude

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

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

可能な入力：

  • プロジェクトディレクトリからの相対パス。
  • グロブまたはdoublestar.PathMatch パターンを使用するワイルドカードを使用できます。

artifacts:exclude の例：

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

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

その他の詳細：

  • artifacts:exclude パスは再帰的に検索されません。
  • artifacts:untracked でマッチしたファイルはartifacts:exclude でも除外できます。

関連トピック：

artifacts:expire_in

  • GitLab 13.0で無効化された機能フラグの後ろに導入され、有効期限に関係なく最新のジョブアーティファクトが保持されます。
  • GitLab 13.4でデフォルトの動作になりました。
  • GitLab 13.8で導入された、最新のジョブアーティファクトの保持をプロジェクトレベルで無効にすることができます。
  • GitLab 13.9 で導入された、最新のジョブアーティファクトの保持をインスタンス全体で無効にすることができます。

expire_in ジョブのアーティファクトが期限切れで削除されるまでの保存期間を指定 expire_inします。expire_in 設定は expire_in影響しません：

  • ただし、最新のジョブのアーティファクトを保持することがプロジェクト・レベルで無効になっている場合はこの限りではありません。

有効期限が切れると、アーティファクトはデフォルトで1時間ごとに削除され (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に保存された時点から始まります。有効期限が定義されていない場合、インスタンス全体の設定がデフォルトとなります。
  • 有効期限をオーバーライドし、アーティファクトが自動的に削除されないようにするには：
    • ジョブページでKeep を選択します。
    • GitLab 13.3 以降では、expire_in の値をnever に設定してください。

artifacts:expose_as

GitLab 12.5で導入されました。

マージリクエスト UI でジョブのアーティファクトを公開するには、artifacts:expose_as キーワードを使用してください。

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

可能な入力：

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

artifacts:expose_as の例：

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

その他の詳細 ：

  • artifacts:paths がCI/CD 変数を使用している場合、アーティファクトが UI に表示されません。
  • マージリクエストごとに公開できるアーティファクトは最大10個です。
  • Globパターンはサポートされていません。
  • ディレクトリが指定され、そのディレクトリに複数のファイルがある場合、リンク先はジョブ・アーティファクト・ブラウザになります。
  • GitLab Pagesが有効な場合、アーティファクトがこれらの拡張子を持つ単一のファイルである場合、GitLabは自動的にアーティファクトをレンダリングします：
    • .html または.htm
    • .txt
    • .json
    • .xml
    • .log

関連トピック：

artifacts:name

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

定義されていない場合、既定の名前はartifacts で、ダウンロードするとartifacts.zip になります。

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

可能な入力：

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

artifacts:name の例：

ジョブの名前でアーカイブを作成します。

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

関連トピック ：

artifacts:public

  • GitLab 13.8でnon_public_artifacts というフラグで導入され、デフォルトでは無効になっています。
  • GitLab 15.10で更新されました。15.10以前のartifacts:public で作成されたアーティファクトは、この更新後も非公開であることは保証されません。
caution
セルフマネジメントのGitLabでは、デフォルトではこの機能は利用できません。利用可能にするには、管理者がnon_public_artifacts という機能フラグを有効にします。GitLab.com では、この機能は利用できません。イシュー 413822により、機能フラグが無効な場合でもキーワードは使用できますが、機能は動作しません。機能フラグが無効になっているときにこの機能を使用しようとせず、必ず最初に本番環境以外のデータでテストしてください。

ジョブのアーティファクトを公開すべきかどうかを判断するには、artifacts:public を使用してください。

artifacts:public がtrue (デフォルト) の場合、公開パイプラインのアーティファクトは匿名ユーザーおよびゲストユーザーがダウンロードできます。

公開パイプラインのアーティファクトに対する匿名ユーザーとゲストユーザーの読み取りアクセスを拒否するには、artifacts:public をfalse に設定します：

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

可能な入力：

  • true (定義されていない場合はデフォルト) またはfalse.

artifacts:public の例：

job:
  artifacts:
    public: false

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 を使うと、Git の追跡されていないファイルをすべてアーティファクトとして追加できます（artifacts:paths で定義したパスも追加されます）。artifacts:untracked はリポジトリの.gitignore, .gitignoreの設定を無視.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 セクション でのみ使用できます。

可能な入力：を含む配列：

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 で指定したスクリプトと連結されます。結合されたスクリプトは、単一のシェルで一緒に実行されます。
  • default セクションではなく、トップレベルでbefore_script を使用することは推奨されません。

関連トピック：

cache

GitLab 15.0 で導入されたキャッシュは、保護されたブランチと保護されていないブランチの間で共有されません。

cache を使って、ジョブ間でキャッシュするファイルやディレクトリのリストを指定します。ローカルの作業コピーにあるパスしか使えません。

キャッシュは

特定のジョブのキャッシュを無効にすることができます：

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

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

cache:paths

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

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

可能な入力：

cache:paths の例：

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

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

その他の詳細：

  • cache:paths キーワードは、追跡されていないファイルや、.gitignore ファイルにあるファイルも含めます。

関連トピック：

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 バッチ を使用してシェルスクリプトを実行する場合は、$ を% に置き換える必要があります。例えばkey: %CI_COMMIT_REF_SLUG%

  • cache:key の値にコンテナを含めることはできません：

    • / 、または同等のURIエンコード%2F 。
    • . 文字（任意の数字）のみ、または同等のURIエンコード%2E 。
  • キャッシュはジョブ間で共有されるため、ジョブごとに異なるパスを使用している場合は、cache:key 。さもないと、キャッシュの内容が上書きされる可能性があります。

関連トピック：

cache:key:files

GitLab 12.5で導入されました。

cache:key:files キーワードを使うと、特定のファイルが一つか二つ変更されたときに新しいキーを生成することができます。cache:key:files を使うと、キャッシュを再利用して再構築する頻度を減らすことができ、その後のパイプラインの実行を高速化することができます。

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

可能な入力：

  • 1つまたは2つのファイルパスの配列。

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 となります。
cache:key:prefix

GitLab 12.5で導入されました。

プレフィックスとcache:key:files で計算された SHA を組み合わせるにはcache:key:prefix を使います。

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

可能な入力：

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

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

追跡されていないファイルをキャッシュすると、ジョブのダウンロード時に予想外に大きなキャッシュが生成される可能性があります：

  • gemsやノードモジュールのような依存ファイルは通常トラッキングされません。
  • 別のジョブのアーティファクト。アーティファクトから抽出されたファイルはデフォルトでは追跡されません。

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

可能な入力：

  • true またはfalse (デフォルト)。

cache:untracked の例：

rspec:
  script: test
  cache:
    untracked: true

その他の詳細 ：

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

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

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

cache:unprotect

GitLab 15.8で導入されました。

cache:unprotect を使って、保護ブランチと非保護ブランチ間で共有するキャッシュを設定します。

caution
true に設定すると、保護ブランチへのアクセス権を持たないユーザーでも、保護ブランチが使用するキャッシュ・キーの読み取りと書き込みが可能になります。

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

可能な入力：

  • true またはfalse (デフォルト)。

cache:unprotect の例：

rspec:
  script: test
  cache:
    unprotect: true

cache:when

GitLab 13.5とGitLab Runner v13.5.0で導入されました。

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 セクション でのみ使用できます。

可能な入力：

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:key のキャッシュが見つからない場合にキャッシュの復元を試みるキーのリストを指定するには、cache:fallback_keys を使用します。 キャッシュは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+)?.

可能な入力：

  • 正規表現。/ で始まり、 で終わる必要があります。カバレッジ番号と一致する必要があります。周囲のテキストにもマッチする可能性があるため、正規表現の文字グループを使用して正確な番号を取得する必要はありません。

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

GitLab 14.1 で導入されました。

CI/CD 設定で使用するサイトプロファイルとスキャナプロファイルを指定するには、dast_configuration キーワードを使用します。両方のプロファイルがプロジェクトで作成されている必要があります。ジョブのステージは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 ジョブは dast include キーワードで追加された設定をdast 拡張して dast、特定のサイトプロファイルとスキャナプロファイルを選択します。

その他の詳細：

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

関連トピック：

dependencies

dependencies キーワードを使用して、アーティファクトをフェッチするジョブのリストを定義します。アーティファクトをまったくダウンロードしないようにジョブを設定することもできます。

dependencies を使用しない場合、前のステージからのすべてのアーティファクトが各ジョブに渡されます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • アーティファクトを取得するジョブの名前。
  • アーティファクトをダウンロードしないようにジョブを設定するには、空の配列 ([]) を指定します。

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 にアクセスできます。

environment:on_stop

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

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

その他の詳細：

environment:action

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

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：以下のキーワードのいずれか：

値説明
startデフォルト値。ジョブが環境を開始することを示します。デプロイはジョブが開始した後に作成されます。
prepareジョブが環境の準備のみを行うことを示します。デプロイはトリガされません。環境の準備についての詳細はこちらをご覧ください。
stopジョブが環境を停止することを示します。環境の停止についての詳細はこちら。
verifyジョブが環境の検証のみを行うことを示します。デプロイはトリガされません。環境の検証についての詳細はこちら。
accessジョブが環境にアクセスしているだけであることを示します。デプロイのトリガーにはなりません。環境へのアクセスについての詳細はこちら。

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

GitLab 12.8で導入されました。

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

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：自然言語で書かれた期間。例えば、これらはすべて等価です：

  • 168 hours
  • 7 days
  • one week
  • never

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 dayNET に設定されます1 day。 レビューアプリがデプロイされるたびに、このライフタイムも .NET にリセット 1 dayされます。

関連トピック：

environment:kubernetes

GitLab 12.6 で導入されました。

kubernetes キーワードを使って、プロジェクトに関連付けられたKubernetes クラスターへのデプロイを設定します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

environment:kubernetes の例：

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      namespace: production

この設定は、Kubernetes名前空間をproduction 使用して、 production環境にデプロイするdeploy ジョブを設定します。

その他の詳細：

関連トピック：

environment:deployment_tier

GitLab 13.10で導入されました。

デプロイ環境の階層を指定するにはdeployment_tier キーワードを使います。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：以下のいずれか：

  • production
  • staging
  • testing
  • development
  • other

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 はランナーによって設定されるCI/CD 変数です。$CI_ENVIRONMENT_SLUG 変数は環境名に基づいていますが、URLに含めるのに適しています。deploy as review app ジョブがpowという名前のブランチで実行される場合、この環境にはhttps://review-pow.example.com/のような URL でアクセスできます。

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

extends

extends を使って設定セクションを再利用します。これはYAML アンカーに代わるもので、少し柔軟で読みやすくなっています。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

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

extends の例：

.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches

rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC

この例では、rspec ジョブは.tests テンプレートジョブの設定を使用します。パイプラインを作成するとき、GitLab：

  • キーを元に逆ディープマージを行います。
  • .tests のコンテンツをrspec のジョブにマージします。
  • キーの値はマージしません。

結果はこのようになりますrspec ジョブ：

rspec:
  script: rake rspec
  stage: test
  only:
    refs:
      - branches
    variables:
      - $RSPEC

その他の詳細：

  • GitLab 12.0 以降では、extends に複数の親を使うことができます。
  • extends キーワードは11レベルまでの継承をサポートしていますが、3レベル以上の継承は避けるべきです。
  • 上記の例では、.tests は隠しジョブですが、通常のジョブからも設定を拡張することができます。

関連トピック：

  • extends を使用して設定セクションを再利用します。
  • extends を使用して、内部設定ファイルから設定を再利用します。

hooks

  • GitLab 15.6 でci_hooks_pre_get_sources_scriptというフラグで導入。デフォルトでは無効。
  • GitLab 15.10で一般的に利用可能。機能フラグci_hooks_pre_get_sources_script を削除しました。

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

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

可能な入力：

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

hooks:pre_get_sources_script

  • GitLab 15.6 でci_hooks_pre_get_sources_scriptというフラグで導入。デフォルトでは無効。
  • GitLab 15.10で一般的に利用可能。機能フラグci_hooks_pre_get_sources_script を削除しました。

hooks:pre_get_sources_script を使って、Git リポジトリとサブモジュールを取得する前に Runner で実行するコマンドのリストを指定します。例えば、Git クライアントの設定を最初に調整するために使うことができます。

関連トピック：

hooks:pre_get_sources_script の例：

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

id_tokens

GitLab 15.7 で導入されました。

id_tokens を使ってJSONウェブトークン(JWT)を作成し、サードパーティのサービスで認証します。この方法で作成された全てのJWTはOIDC認証をサポートします。必須id_tokens サブキーワードは id_tokens、JWTのクレームをid_tokens 設定するために使わ id_tokensれます。

可能な入力 ：

  • トークン名とそのaud クレーム： aud
    • 単一の文字列。
    • 文字列の配列。
    • CI/CD変数。

** id_tokens** の例：

job_with_id_tokens:
  id_tokens:
    ID_TOKEN_1:
      aud: https://gitlab.com
    ID_TOKEN_2:
      aud:
        - https://gcp.com
        - https://aws.com
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - command_to_authenticate_with_gitlab $ID_TOKEN_1
    - command_to_authenticate_with_aws $ID_TOKEN_2

関連トピック ：

image

ジョブが実行されるDockerイメージを指定するにはimage 。

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

可能な入力：画像の名前。 必要であればレジストリパスも：

  • (latest タグと<image-name> 同じ <image-name>)
  • <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:name

ジョブが実行されるDockerイメージの名前。image 。

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

可能な入力：画像の名前。 必要であればレジストリパスも：

  • (latest タグと<image-name> 同じ <image-name>)
  • <image-name>:<tag>
  • <image-name>@<digest>

image:name の例：

image:
  name: "registry.example.com/my/image:latest"

関連トピック ：

image:entrypoint

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

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

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

可能な入力：

  • 文字列。

image:entrypoint の例：

image:
  name: super/sql:experimental
  entrypoint: [""]

関連トピック ：

image:pull_policy

RunnerがDockerイメージを取得するために使用するプルポリシー。

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

可能な入力：

  • 単一のプルポリシー、または配列内の複数のプルポリシー。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]

その他の詳細 ：

  • ランナーが定義されたプルポリシーをサポートしていない場合、ジョブは以下のようなエラーで失敗します：ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never]).

関連トピック：

inherit

GitLab 12.9で導入されました。

inherit を使って、デフォルトのキーワードや変数の継承を制御します。

inherit:default

デフォルト・キーワードの継承を制御するにはinherit:default を使用してください。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • true (デフォルト) またはfalse すべてのデフォルトキーワードの継承を有効または無効にします。
  • 継承する特定のデフォルトキーワードのリスト。

inherit:default の例：

default:
  retry: 2
  image: ruby:3.0
  interruptible: true

job1:
  script: echo "This job does not inherit any default keywords."
  inherit:
    default: false

job2:
  script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
  inherit:
    default:
      - retry
      - image

その他の詳細 ：

  • 継承するデフォルトキーワードを1行に列挙することもできます：default: [keyword1, keyword2]

inherit:variables

inherit:variables を使用して、グローバル変数キーワードの継承を制御します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • true (デフォルト) またはfalse すべてのグローバル変数の継承を有効または無効にします。
  • 継承する変数のリスト。

inherit:variables の例：

variables:
  VARIABLE1: "This is variable 1"
  VARIABLE2: "This is variable 2"
  VARIABLE3: "This is variable 3"

job1:
  script: echo "This job does not inherit any global variables."
  inherit:
    variables: false

job2:
  script: echo "This job inherits only the two listed global variables. It does not inherit 'VARIABLE3'."
  inherit:
    variables:
      - VARIABLE1
      - VARIABLE2

その他の詳細 ：

  • 継承するグローバル変数を1行に列挙することもできます：variables: [VARIABLE1, VARIABLE2]

interruptible

GitLab 12.3 で導入されました。

ジョブが完了する前に新しいパイプラインが開始した場合、ジョブをキャンセルする場合はinterruptible を使用します。

このキーワードは、冗長パイプラインの自動キャンセルを無効にしている場合は効果がありません。有効にすると、interruptible: true を持つ実行中のジョブは、同じブランチで新しい変更のパイプラインを開始するときにキャンセルされます。

interruptible: false を持つジョブが開始した後に、後続のジョブをキャンセルすることはできません。

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

可能な入力：

  • true またはfalse (デフォルト)。

interruptible の例：

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "Can be canceled."
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "Can not be canceled."

step-3:
  stage: stage3
  script:
    - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
  interruptible: true

この例では、新しいパイプラインが実行中のパイプラインを引き起こします：

  • step-1 のみが実行中または保留中の場合は、キャンセルされます。
  • step-2 が起動した後はキャンセルされません。

その他の詳細：

  • ビルドジョブのように、ジョブの開始後に安全にキャンセルできる場合のみ、interruptible: true 。デプロイジョブは通常、部分的なデプロイを防ぐためにキャンセルすべきではありません。
  • 実行中のパイプラインを完全にキャンセルするには、すべてのジョブがinterruptible: true になっているか、interruptible: false ジョブが開始されていない必要があります。

needs

  • GitLab 12.2で導入されました。
  • GitLab 12.3では、needs 配列のジョブ数の最大値が5から50に引き上げられました。
  • GitLab 12.8で導入された needs: [] は、ジョブをすぐに開始できるようにします。
  • GitLab 14.2から導入され、設定中のジョブと同じステージのジョブを参照できるようになりました。

needs ジョブをアウトオブオーダーで実行するために needs使います。使用するneeds ジョブ間の関係は needs 有向非巡回グラフとして可視化できます。

ステージの順序を無視して、他のジョブの完了を待たずにジョブを実行することができます。複数のステージのジョブを同時に実行できます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • ジョブの配列。
  • 空の配列 ([]) を指定すると、パイプラインが作成されると同時にジョブを開始します。

needs の例：

linux:build:
  stage: build
  script: echo "Building linux..."

mac:build:
  stage: build
  script: echo "Building mac..."

lint:
  stage: test
  needs: []
  script: echo "Linting..."

linux:rspec:
  stage: test
  needs: ["linux:build"]
  script: echo "Running rspec on linux..."

mac:rspec:
  stage: test
  needs: ["mac:build"]
  script: echo "Running rspec on mac..."

production:
  stage: deploy
  script: echo "Running production..."
  environment: production

この例では、4つの実行パスを作成します。

  • Linter：lint のジョブはbuild のステージの完了を待たずに即座に実行されます(needs: [])。
  • Linux パス：mac:build の終了を待たずに、linux:build の終了と同時にlinux:rspec のジョブが実行されます。
  • MacOSパス：linux:build の終了を待たずに、mac:build の終了と同時にmac:rspec のジョブが実行されます。
  • production のジョブは、linux:build,linux:rspec,mac:build,mac:rspec のすべての前のジョブが終了するとすぐに実行されます。

その他の詳細：

  • needs 、1つのジョブが持つことのできる最大ジョブ数には制限があります：
    • GitLab.comの場合、上限は50です。詳しくはインフラのイシューをご覧ください。
    • セルフマネージドインスタンスでは、デフォルトの上限は50です。この制限は変更することができます。
  • needs がparallel キーワードを使用するジョブを参照する場合、1 つのジョブだけでなく、並列に作成されたすべてのジョブに依存します。また、デフォルトですべての並列ジョブからアーティファクトをダウンロードします。アーティファクトが同じ名前の場合、それらは互いに上書きされ、最後にダウンロードされたものだけが保存されます。
    • needs 並列化されたジョブのサブセット（並列化されたジョブのすべてではない）を参照するには、needs:parallel:matrix キーワードを使用します。
  • GitLab 14.1以降では、設定中のジョブと同じステージのジョブを参照することができます。この機能はGitLab.comで有効になっており、実運用で使用できるようになっています。セルフマネジメントのGitLab 14.2以降では、この機能はデフォルトで利用可能です。
  • GitLab 14.0以前では、以前のステージのジョブしか参照できません。ステージは、needs キーワードを needs使用する、needs またはジョブのセクションで参照される needsすべてのジョブに対して明示的に定義されなければなりません。
  • GitLab 13.9 以前では、needs がonly,except,rules のためにパイプラインに追加されないかもしれないジョブを参照すると、パイプラインの作成に失敗するかもしれません。GitLab 13.10 以降では、needs:optional キーワードを使ってパイプラインの作成に失敗したことを解決してください。
  • パイプラインにneeds: [] のジョブと.pre のステージのジョブがある場合、パイプラインが作成されると同時にそれらのジョブが開始されます。needs: [] のジョブはすぐに開始され、.pre ステージのジョブもすぐに開始されます。

needs:artifacts

GitLab 12.6 で導入されました。

needsを needs使うジョブは、needs以前のステージ needsが完了する前に開始できるneedsため、デフォルトでは以前のステージから全てのアーティファクトをダウンロード needsしなくなりました。を使うと、設定needs にリストされたジョブからのみアーティファクトをダウンロードできる needsようになります。

needs を使用するジョブでアーティファクトがダウンロードされるタイミングを制御するには、artifacts: true (デフォルト) またはartifacts: false を使用します。

キーワードタイプ：ジョブ・キーワード。ジョブの一部としてのみ使用できます。needs:job と共に使用する必要があります。

可能な入力：

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

needs:artifacts の例：

test-job1:
  stage: test
  needs:
    - job: build_job1
      artifacts: true

test-job2:
  stage: test
  needs:
    - job: build_job2
      artifacts: false

test-job3:
  needs:
    - job: build_job1
      artifacts: true
    - job: build_job2
    - build_job3

この例では:

  • test-job1 ジョブはbuild_job1 のアーティファクトをダウンロードします。
  • test-job2 ジョブはbuild_job2 のアーティファクトをダウンロードしません。
  • test-job3 ジョブは、3 つのbuild_jobs すべてからアーティファクトをダウンロードします。これは、artifacts がtrue、 true必要な 3 つのジョブすべてに対して、true(またはデフォルトが true) 、であるためです。

その他の詳細：

  • GitLab 12.6 以降では、dependencies キーワードとneeds を組み合わせることはできません。

needs:project

GitLab 12.7から導入されました。

needs:project を使って、他のパイプラインの最大5つのジョブからアーティファクトをダウンロードします。アーティファクトは、指定された ref に対して、指定されたジョブのうち最新の成功したジョブからダウンロードされます。複数のジョブを指定するには、needs キーワードの下にそれぞれ別の配列項目として追加します。

Refに対して実行中のパイプラインがある場合、needs:project を持つジョブはパイプラインの完了を待ちません。代わりに、アーティファクトは指定されたジョブの最新の成功した実行からダウンロードされます。

needs:project は、job 、ref 、artifacts と共に使用する必要があります。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • needs:project:名前空間とグループを含む完全なプロジェクト・パス。
  • job:アーティファクトをダウンロードするジョブ。
  • ref:アーティファクトをダウンロードする参照元。
  • artifacts:アーティファクトをダウンロードするにはtrue である必要があります。

** needs:project**の例：

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: namespace/group/project-name
      job: build-1
      ref: main
      artifacts: true
    - project: namespace/group/project-name-2
      job: build-2
      ref: main
      artifacts: true

この例では、build_job は、group/project-name とgroup/project-name-2 プロジェクトのmain ブランチ上のbuild-1 とbuild-2 ジョブからアーティファクトをダウンロードします。

GitLab 13.3 以降では、例えばneeds:project でCI/CD 変数を使うことができます：

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: $CI_PROJECT_PATH
      job: $DEPENDENCY_JOB_NAME
      ref: $ARTIFACTS_DOWNLOAD_REF
      artifacts: true

その他の詳細：

  • 現在のプロジェクト内の別のパイプラインからアーティファクトをダウンロードするには、project を現在のプロジェクトと同じに設定しますが、現在のパイプラインとは別の ref を使用します。同じ ref で実行されている並行パイプラインは、アーティファクトを上書きする可能性があります。
  • パイプラインを実行するユーザーは、グループまたはプロジェクトの少なくともレポーターロールを持っているか、グループ/プロジェクトが公開されている必要があります。
  • trigger と同じジョブでneeds:project を使用することはできません。
  • 別のパイプラインからアーティファクトをダウンロードするためにneeds:project を使用する場合、ジョブは必要なジョブの完了を待ちません。有効非巡回グラフの動作は、同じパイプライン内のジョブに限定されます。必要なジョブがアーティファクトをダウンロードする前に、他のパイプラインの必要なジョブが完了するようにしてください。
  • parallelで実行されるジョブからアーティファクトをダウンロードすることはできません。
  • project,job,ref のCI/CD 変数のサポートは GitLab 13.3 で導入されました。GitLab 13.4 で機能フラグが削除されました。

関連トピック：

needs:pipeline:job

GitLab 13.7 で導入されました。

子パイプラインは、親パイプライン内のジョブや、同じ親子パイプライン階層内の別の子パイプラインからアーティファクトをダウンロードすることができます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • needs:pipeline:パイプラインID。同じ親子パイプライン階層に存在するパイプラインである必要があります。
  • job:アーティファクトをダウンロードするジョブ。

needs:pipeline:job の例：

  • 親パイプライン (.gitlab-ci.yml)：

     create-artifact:
   stage: build
   script: echo "sample artifact" > artifact.txt
   artifacts:
     paths: [artifact.txt]
   
 child-pipeline:
   stage: test
   trigger:
     include: child.yml
     strategy: depend
   variables:
     PARENT_PIPELINE_ID: $CI_PIPELINE_ID

  • 子パイプライン (child.yml)：

     use-artifact:
   script: cat artifact.txt
   needs:
     - pipeline: $PARENT_PIPELINE_ID
       job: create-artifact

この例では、親パイプラインのcreate-artifact ジョブがアーティファクトを作成します。child-pipeline ジョブは子パイプラインをトリガーし、CI_PIPELINE_ID 変数を新しいPARENT_PIPELINE_ID 変数として子パイプラインに渡します。子パイプラインは、needs:pipeline でその変数を使用して、親パイプラインからアーティファクトをダウンロードできます。

その他の詳細：

  • pipeline 属性は、現在のパイプライン ID ($CI_PIPELINE_ID) を受け付けません。現在のパイプラインのジョブからアーティファクトをダウンロードするには、needsを使用します。

needs:optional

パイプラインに存在しないジョブを必要とするには、needs の設定にoptional: true を追加してください。定義されていない場合は、optional: false がデフォルトです。

rules,only,except を使用し、include で追加されたジョブは、常にパイプラインに追加されるとは限りません。GitLabはパイプラインを開始する前にneeds の関係をチェックします：

  • needs エントリがoptional: true を持ち、必要なジョブがパイプラインに存在する場合、ジョブはそのジョブが完了するのを待ってから開始します。
  • 必要なジョブが存在しない場合、ジョブは他のすべての必要条件が満たされたときに開始することができます。
  • needs セクションがオプションのジョブのみを含み、パイプラインに何も追加されていない場合、ジョブはすぐに開始されます(空の needsエントリと同じです:needs: [])。
  • 必要なジョブがoptional: false 、パイプラインに追加されていない場合、パイプラインは次のようなエラーで開始できません：'job1' job needs 'job2' job, but it was not added to the pipeline.

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

needs:optional の例：

build-job:
  stage: build

test-job1:
  stage: test

test-job2:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
    - job: test-job1
  environment: production

review-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
  environment: review

この例では:

  • build-job test-job1 、test-job2 の順にステージが始まります。
  • ブランチがデフォルトブランチの場合、test-job2 、パイプラインに追加されます：
    • deploy-job はtest-job1 とtest-job2 の両方の完了を待ちます。
    • review-job test-job2 の完了を待ちます。
  • ブランチがデフォルトブランチでない場合、test-job2 はパイプラインに追加されません：
    • deploy-job はtest-job1 の完了だけを待ち、欠落しているtest-job2 を待ちません。
    • review-job は他に必要なジョブがなく、needs: [] のようにすぐに（build-job と同時に）開始します。

needs:pipeline

needs:pipeline キーワードを使用すると、アップストリームパイプラインのパイプラインステータスをジョブにミラーリングできます。デフォルトブランチの最新のパイプラインステータスがジョブにレプリケートされます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 名前空間とグループを含む完全なプロジェクト・パス。プロジェクトが同じグループまたはネームスペースにある場合は、project キーワードからそれらを省略できます。例：project: group/project-name またはproject: project-name 。

needs:pipeline の例：

upstream_status:
  stage: test
  needs:
    pipeline: other/project

その他の詳細 ：

  • needs:pipeline にjob キーワードを追加すると、ジョブはパイプラインステータスを反映しなくなります。動作はneeds:pipeline:job に変わります。

needs:parallel:matrix

GitLab 16.3 で導入されました。

ジョブはparallel:matrix を使って、ジョブのインスタンスごとに異なる変数を使って、一つのパイプラインで複数回並行して実行することができます。

needs:parallel:matrix を使用すると、並列化されたジョブに応じてジョブを順番通りに実行できません。

キーワードタイプ：ジョブ・キーワード。ジョブの一部としてのみ使用できます。needs:job と共に使用する必要があります。

可能な入力：変数のハッシュの配列：

  • 変数と値は、parallel:matrix ジョブで定義された変数と値から選択する必要があります。

needs:parallel:matrix の例：

linux:build:
  stage: build
  script: echo "Building linux..."
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2

linux:rspec:
  stage: test
  needs:
    - job: linux:build
      parallel:
        matrix:
          - PROVIDER: aws
            STACK: app1
  script: echo "Running rspec on linux..."

上記の例は以下のジョブを生成します：

linux:build: [aws, monitoring]
linux:build: [aws, app1]
linux:build: [aws, app2]
linux:rspec

linux:rspec ジョブはlinux:build: [aws, app1] ジョブの終了と同時に実行されます。

関連トピック：

only /except

note
only やexcept は積極的に開発されていません。 rulesは、パイプラインにジョブを追加するタイミングを制御するために推奨されるキーワードです。

ジョブをパイプラインに追加するタイミングを制御するには、only とexcept を使用できます。

  • only を使用して、ジョブが実行されるタイミングを定義します。
  • ジョブが実行されないタイミングを定義するには、except を使用します。

詳細と例については、specified when jobs run withonly andexcept を参照してください。

only:refs /except:refs

ブランチ名やパイプラインタイプに基づいてジョブをパイプラインに追加するタイミングを制御するには、only:refs とexcept:refs キーワードを使用します。

only:refs except:refs ジョブをパイプラインに追加するタイミングを制御するために参照、正規表現、変数を使用する場合は、rules:if 。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：任意の数を含む配列：

  • ブランチ名、例えばmain やmy-feature-branch 。
  • ブランチ名にマッチする正規表現、例えば/^feature-.*/ 。

  • 以下のキーワード：

    値説明
    api パイプラインAPIで起動されたパイプラインの場合。
    branchesパイプラインのGit参照がブランチの場合。
    chat GitLab ChatOps コマンドを使用して作成したパイプラインの場合。
    externalGitLab以外のCIサービスを利用する場合。
    external_pull_requestsGitHub上の外部プルリクエストが作成または更新されたとき（詳細は外部プルリクエスト用のパイプラインを参照してください）。
    merge_requestsマージリクエストが作成または更新されたときに作成されるパイプライン用です。マージリクエストパイプライン、マージ結果パイプライン、マージトレインを有効にします。
    pipelines CI_JOB_TOKEN](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api)またはtrigger キーワードを使用した API を使用して[で作成されたマルチプロジェクトパイプラインの場合。
    pushesブランチやタグを含む、git push イベントをトリガーとするパイプラインの場合。
    schedules スケジュールパイプラインの場合。
    tagsパイプラインのGit参照がタグの場合。
    triggers トリガートークンを使用して作成されたパイプラインの場合。
    webGitLab UI でプロジェクトのBuild > PipelinesセクションからRun pipelineを選択して作成したパイプラインの場合。

** only:refs とexcept:refs** の例：

job1:
  script: echo
  only:
    - main
    - /^issue-.*$/
    - merge_requests

job2:
  script: echo
  except:
    - main
    - /^stable-branch.*$/
    - schedules

その他の詳細 ：

  • スケジュールされたパイプラインは特定のブランチで実行されるため、only: branches で設定されたジョブもスケジュールされたパイプライン上で実行されます。only: branches のジョブがスケジュールされたパイプライン上で実行されないようにするには、except: schedules を追加します。

  • only またはexcept を他のキーワードなしで使用した場合は、only: refs またはexcept: refs と同じです。例えば、以下の2つのジョブ設定は同じ動作をします：

     job1:
   script: echo
   only:
     - branches
   
 job2:
   script: echo
   only:
     refs:
       - branches

  • ジョブがonly,except, またはrules を使用しない場合、only はデフォルトでbranches およびtags に設定されます。

    例えば、job1 とjob2 は等価です：

     job1:
   script: echo "test"
   
 job2:
   script: echo "test"
   only:
     - branches
     - tags

only:variables /except:variables

CI/CD 変数の状態に基づいて、パイプラインにジョブを追加するタイミングを制御するには、only:variables またはexcept:variables キーワードを使用します。

only:variables except:variables ジョブをパイプラインに追加するタイミングを制御するために参照、正規表現、変数を使用する場合は、rules:if 。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

only:variables の例：

deploy:
  script: cap staging deploy
  only:
    variables:
      - $RELEASE == "staging"
      - $STAGING

関連トピック ：

only:changes /except:changes

Git のプッシュイベントによってファイルが変更された場合に、ジョブを実行するにはonly とともにchanges キーワードを、ジョブをスキップするにはexcept とともに使用します。

パイプラインでは、changes を次の参照で使用します：

  • branches
  • external_pull_requests
  • merge_requests (マージリクエストパイプラインでonly:changes を使用するについての詳細は を参照してください)

only:changes except:changes パイプラインにジョブを追加するタイミングを制御するために変更されたファイルを使用する場合、rules:changes が好ましいキーワードです。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：任意の数を含む配列：

  • ファイルへのパス。
  • 単一のディレクトリ、例えばpath/to/directory/* 、またはディレクトリとそのすべてのサブディレクトリ、例えばpath/to/directory/**/* のためのワイルドカードパス。
  • 同じ拡張子または複数の拡張子を持つすべてのファイルに対するワイルドカード・グローブ・パス、たとえば*.md やpath/to/directory/*.{rb,py,sh} 。 サポートされている構文の一覧については、Rubyfnmatch ドキュメント を参照してください。
  • 二重引用符で囲んだ、ルートディレクトリまたはすべてのディレクトリのファイルへのワイルドカードパス。例えば、"*.json" や"**/*.json" などです。

only:changes の例：

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - branches
    changes:
      - Dockerfile
      - docker/scripts/*
      - dockerfiles/**/*
      - more_scripts/*.{rb,py,sh}
      - "**/*.json"

その他の詳細 ：

  • changes 一致するファイルのいずれかが変更された場合、true に解決されます (OR オペレーション)。
  • branches 、external_pull_requests 、merge_requests 以外の参照を使っている場合、changes は指定されたファイルが新しいか古いかを判断できず、常にtrue を返します。
  • only: changes を他の参照と一緒に使用すると、ジョブは変更を無視して常に実行されます。
  • except: changes を他の参照と一緒に使うと、ジョブは変更を無視して実行されません。

関連トピック：

only:kubernetes /except:kubernetes

only:kubernetes またはexcept:kubernetes を使用して、プロジェクトで Kubernetes サービスがアクティブなときにパイプラインにジョブが追加されるかどうかを制御します。

only:refs とexcept:refs はアクティブに開発されていません。Kubernetesサービスがプロジェクトでアクティブなときにジョブがパイプラインに追加されるかどうかを制御するには、rules:if をCI_KUBERNETES_ACTIVE 定義済みCI/CD変数と一緒に使用します。

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

可能な入力：

  • kubernetes 戦略はactive キーワードのみを受け付けます。

only:kubernetes の例：

deploy:
  only:
    kubernetes: active

この例では、deploy ジョブはプロジェクト内で Kubernetes サービスがアクティブなときにのみ実行されます。

pages

静的コンテンツをGitLabにアップロードするGitLab Pagesジョブを定義するには、pages 。コンテンツはウェブサイトとして公開されます。

あなたは

  • artifacts 、デフォルトではpublic 。
  • 異なるコンテンツ・ディレクトリを使用したい場合は、publish を使用してください。

キーワードの種類ジョブ名

pages の例：

pages:
  stage: deploy
  script:
    - mv my-html-content public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

この例では、すべてのファイルをmy-html-content/ ディレクトリからpublic/ ディレクトリに移動します。このディレクトリはアーティファクトとしてエクスポートされ、GitLab Pagesで公開されます。

pages:publish

GitLab 16.1 で導入されました。

pages ジョブ のコンテンツディレクトリを設定するにはpublish を使います。

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

可能な入力：Pages コンテンツを含むディレクトリへのパス。

publish の例：

pages:
  stage: deploy
  script:
    - npx @11ty/eleventy --input=path/to/eleventy/root --output=dist
  artifacts:
    paths:
      - dist
  publish: dist
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

この例では、Eleventyを使って静的なウェブサイトを生成し、生成されたHTMLファイルをdist/ ディレクトリに出力します。このディレクトリはアーティファクトとしてエクスポートされ、GitLab Pagesで公開されます。

parallel

GitLab 15.9で導入され、parallel の最大値が50から200に増えました。

一つのパイプラインでジョブを複数回並行して実行するには、parallel 。

複数の Runner が存在するか、1 つの Runner が複数のジョブを同時に実行するように設定されている必要があります。

Parallelsジョブは、job_name 1/N からjob_name N/N まで順次名前が付けられます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 1 から200 までの数値。

parallel の例：

test:
  script: rspec
  parallel: 5

この例では、test 1/5 からtest 5/5 という名前の、並行して実行される5つのジョブを作成します。

その他の詳細：

  • すべての並列ジョブは、CI_NODE_INDEX 、CI_NODE_TOTAL 定義済みの CI/CD 変数セットを持っています。
  • parallel を使用するジョブを持つパイプラインはそうかもしれません：
    • 利用可能な Runner よりも多くのジョブを Parallels で実行します。利用可能な Runner を待つ間、余分なジョブはキューに入れられ、pending とマークされます。
    • ジョブを作成しすぎると、パイプラインはjob_activity_limit_exceeded エラーで失敗します。アクティブなパイプラインに存在できるジョブの最大数は、インスタンスレベルで制限されます。

関連トピック：

parallel:matrix

parallel:matrix を使って、一つのパイプラインでジョブを複数回並行して実行しますが、ジョブのインスタンスごとに異なる変数値を設定します。

複数の Runner が存在するか、1 つの Runner が複数のジョブを同時に実行するように設定されている必要があります。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：変数のハッシュの配列：

  • 変数名には、数字、アルファベット、アンダースコア (_) のみを使用できます。
  • 値は文字列か文字列の配列でなければなりません。
  • 順列の数は200を超えることはできません。

parallel:matrix の例：

deploystacks:
  stage: deploy
  script:
    - bin/deploy
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2
      - PROVIDER: ovh
        STACK: [monitoring, backup, app]
      - PROVIDER: [gcp, vultr]
        STACK: [data, processing]
  environment: $PROVIDER/$STACK

この例では、PROVIDER とSTACK にそれぞれ異なる値を指定し、deploystacks ジョブを 10 並列生成しています：

deploystacks: [aws, monitoring]
deploystacks: [aws, app1]
deploystacks: [aws, app2]
deploystacks: [ovh, monitoring]
deploystacks: [ovh, backup]
deploystacks: [ovh, app]
deploystacks: [gcp, data]
deploystacks: [gcp, processing]
deploystacks: [vultr, data]
deploystacks: [vultr, processing]

その他の詳細：

関連トピック：

release

GitLab 13.2 で導入されました。

release を使ってリリースを作成します。

リリース・ジョブは、release-cli にアクセスできなければなりません。$PATH は、 にあります。

Dockerエクゼキュータを使う場合は、GitLabコンテナレジストリからこのイメージを使うことができます：registry.gitlab.com/gitlab-org/release-cli:latest

Executorなどを使用する場合は、ランナーが登録されているサーバーにrelease-cli をインストールしてください。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：release のサブキー：

** release キーワードの例**：

release_job:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG                  # Run this job when a tag is created manually
  script:
    - echo "Running the release job."
  release:
    tag_name: $CI_COMMIT_TAG
    name: 'Release $CI_COMMIT_TAG'
    description: 'Release created using the release-cli.'

この例ではリリースを作成します：

  • Git タグをプッシュすると、次のようになります。
  • UI のCode > Tags で Git タグを追加したとき。

その他の詳細 ：

  • トリガージョブを除くすべてのリリースジョブには、script キーワードを含める必要があります。リリースジョブはスクリプトコマンドからの出力を使用できます。スクリプトが不要な場合は、プレースホルダを使用できます：

     script:
   - echo "release job"

    この要件を削除するイシューが存在します。

  • release セクションはscript キーワードの後でafter_scriptの前に実行されます。
  • リリースは、ジョブのメインスクリプトが成功した場合にのみ作成されます。
  • リリースが既に存在する場合、そのリリースは更新されず、release キーワードを指定したジョブは失敗します。

関連トピック：

release:tag_name

必須。リリースの Git タグ。

プロジェクトにタグがまだ存在しない場合は、リリースと同時に作成されます。新しいタグは、パイプラインに関連付けられた SHA を使用します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • タグ名。

CI/CD変数に対応しています。

release:tag_name の例：

プロジェクトに新しいタグが追加されたときにリリースを作成する場合：

  • CI/CD 変数$CI_COMMIT_TAG をtag_name として使います。
  • rules:if を使って、新しいタグに対してのみジョブを実行するように設定してください。
job:
  script: echo "Running the release job for the new tag."
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release description'
  rules:
    - if: $CI_COMMIT_TAG

リリースと新しいタグを同時に作成するために、rules 、新しいタグのためだけにジョブを実行するように設定すべきではありません。セマンティックバージョニングの例

job:
  script: echo "Running the release job and creating a new tag."
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: 'Release description'
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

release:tag_message

GitLab 15.3で導入されました。release-cli v0.12.0以降でサポート。

タグが存在しない場合、新しく作成されたタグはtag_message で指定されたメッセージでアノテーションされます。省略された場合は、軽量タグが作成されます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 文字列。

release:tag_message の例：

  release_job:
    stage: release
    release:
      tag_name: $CI_COMMIT_TAG
      description: 'Release description'
      tag_message: 'Annotated tag message'

release:name

リリース名。省略した場合はrelease: tag_name の値が入力されます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 文字列。

release:name の例：

  release_job:
    stage: release
    release:
      name: 'Release $CI_COMMIT_TAG'

release:description

リリースの長い説明。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 長い説明を表す文字列。
  • 説明を含むファイルへのパス。GitLab 13.7 で導入。
    • ファイルの場所はプロジェクトディレクトリ($CI_PROJECT_DIR)からの相対パスでなければなりません。
    • ファイルがシンボリックリンクの場合は、$CI_PROJECT_DIR 。
    • ./path/to/file とファイル名にスペースを含めることはできません。

release:description の例：

job:
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: './path/to/CHANGELOG.md'

その他の詳細 ：

  • description はrelease-cli を実行する Shell によって評価されます。CI/CD変数を使用して記述を定義できますが、シェルによっては変数の参照に異なる構文を使用します。同様に、シェルによっては特殊文字をエスケープする必要があるかもしれません。例えば、バックスティック(`)はバックスラッシュ(\)でエスケープする必要があるかもしれません。

release:ref

release: tag_name がまだ存在しない場合は、リリースのref を指定します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • コミット SHA、別のタグ名、ブランチ名。

release:milestones

リリースが関連する各マイルストーンのタイトルです。

release:released_at

リリースの準備ができた日時。

可能な入力：

  • 引用符で囲まれた ISO 8601 形式の日付。

release:released_at の例：

released_at: '2021-03-15T08:00:00Z'

その他の詳細 ：

  • 定義されていない場合は、現在の日付と時刻が使用されます。

GitLab 13.12 で導入されました。

リリースにアセットリンクを含めるにはrelease:assets:links を使用してください。

release-cli バージョン v0.4.0 以降が必要です。

release:assets:links の例：

assets:
  links:
    - name: 'asset1'
      url: 'https://example.com/assets/1'
    - name: 'asset2'
      url: 'https://example.com/assets/2'
      filepath: '/pretty/url/1' # optional
      link_type: 'other' # optional

resource_group

GitLab 12.7から導入されました。

resource_group を使ってリソースグループを作成し、同じプロジェクトの異なるパイプライン間でジョブが相互に排他されるようにします。

例えば、同じリソースグループに属する複数のジョブが同時にキューに入った場合、ジョブの1つだけが開始します。他のジョブはresource_group が空くまで待機します。

リソースグループは、他のプログラミング言語におけるセマフォに似た振る舞いをします。

環境ごとに複数のリソースグループを定義できます。例えば、物理デバイスにデプロイする場合、複数の物理デバイスがあるかもしれません。各デバイスにデプロイできますが、1 つのデバイスにつき、常に 1 つのデプロイしかできません。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 文字、数字、- 、_、/ 、$ 、{、}、.、スペースのみ。/で始まったり終わったりすることはできません。CI/CD 変数がサポートされています。

resource_group の例：

deploy-to-production:
  script: deploy
  resource_group: production

この例では、2つのパイプラインの2つのジョブ（deploy-to-production ）が同時に実行されることはありません。その結果、本番環境への同時デプロイが絶対に起こらないようにすることができます。

関連トピック：

retry

retry を使用して、ジョブが失敗した場合に再試行する回数を設定します。定義されていない場合、デフォルトは0 で、ジョブは再試行されません。

ジョブが失敗した場合、そのジョブは成功するか、最大再試行回数に達するまで、最大2回まで処理されます。

デフォルトでは、すべての失敗タイプでジョブが再試行されます。retry:when を使用して、再試行する失敗を選択します。

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

可能な入力：

  • 0 (デフォルト）、1、または2 。

retry の例：

test:
  script: rspec
  retry: 2

retry:when

retry:when を使用retry:max すると、特定の障害ケースに対してのみジョブを再試行できます。 retry:max retry のように最大再試行回数を指定し、0 、1、または2のいずれかを指定します。

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

可能な入力：

  • 単一の障害タイプ、または1つ以上の障害タイプの配列：
  • always: 失敗したら再試行（デフォルト）。
  • unknown_failure: 失敗理由が不明な場合に再試行します。
  • script_failure:リトライ
    • スクリプトが失敗しました。
    • Runner が Docker イメージのプルに失敗しました。docker,docker+machine,kubernetes Executorの場合。
  • api_failure: API失敗時に再試行します。
  • stuck_or_timeout_failure: ジョブがスタックまたはタイムアウトした場合に再試行します。
  • runner_system_failure:Runnerシステムに障害が発生した場合に再試行します（ジョブのセットアップに失敗した場合など）。
  • runner_unsupported:ランナーがサポートされていない場合に再試行します。
  • stale_schedule: 遅延したジョブが実行できなかった場合に再試行します。
  • job_execution_timeout: スクリプトがジョブに設定された最大実行時間を超えた場合に再試行します。
  • archived_failure: ジョブがアーカイブされ、実行できない場合に再試行します。
  • unmet_prerequisites: ジョブが前提条件のタスクを完了できなかった場合に再試行します。
  • scheduler_failure: スケジューラがジョブのRunnerへの割り当てに失敗した場合に再試行します。
  • data_integrity_failure:構造的インテグレーションに問題が検出された場合は、リトライします。

** retry:when** （単一故障タイプ）の例：

test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure

Runnerシステム障害以外の障害が発生した場合、ジョブは再試行されません。

** retry:when** (障害タイプの配列) の例：

test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

関連トピック：

変数を使用して、ジョブ実行の特定のステージに対する再試行回数を指定できます。

rules

GitLab 12.3 で導入されました。

rules を使ってパイプラインにジョブを含めたり除外したりできます。

ルールはパイプラインが作成されたときに評価され、最初にマッチするまで順番に評価されます。一致するジョブが見つかると、設定に応じてそのジョブはパイプラインに含まれるか除外されます。

ルールはジョブが実行される前に評価されるため、ジョブスクリプトで作成されたdotenv変数をルールで使用することはできません。

rules はonly/except に置き換えられ、同じジョブで一緒に使うことはできません。1つのジョブで両方のキーワードを使うように設定すると、GitLabはkey may not be used with rules エラーを返します。

rules で定義されたルールの配列を受け取ります：

  • if
  • changes
  • exists
  • allow_failure
  • variables
  • when

複数のキーワードを組み合わせて、複雑なルールを作成することができます。

ジョブがパイプラインに追加される場合:

  • if 、changes 、exists のルールがマッチし、when: on_success (デフォルト)、when: delayed 、when: alwaysもマッチする場合。
  • when: on_success 、when: delayed 、またはwhen: always のみのルールに達した場合。

ジョブはパイプラインに追加されない場合:

  • 一致するルールがない場合
  • ルールが一致し、when: never 。

!reference タグ から rules 設定 を異なるジョブで再利用できます。

rules:if

rules:if 節を使用して、ジョブをパイプラインに追加するタイミングを指定します：

  • if ステートメントが真の場合、ジョブをパイプラインに追加します。
  • if ステートメントが真で、when: never と組み合わされている場合は、ジョブをパイプラインに追加しないでください。
  • if ステートメントが真でない場合、ジョブをパイプラインに追加しないでください。

if 節は、一部の例外を除き、CI/CD変数または事前に定義されたCI/CD変数の値に基づいて評価されます。

キーワードタイプ：ジョブ固有、パイプライン固有。ジョブの一部として使用してジョブの動作を設定したり、workflow と一緒に使用してパイプラインの動作を設定したりできます。

可能な入力：

rules:if の例：

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/
      when: manual
      allow_failure: true
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

その他の詳細 ：

  • ルールがマッチし、when の定義がない場合、ルールはジョブのデフォルトの on_success として when を使用します。
  • GitLab 14.5以前では、定義できるのはwhen ルールごとに1回、もしくはジョブレベルで1回 whenです。ルールの中でジョブレベルとwhen をwhen 混在させる whenことはできません。
  • GitLab 14.6以降では、ジョブレベルでのwhen とルールでのwhen を混ぜることができます.rules でのwhen 設定は、ジョブレベルでのwhen より優先されます。
  • script セクションの変数とは異なり、ルール式の変数は常に$VARIABLE のようにフォーマットされます。
  • =~ と!~ 表現の右側にある CI/CD 変数は正規表現として評価されます。

関連トピック：

rules:changes

rules:changes を使用して、特定のファイルの変更をチェックしてパイプラインにジョブを追加するタイミングを指定します。

caution
rules: changes ブランチパイプラインや マージリクエストパイプラインでのみrules: changes使用します。他のパイプラインタイプでもrules: changes 使用 rules: changesできますが、rules: changes Git rules: changesイベントがrules: changes ない場合は常にtrueと評価さ rules: changesれますrules: changes push 。タグパイプラインやスケジュールパイプライン、手動パイプラインなどでは、Git pushイベントは発生push しません push。 rules: changesジョブをブランチやマージリクエストパイプラインに限定する** がなければ、rules: changes ジョブは rules: changes 常にこれらのパイプラインに追加されます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

任意の数を含む配列：

  • ファイルへのパス。GitLab 13.6 以降では、ファイルパスに変数を含めることができます。ファイルパスの配列は、rules:changes:paths 。
  • のワイルドカードパス：
    • 単一ディレクトリ、例えばpath/to/directory/*.
    • ディレクトリとそのすべてのサブディレクトリ、たとえばpath/to/directory/**/* 。
  • 同じ拡張子または複数の拡張子を持つすべてのファイルに対するワイルドカードグロブパス、例えば*.md やpath/to/directory/*.{rb,py,sh} 。 サポートされる構文の一覧はRubyfnmatch ドキュメント を参照してください。
  • 二重引用符で囲んだ、ルートディレクトリまたはすべてのディレクトリのファイルへのワイルドカードパス。例えば、"*.json" や"**/*.json" などです。

rules:changes の例：

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile
      when: manual
      allow_failure: true
  • パイプラインがマージリクエストパイプラインの場合、Dockerfile に変更がないか確認してください。
  • Dockerfile が変更されている場合、ジョブを手動ジョブとしてパイプラインに追加します。パイプラインは、ジョブがトリガーされなくても実行し続けます (allow_failure: true)。
  • 1つのrules:changes セクションにつき、最大50のパターンまたはファイルパスを定義できます。
  • Dockerfile が変更されていない場合、(when: neverと同じように)ジョブをパイプラインに追加しません。
  • rules:changes:paths は、サブキーがない場合はrules:changes と同じです。

その他の詳細：

  • rules: changes はonly: changes やexcept: changes と同じ働きをします。
  • when: never を使って、except:changes と同様のルールを実装することができます。
  • changes 一致するファイルのいずれかが変更された場合、true に解決されます (OR オペレーション)。

関連トピック：

  • rules: changes を使用すると、ジョブやパイプラインが予期せず実行されることがあります。
rules:changes:paths

GitLab 15.2 で導入されました。

rules:changes を使って特定のファイルが変更されたときだけパイプラインにジョブを追加するように指定し、rules:changes:paths を使ってファイルを指定します。

rules:changes:paths は、サブキーなしでrules:changes を使用するのと同じです。追加の詳細と関連するトピックはすべて同じです。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

rules:changes:paths の例：

docker-build-1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile

docker-build-2:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile

この例では、どちらのジョブも同じ動作をします。

rules:changes:compare_to

rules:changes:compare_to を使って、rules:changes:paths にリストされたファイルへの変更を比較する ref を指定します。

キーワードタイプ：ジョブ・キーワード。ジョブの一部としてのみ使用でき、rules:changes:paths と組み合わせる必要があります。

可能な入力 ：

  • main,branch1,refs/heads/branch1 のようなブランチ名。
  • tag1 やrefs/tags/tag1 のようなタグ名。
  • 2fg31ga14b のようなコミットSHA。

rules:changes:compare_to の例：

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile
        compare_to: 'refs/heads/branch1'

この例では、Dockerfile がrefs/heads/branch1 に対して相対的に変更され、パイプラインソースがマージリクエストイベントである場合にのみ、docker build ジョブが含まれます。

rules:exists

exists を使って、リポジトリに特定のファイルが存在するときにジョブを実行します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • ファイルパスの配列。パスはプロジェクトディレクトリ ($CI_PROJECT_DIR) からの相対パスで、内部リンクはできません。ファイルパスはグロブパターンとCI/CD 変数を使用できます。

rules:exists の例：

job:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - Dockerfile

job リポジトリのどこかにDockerfile が存在するかどうかを調べます。

その他の詳細：

  • Glob パターンは RubyFile.fnmatch のフラグFile::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB で解釈されます。
  • パフォーマンス上の理由から、GitLabはexists パターンやファイルパスに対して exists最大10,000回のチェックを行います。exists 10,000回目のチェック以降は、パターン化されたグロブを持つルールは常にマッチします。 exists言い換えると、ファイル数が10,000を超えるプロジェクト、またはファイル数が10,000未満でもexists ルールが10,000回以上チェックされる場合、exists ルールは exists常に一致すると見なされます。
  • 1つのrules:exists セクションにつき、最大50のパターンまたはファイルパスを定義できます。
  • exists リストされたファイルのいずれかが見つかった場合、true に解決します (OR オペレーション)。

rules:allow_failure

GitLab 12.8で導入されました。

rules でallow_failure: true を使用すると、パイプラインを停止せずにジョブを失敗させることができます。

手動ジョブでallow_failure: true を使用することもできます。パイプラインは手動ジョブの結果を待たずに実行を続けます。allow_failure: false とwhen: manual を規則で組み合わせると、パイプラインは手動ジョブの実行を待ってから実行を続けます。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

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

rules:allow_failure の例：

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
      when: manual
      allow_failure: true

ルールが一致した場合、そのジョブは手動ジョブでallow_failure: true 。

その他の詳細：

  • ルールレベルのrules:allow_failure は、ジョブレベルのallow_failure を上書きし、特定のルールがジョブをトリガーする場合にのみ適用されます。

rules:needs

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

ルールでneeds を使って、特定の条件に対してジョブのneeds を更新します。条件がルールにマッチすると、ジョブのneeds 設定は完全に needsルールの内容に置き換えられます。

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

可能な入力：

  • 文字列としてのジョブ名の配列。
  • ジョブ名のハッシュ、オプションで追加属性。
  • 空の配列 ([]) を指定すると、特定の条件が満たされたときにジョブが不要になります。

rules:needs の例：

build-dev:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
  script: echo "Feature branch, so building dev version..."

build-prod:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script: echo "Default branch, so building prod version..."

specs:
  stage: test
  needs: ['build-dev']
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      needs: ['build-prod']
    - when: on_success # Run the job in other cases
  script: echo "Running dev specs by default, or prod specs when default branch..."

この例では:

  • パイプラインがデフォルトブランチでないブランチで実行される場合、specs ジョブはbuild-dev ジョブを必要とします (デフォルトの動作)。
  • パイプラインがデフォルトブランチで実行され、そのためルールが条件に一致する場合、specs ジョブは代わりにbuild-prod ジョブを必要とします。

その他の詳細：

  • needs のルールは needsジョブレベルで定義されたneeds ものを上書き needsします。オーバーライドされた場合、動作はジョブレベルneeds と同じになります。
  • needs inルールは、artifacts およびoptionalを受け入れることができます。

rules:variables

rules でvariables を使って、特定の条件の変数を定義します。

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

可能な入力：

  • VARIABLE-NAME: value という形式の変数のハッシュ。

rules:variables の例：

job:
  variables:
    DEPLOY_VARIABLE: "default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                              # Override DEPLOY_VARIABLE defined
        DEPLOY_VARIABLE: "deploy-production"  # at the job level.
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

script

ランナーが実行するコマンドを指定するには、script を使用します。

トリガジョブを除くすべてのジョブは、script キーワードを必要とします。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：を含む配列：

CI/CD変数に対応しています。

script の例：

job1:
  script: "bundle exec rspec"

job2:
  script:
    - uname -a
    - bundle exec rspec

その他の詳細 ：

  • これらの特殊文字をscript で使用する場合は、シングルクォーテーション (') またはダブルクォーテーション (") を使用する必要があります。

関連トピック：

secrets

GitLab 13.4 で導入されました。

secrets を使ってCI/CD シークレットを指定します：

secrets:vault

GitLab 13.4 と GitLab Runner 13.4 で導入されました。

HashiCorp Vaultが提供するシークレットを指定するには、secrets:vault 。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • engine:name:シークレット・エンジンの名前。
  • engine:path:シークレットエンジンへのパス。
  • path:シークレットへのパス。
  • field:パスワードが格納されるフィールドの名前。

secrets:vault の例：

すべての詳細を明示的に指定し、KV-V2シークレットエンジンを使用する場合：

job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault:  # Translates to secret: `ops/data/production/db`, field: `password`
        engine:
          name: kv-v2
          path: ops
        path: production/db
        field: password

この構文を短くすることができます。この短い構文では、engine:name とengine:path のデフォルトは、どちらもkv-v2 になります：

job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault: production/db/password  # Translates to secret: `kv-v2/data/production/db`, field: `password`

短い構文でカスタムシークレットエンジンのパスを指定するには、@ で始まるサフィックスを追加します：

job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault: production/db/password@ops  # Translates to secret: `ops/data/production/db`, field: `password`

secrets:azure_key_vault

GitLab 16.3 と GitLab Runner 16.3 で導入されました。

Azure Key Vault が提供するシークレットを指定するにはsecrets:azure_key_vault を使用します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • name:シークレットの名前。
  • version:秘密のバージョン。

secrets:azure_key_vault の例：

job:
  secrets:
    DATABASE_PASSWORD:
      azure_key_vault:
        name: 'test'
        version: 'test'

関連トピック ：

secrets:file

GitLab 14.1 と GitLab Runner 14.1 で導入されました。

secrets:file を使って、シークレットをfile またはvariable タイプの CI/CD 変数として保存するように設定します。

デフォルトでは、シークレットはfile 型の CI/CD 変数としてジョブに渡されます。シークレットの値はファイルに保存され、変数にはファイルへのパスが含まれます。

もしあなたのソフトウェアがfile タイプの CI/CD 変数を使えない場合、file: false を設定してシークレットの値を変数に直接格納してください。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

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

secrets:file の例：

job:
  secrets:
    DATABASE_PASSWORD:
      vault: production/db/password@ops
      file: false

その他の詳細 ：

  • file キーワードはCI/CD変数の設定であり、vault セクションではなく、CI/CD変数名の下にネストされなければなりません。

secrets:token

GitLab 15.8で導入されました。

secrets:token を使用して、トークンの CI/CD 変数を参照し、Vault で認証する際に使用するトークンを明示的に選択します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • IDトークンの名前

secrets:token の例：

job:
  id_tokens:
    AWS_TOKEN:
      aud: https://aws.example.com
    VAULT_TOKEN:
      aud: https://vault.example.com
  secrets:
    DB_PASSWORD:
      vault: gitlab/production/db
      token: $VAULT_TOKEN

その他の詳細 ：

  • token キーワードが設定されていない場合、最初の ID トークンが認証に使用されます。
  • GitLab 15.8から15.11では、以下を有効にする必要があります。 Limit JSON Web Token(JWT) アクセスを制限します。を有効にする必要があります。
  • **Limit JSON Web Token(JWT) **アクセスを無効にすると、token キーワードは無視され、token CI/CD 変数が認証に使用されます。

services

スクリプトを正常に実行するために必要な追加のDockerイメージを指定するには、services 。services イメージ は、image キーワードで指定されたイメージにリンクされます。

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

可能な入力：サービスイメージの名前 (必要であればレジストリパスを含む)：

  • (latest タグと<image-name> 同じ <image-name>)
  • <image-name>:<tag>
  • <image-name>@<digest>

CI/CD 変数には対応していますが、 alias には対応していません。

services の例：

default:
  image:
    name: ruby:2.6
    entrypoint: ["/bin/bash"]

  services:
    - name: my-postgres:11.7
      alias: db-postgres
      entrypoint: ["/usr/local/bin/db-postgres"]
      command: ["start"]

  before_script:
    - bundle install

test:
  script:
    - bundle exec rake spec

この例では、GitLabはジョブのために2つのコンテナを起動します：

  • script コマンドを実行する Ruby コンテナ。
  • PostgreSQL コンテナ。Ruby コンテナ内のscript コマンドは、db-postgrest ホスト名の PostgreSQL データベースに接続できます。

関連トピック：

service:pull_policy

RunnerがDockerイメージを取得するために使用するプルポリシー。

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

可能な入力：

  • 単一のプルポリシー、または配列内の複数のプルポリシー。always 、if-not-present 、またはnever のいずれかです。

** service:pull_policy**の例：

job1:
  script: echo "A single pull policy."
  services:
    - name: postgres:11.6
      pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  services:
    - name: postgres:11.6
      pull_policy: [always, if-not-present]

その他の詳細 ：

  • ランナーが定義されたプルポリシーをサポートしていない場合、ジョブは以下のようなエラーで失敗します：ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never]).

関連トピック：

stage

stage を使用して、ジョブがどのステージで実行されるかを定義します。同じstage 内のジョブは並行して実行できます (Additional detailsを参照)。

stage が定義されていない場合、ジョブはデフォルトでtest のステージを使用します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：文字列：

stage の例：

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - echo "This job compiles code."

job2:
  stage: test
  script:
    - echo "This job tests the compiled code. It runs when the build stage completes."

job3:
  script:
    - echo "This job also runs in the test stage".

job4:
  stage: deploy
  script:
    - echo "This job deploys the code. It runs when the test stage completes."
  environment: production

その他の詳細 ：

  • ジョブは異なるRunner上で実行される場合、Parallelsで実行することができます。
  • ランナーが1つしかない場合、ランナーのconcurrent 設定 が1 より大きければ、ジョブは並行して実行できます。

stage: .pre

GitLab 12.4で導入されました。

.pre パイプラインの最初にジョブを実行するにはステージを使います。 .preユーザー定義のステージは、.pre. .pre stages で.pre定義する必要は .preありません。

パイプラインに.pre または.post ステージのジョブのみが含まれる場合、そのパイプラインは実行されません。異なるステージに少なくとも1つのジョブがなければなりません。

キーワードタイプ：ジョブのstage キーワードでのみ使用できます。

stage: .pre の例：

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "This job runs in the build stage."

first-job:
  stage: .pre
  script:
    - echo "This job runs in the .pre stage, before all other stages."

job2:
  stage: test
  script:
    - echo "This job runs in the test stage."

stage: .post

GitLab 12.4で導入されました。

.post パイプラインの最後にジョブを実行するためにステージを使います。 .postユーザー定義のステージは.post. .postNETの前に実行されます。stagesで.post定義する必要は .postありません。

パイプラインに.pre または.post ステージのジョブのみが含まれる場合、そのパイプラインは実行されません。異なるステージに少なくとも1つのジョブがなければなりません。

キーワードタイプ：ジョブのstage キーワードでのみ使用できます。

stage: .post の例：

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "This job runs in the build stage."

last-job:
  stage: .post
  script:
    - echo "This job runs in the .post stage, after all other stages."

job2:
  stage: test
  script:
    - echo "This job runs in the test stage."

その他の詳細

  • パイプラインにneeds: [] のジョブと.pre ステージのジョブがある場合、パイプラインが作成されると同時に、それらすべてが開始されます。needs: [] のジョブは、ステージ設定を無視してすぐに開始されます。

tags

tags を使って、プロジェクトで利用可能な全ての Runner のリストから特定の Runner を選択してください。

ランナーを登録する際、ランナーのタグを指定することができます（例：ruby 、postgres 、development ）。 ジョブをピックアップして実行するには、ジョブにリストされているすべてのタグをランナーに割り当てる必要があります。

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

可能な入力：

tags の例：

job:
  tags:
    - ruby
    - postgres

この例では、ruby とpostgres の両方のタグを持つ Runner だけがジョブを実行できます。

その他の詳細：

  • GitLab 14.3以降では、タグの数は50 以下でなければなりません。

関連トピック：

timeout

GitLab 12.3 で導入されました。

timeout を使って特定のジョブのタイムアウトを設定します。ジョブがタイムアウト時間を超えて実行されると、そのジョブは失敗します。

ジョブレベルのタイムアウトはプロジェクトレベルのタイムアウトより長くすることができますが、ランナーのタイムアウトより長くすることはできません。

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

可能な入力：自然言語で書かれた期間。例えば、これらはすべて等価です：

  • 3600 seconds
  • 60 minutes
  • one hour

timeout の例：

build:
  script: build.sh
  timeout: 3 hours 30 minutes

test:
  script: rspec
  timeout: 3h 30m

trigger

trigger を使用して、ジョブがダウンストリームパイプラインを開始する “トリガージョブ “であることを宣言します：

トリガージョブは、GitLab CI/CD設定キーワードの限られたセットだけを使うことができます。トリガジョブで使用できるキーワードは以下の通りです：

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

trigger の例：

trigger-multi-project-pipeline:
  trigger: my-group/my-project

その他の詳細 ：

関連トピック：

trigger:include

子パイプラインを開始する “トリガージョブ “であることを宣言するには、trigger:include を使用します。

動的な子パイプラインをトリガーするには、trigger:include:artifact を使用します。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

  • 子パイプラインの設定ファイルへのパス。

trigger:include の例：

trigger-child-pipeline:
  trigger:
    include: path/to/child-pipeline.gitlab-ci.yml

関連トピック ：

trigger:project

trigger:project を使って、ジョブがマルチプロジェクトパイプラインを開始する “トリガージョブ” であることを宣言します。

デフォルトでは、マルチプロジェクトパイプラインはデフォルトのブランチをトリガーします。別のブランチを指定するには、trigger:branch を使用してください。

キーワードの種類：ジョブキーワード。ジョブの一部としてのみ使用できます。

可能な入力：

trigger:project の例：

trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project

別のブランチの例trigger:project ：

trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project
    branch: development

関連トピック：

trigger:strategy

trigger:strategy を使用して、trigger ジョブが成功としてマークされる前に、ダウンストリームパイプラインの完了を待つようにします。

この動作は、ダウンストリームパイプラインが作成されるとすぐにtrigger ジョブが成功としてマークされるデフォルトとは異なります。

この設定により、パイプラインの実行は並列ではなく線形になります。

trigger:strategy の例：

trigger_job:
  trigger:
    include: path/to/child-pipeline.yml
    strategy: depend

この例では、後続ステージのジョブは、トリガーされたパイプラインが正常に完了するまで待ってから開始します。

その他の詳細 ：

  • ダウンストリームパイプラインのオプションの手動ジョブは、ダウンストリームパイプラインやアップストリームトリガージョブのステータスに影響しません。オプションの手動ジョブを実行しなくても、ダウンストリームパイプラインは正常に完了します。
  • ダウンストリーム パイプラインのブロック手動ジョブは、トリガ ジョブが成功または失敗としてマークされる前に実行する必要があります。ダウンストリームパイプラインのステータスが **手動ジョブのために手動アクション待ち () の場合 **、トリガジョブは保留中** () **を表示します。デフォルトでは、トリガジョブが完了するまで、後のステージのジョブは開始しません。
  • ダウンストリームパイプラインに失敗したジョブがあっても、そのジョブがallow_failure: true を使用している場合、ダウンストリームパイプラインは成功とみなされ、トリガジョブは成功を示します。

trigger:forward

trigger:forward を使って、ダウンストリームパイプラインに転送する内容を指定します。親子パイプラインと マルチプロジェクトパイプラインの両方に転送する内容を制御できます。

可能な入力：

trigger:forward の例：

CI/CD 変数MYVAR = my value を使って、手動でこのパイプラインを実行します：

variables: # default variables for each job
  VAR: value

# Default behavior:
# - VAR is passed to the child
# - MYVAR is not passed to the child
child1:
  trigger:
    include: .child-pipeline.yml

# Forward pipeline variables:
# - VAR is passed to the child
# - MYVAR is passed to the child
child2:
  trigger:
    include: .child-pipeline.yml
    forward:
      pipeline_variables: true

# Do not forward YAML variables:
# - VAR is not passed to the child
# - MYVAR is not passed to the child
child3:
  trigger:
    include: .child-pipeline.yml
    forward:
      yaml_variables: false

variables

variables を使用して、ジョブのCI/CD 変数を定義します。

キーワードタイプ：グローバルキーワードとジョブキーワード。グローバルレベルでもジョブレベルでも使用できます。

variables をグローバルキーワードとして定義した場合、すべてのジョブのデフォルト変数のように動作します。各変数はパイプラインが作成されるときにすべてのジョブ設定にコピーされます。ジョブが既にその変数を定義している場合、ジョブレベルの変数が優先されます。

グローバルレベルで定義された変数は、includeのような他のグローバルキーワードの入力として使用することはできません。これらの変数は、script、before_script、after_script セクション、およびrulesのようないくつかのジョブ・キーワードの入力として、ジョブ・レベルでのみ使用できます。

可能な入力：変数名と値のペア：

  • 名前には数字、アルファベット、アンダースコア (_) のみを使用できます。シェルによっては、最初の文字は文字でなければなりません。
  • 値は文字列でなければなりません。

CI/CD変数に対応しています。

** variables**の例：

variables:
  DEPLOY_SITE: "https://example.com/"

deploy_job:
  stage: deploy
  script:
    - deploy-script --url $DEPLOY_SITE --path "/"
  environment: production

deploy_review_job:
  stage: deploy
  variables:
    REVIEW_PATH: "/review"
  script:
    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH
  environment: production

その他の詳細 ：

関連トピック ：

variables:description

GitLab 13.7 で導入されました。

パイプラインレベル(グローバル)変数の説明を定義するには、description キーワードを使います。パイプラインを手動で実行する際に、変数名と共に説明が表示されます。

キーワードの種類グローバル・キーワード。ジョブレベル変数には使用できません。

可能な入力：

  • 文字列。

variables:description の例：

variables:
  DEPLOY_NOTE:
    description: "The deployment note. Explain the reason for this deployment."

その他の詳細 ：

  • value なしで使用された場合、変数は手動でトリガーされなかったパイプラインに存在し、デフォルト値は空文字列 ('') になります。

variables:value

GitLab 13.7 で導入されました。

パイプラインレベル(グローバル)変数の値を定義するには、value キーワードを使います。variables: descriptionと一緒に使うと、パイプラインを手動で実行するときに変数の値がプリフィルドされます。

キーワードの種類グローバル・キーワード。ジョブレベル変数には使用できません。

可能な入力：

  • 文字列。

variables:value の例：

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    description: "The deployment target. Change this variable to 'canary' or 'production' if needed."

その他の詳細 ：

variables:options

GitLab 15.7 で導入されました。

variables:options を使って、パイプラインを手動で実行する際にUIで選択可能な値の配列を定義します。

variables: value 、およびvalueで定義された文字列と一緒に使用する必要があります：

  • また、options 配列の文字列のいずれかでなければなりません。
  • デフォルトの選択です。

descriptionがない場合、このキーワードは何の効果もありません。

キーワードの種類グローバル・キーワード。ジョブレベル変数には使用できません。

可能な入力：

  • 文字列の配列。

variables:options の例：

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    options:
      - "production"
      - "staging"
      - "canary"
    description: "The deployment target. Set to 'staging' by default."

variables:expand

expand キーワードを使って、変数を拡張可能かどうかを設定します。

キーワード・タイプ：グローバルおよびジョブ・キーワード。グローバル・レベルでもジョブ・レベルでも使用できます。

可能な入力：

  • true (デフォルト）：変数は拡張可能。
  • false:変数は拡張可能ではありません。

variables:expand の例：

variables:
  VAR1: value1
  VAR2: value2 $VAR1
  VAR3:
    value: value3 $VAR1
    expand: false
  • VAR2 の結果はvalue2 value1。
  • VAR3 の結果はvalue3 $VAR1。

その他の詳細：

  • expand キーワードは、グローバルおよびジョブレベルのvariables キーワードでのみ使用できます。rules:variables またはworkflow:rules:variablesとは使用できません。

when

ジョブの実行時の条件を設定するには、when を使用します。ジョブで定義されていない場合、既定値はwhen: on_success です。

キーワード・タイプ：ジョブ・キーワード。ジョブの一部として使用できます。when: always およびwhen: never は、workflow:rulesでも使用できます。

可能な入力：

  • on_success (デフォルト)：ジョブの実行は、それ以前のステージのジョブが失敗しないか、allow_failure: true 。
  • on_failure:以前のステージのジョブが少なくとも1つ失敗した場合にのみジョブを実行します。以前のステージのジョブでallow_failure: true 、常に成功と見なされます。
  • never:以前のステージのジョブのステータスに関係なく、ジョブを実行しません。rules セクションまたはworkflow: rules でのみ使用できます。
  • always:前のステージのジョブのステータスに関係なくジョブを実行します。また、workflow:rules.
  • manual:手動でトリガーされたときのみジョブを実行します。
  • delayed:指定した時間だけジョブの実行を遅らせます。

when の例：

stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual
  environment: production

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

この例では、スクリプト

  1. build_job が失敗した場合のみ、cleanup_build_job を実行します。
  2. 成功、失敗にかかわらず、パイプラインの最後のステップとして常にcleanup_job を実行します。
  3. GitLab UIで手動で実行する場合、deploy_job 。

その他の詳細：

  • GitLab 13.5以降では、triggerと同じジョブでwhen:manual を使うことができます。GitLab 13.4 以前では、これらを一緒に使うとjobs:#{job-name} when should be on_success, on_failure or always というエラーが発生します。
  • allow_failure のデフォルトの動作はtrue に変わりますwhen: manual。 しかし when: manual、rulesと一緒に使うと、allow_failure のデフォルトはfalseになります。

関連トピック：

  • when rules と併用することで、よりダイナミックなジョブ制御が可能になります。
  • when をworkflow と併用することで、パイプラインの開始タイミングを制御することができます。

非推奨キーワード

以下のキーワードは非推奨です。

グローバルに定義された image、services、cache、before_script、after_script

image、services、cache、before_script、after_script をグローバルに定義することは非推奨です。 将来のリリースでサポートが削除される可能性があります。

代わりにdefault を使用してください。使用例：

default:
  image: ruby:3.0
  services:
    - docker:dind
  cache:
    paths: [vendor/]
  before_script:
    - bundle config set path vendor/bundle
    - bundle install
  after_script:
    - rm -rf tmp/