GitLab CI/CD パイプライン設定リファレンス

GitLab CI/CDパイプラインは、各プロジェクト内で.gitlab-ci.yml という YAML ファイルを使って設定します。

.gitlab-ci.yml ファイルはパイプラインの構造と順序を定義し、以下のことを決定します：

  • GitLab Runnerを使って実行する内容。
  • 特定の状況において、どのような判断をするか。例えば、処理が成功した場合と失敗した場合。

このトピックでは、CI/CDパイプラインの設定について説明します。その他のCI/CDの設定については、以下を参照してください。

  • GitLab CI/CDの変数、パイプラインの実行環境を設定するための内容です。
  • GitLab Runnerの高度な設定、GitLab Runnerを設定するための内容です。

パイプラインの完全な設定例を以下で紹介しています。

GitLab CI/CDについての追加情報はこちらをご覧ください。

注意: GitLab でプルミラーリングしているリポジトリがある場合は、プロジェクトの設定 > リポジトリ > リモートリポジトリからプル > ミラー更新のパイプラインのトリガーでパイプラインのトリガーを有効にする必要があります。

導入

パイプラインの設定はジョブから始まります。 ジョブは.gitlab-ci.yml ファイルの最も基本的な要素です。

ジョブは以下のようなものです。

  • どのような条件で実行されるべきかを示す制約とともに定義されます。
  • 任意の名前を持つトップレベル要素で」、少なくともscript 句を含んでいます。
  • 定義できる数に制限はありません。

使用例： 

job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"

上記の例は2つのジョブを別々に実行し、それぞれのジョブが異なるコマンドを実行する、最もシンプルなCI/CDの設定です。 もちろんコマンドは直接コードを実行したり(./configure;make;make install)、リポジトリ内のスクリプトを実行したり(test.sh)することができます。

ジョブはRunnerによってピックアップされ、Runnerの環境内で実行されます。重要なのは、それぞれのジョブが独立して実行されることです。

.gitlab-ci.ymlを検証する

GitLab CI/CDの各インスタンスにはLintと呼ばれるデバッグツールが組み込まれており、.gitlab-ci.yml ファイルの内容を検証するために使用できます。Lintはプロジェクト名前空間のci/lintページの下にあります。例えば、https://gitlab.example.com/gitlab-org/project-123/-/ci/lintです。

ジョブで利用できない名前

各ジョブには一意な名前が必要ですが、ジョブ名として使用できない予約keywords がいくつかあります：

  • image
  • services
  • stages
  • types
  • before_script
  • after_script
  • variables
  • cache
  • include

予約語の使用

特定の値(例えば、true やfalse)を使用する際にバリデーションエラーが発生する場合は、以下をお試しください：

  • それらを「”」で囲む。
  • それらを別の形に変更する。例えば、/bin/true。

設定パラメータ

ジョブは、ジョブの動作を定義するパラメータのリストとして定義されます。

次の表は、ジョブで使用可能なパラメータの一覧です。

キーワード 説明
script Runnerで実行されるシェルスクリプトです。
image Docker イメージを使用します。image:name とimage:entrypointも利用可能です。
services Docker サービスイメージを使用します。services:name、services:alias、services:entrypoint、services:commandも利用可能です。
before_script ジョブの前に実行されるコマンドを上書きします。
after_script ジョブの後に実行されるコマンドを上書きします。
stage ジョブステージを定義します（デフォルト：test）。
only どのような場合にジョブが作成されるかを制限します。only:refs、only:kubernetes、only:variables、only:changesも利用可能です。
except どのような場合にジョブが作成されないかを制限します。except:refs、except:kubernetes、except:variables、except:changesも利用可能です。
rules ジョブを作成する、または作成しないかどうかを判断するために評価する条件の一覧です。only/exceptと一緒に使用できません。
tags Runnerを選択する際に使用するタグの一覧です。
allow_failure ジョブの失敗を許可します。ジョブが失敗しても、パイプラインのステータスには影響しません。
when いつジョブを実行するかを決めます。when:manual、when:delayedも利用可能です。
environment ジョブをデプロイする環境の名前です。environment:name,environment:url,environment:on_stop,environment:auto_stop_in およびenvironment:actionも利用可能です。
cache 後続の処理でキャッシュされるべきファイルのリストです。cache:paths、cache:key、cache:untracked、cache:policyも利用可能です。
artifacts 成功した場合にジョブに添付するファイルとディレクトリのリストです。artifacts:paths、artifacts:exclude、artifacts:expose_as、artifacts:name、artifacts:untracked、artifacts:when、artifacts:expire_in、artifacts:reports、artifacts:reports:junit、artifacts:reports:cobertura、artifacts:reports:terraformが利用可能です。

GitLabEnterprise Editionでは、以下も利用可能です:artifacts:reports:codequality、artifacts:reports:sast、artifacts:reports:dependency_scanning、artifacts:reports:container_scanning、artifacts:reports:dast、artifacts:reports:license_scanning、artifacts:reports:license_management (GitLab 13.0で削除) 、artifacts:reports:performance、artifacts:reports:load_performance、artifacts:reports:metrics。
dependencies アーティファクトを取得するジョブのリストを与えることで、アーティファクトが渡されるジョブを制限します。
coverage ジョブのコードカバレッジを設定します。
retry ジョブが失敗した場合に、ジョブをいつ、何回自動リトライするかを設定します。
timeout プロジェクト全体の設定よりも優先される、ジョブレベルのタイムアウトを定義します。
parallel ジョブを並列に実行するインスタンス数を定義します。
trigger ダウンストリームのパイプライントリガーを定義します。
include このジョブが外部YAMLファイルを含むことを許可します。include:local、include:file、include:template、include:remoteも利用可能です。
extends このジョブが継承する項目を設定します。
pages GitLab Pagesで使用するために、ジョブの結果をアップロードします。
variables ジョブレベルでジョブ変数を定義します。
interruptible 新しいジョブによって、冗長なジョブをキャンセルできるかどうかを定義します。
resource_group ジョブの同時実行を制限します。
release Runnerにリリースオブジェクトを生成するよう指示します。
注意：パラメータtypes とtype は非推奨です。

グローバルパラメータ

一部のパラメータはグローバルレベルで定義する必要があり、パイプライン内のすべてのジョブに影響を与えます。

グローバルデフォルト

いくつかのパラメータは、default: キーワードを使用して、すべてのジョブのデフォルトとしてグローバルに設定することができます。 デフォルトのパラメータは、ジョブ固有の設定によって上書きすることができます。

以下のジョブパラメータはdefault: ブロック内で定義できます：

以下の例では、ruby:2.6 イメージを使用するrspec 2.6 ジョブを除くすべてのジョブで、ruby:2.5 イメージがデフォルトとして設定されています： 

default:
  image: ruby:2.5

rspec:
  script: bundle exec rspec

rspec 2.6:
  image: ruby:2.6
  script: bundle exec rspec

inherit

GitLab 12.9で導入されました。

グローバルに定義されたデフォルトや変数の継承を無効にするには、inherit: パラメータを使用します。

すべてのvariables: またはdefault: パラメーターの継承を有効または無効にするには、以下の書式を使用します：

  • default: true またはdefault: false
  • variables: true またはvariables: false

default: パラメーターのサブセットまたはvariables:のみを継承するには、継承したいものを指定します。リストにないものは継承されません。以下のいずれかの形式を使用します： 

inherit:
  default: [parameter1, parameter2]
  variables: [VARIABLE1, VARIABLE2]

または: 

inherit:
  default:
    - parameter1
    - parameter2
  variables:
    - VARIABLE1
    - VARIABLE2

下の例では:

  • rubocop:
    • 継承する: なし。
  • rspec:
    • 継承する: デフォルトのimage、WEBHOOK_URL 変数。
    • 継承しない: デフォルトのbefore_script 、DOMAIN 変数。
  • capybara:
    • 継承する: デフォルトのbefore_script 、デフォルトのimage。
    • 継承しない: DOMAIN変数、WEBHOOK_URL変数。
  • karma:
    • 継承する: デフォルトのimage、デフォルトのbefore_script、DOMAIN 変数。
    • 継承さしない: WEBHOOK_URL 変数。 
default:
  image: 'ruby:2.4'
  before_script:
    - echo Hello World

variables:
  DOMAIN: example.com
  WEBHOOK_URL: https://my-webhook.example.com

rubocop:
  inherit:
    default: false
    variables: false
  script: bundle exec rubocop

rspec:
  inherit:
    default: [image]
    variables: [WEBHOOK_URL]
  script: bundle exec rspec

capybara:
  inherit:
    variables: false
  script: bundle exec capybara

karma:
  inherit:
    default: true
    variables: [DOMAIN]
  script: karma

stages

stages は、ジョブを含有するステージを定義するために使用され、パイプラインに対してグローバルに定義されます。

stagesの仕様により、柔軟な多段パイプラインを構築できます。 stagesの要素の順序が、ジョブの実行順序を定義します：

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

3つのステージを定義した次の例を考えてみましょう。 

stages:
  - build
  - test
  - deploy
  1. はじめに、build のすべてのジョブが並列実行されます。
  2. build のジョブがすべて成功すると、test のジョブが並行して実行されます。
  3. test のジョブがすべて成功すると、deploy のジョブが並行して実行されます。
  4. deploy のすべてのジョブが成功した場合、コミットはpassedとしてマークされます。
  5. 前のジョブのいずれかが失敗した場合、コミットはfailed とマークされ、それ以降のステージのジョブは実行されません。

また、特筆すべきエッジケースが2つあります。

  1. .gitlab-ci.ymlにstages が定義されていない場合、build、test 、deploy がデフォルトでジョブのステージとして使用されます。
  2. ジョブがstageを指定しない場合、そのジョブはtest のステージに割り当てられます。

workflow:rules

GitLab 12.5で導入されました

トップレベルのworkflow: キーは、パイプライン全体に適用され、パイプラインが作成されるかどうかを決定します。現在、ジョブ内で定義されたrules: と同様に動作するように、単一のrules: キーを受け入れます。これは、パイプラインの動的な設定を可能にするためです。

GitLab CI/CD とworkflow: rulesを初めて使う場合は、workflow:rules テンプレート が役に立ちます。

独自のworkflow: rulesを定義するのに、現在利用可能な設定オプションがは以下の通りです：

  • ifルールを定義します。
  • when:always またはnever にのみ設定できます。設定しない場合の、デフォルト値はalwaysが設定されます。

if ルールのリストは、1がマッチするまで評価されます。 1つもマッチしない場合は、最後のwhen が使用されます： 

workflow:
  rules:
    - if: $CI_COMMIT_REF_NAME =~ /-wip$/
      when: never
    - if: $CI_COMMIT_TAG
      when: never
    - when: always

workflow:rules のテンプレート

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

一般的なシナリオのためにworkflow: rulesを設定するパイプラインで使用するテンプレートをあらかじめ用意しています。これらを使用することで、作業が容易になり、パイプラインの重複実行を防ぐことができます。

Branch-Pipelines テンプレートはブランチとタグに対してパイプラインを実行させます。

ブランチパイプラインのステータスは、そのブランチをソースとして使用するマージリクエスト内に表示されます。しかし、このパイプラインタイプは マージリクエストパイプライン、マージ結果のパイプラインやマージトレインのいかなる機能もサポートしません。 これらの機能を意図的に避けている場合は、このテンプレートを使用してください。

以下のようにincludedします。 

include:
  - template: 'Workflows/Branch-Pipelines.gitlab-ci.yml'

MergeRequest-Pipelines テンプレートは、デフォルトブランチ (通常はmaster)、タグ、すべてのタイプのマージリクエストパイプラインに対してパイプラインを実行します。前述のマージリクエスパイプライン機能のいずれかを使用する場合は、このテンプレートを使用してください。

以下のようにincludedします。 

include:
  - template: 'Workflows/MergeRequest-Pipelines.gitlab-ci.yml'

include

  • GitLab Premium 10.5 で導入されました。
  • 10.6からStarter、Premium、Ultimateで利用可能になりました。
  • 11.4でGitLab Coreに移動しました。

includeキーワードを使用すると、外部のYAMLファイルを含有することができます。これにより、CI/CDの設定を複数のファイルに分解し、長い設定ファイルの可読性を高めることができます。 また、テンプレートファイルを中央のリポジトリに保存し、プロジェクトにその設定ファイルを含めることも可能です。これは、すべてのプロジェクトのグローバルデフォルト変数など、設定の重複を避けるのに役立ちます。

include は外部の YAML ファイルの拡張子が.yml もしくは.yamlであることを必要とし、そうでなければ外部ファイルはインクルードされません。

include は以下のインクルード方法をサポートしています：

方法 説明
local ローカルのプロジェクトリポジトリからファイルをインクルードします。
file 別のプロジェクトリポジトリからのファイルをインクルードします。
remote リモートURLからのファイルをインクルードします。公開されている必要があります。
template GitLabが提供しているテンプレートをインクルードします。

include メソッドは変数展開をサポートしていません。

注意: すべてのメソッドに含まれる.gitlab-ci.ymlの設定は、パイプラインの作成時に評価されます。 設定は時間的にスナップショットであり、データベースに永続化されます。 参照された .gitlab-ci.ymlの設定を変更しても、次のパイプラインが作成されるまでGitLabに反映されません。

include で定義されているファイルは以下の通り：

  • .gitlab-ci.ymlにあるものをディープマージされます。
  • include キーワードの位置に関係なく、常に最初に評価され、.gitlab-ci.ymlの内容とマージされます。
ヒント: マージを使用して、ローカル定義に含まれる CI/CD の設定をカスタマイズして上書きします。.gitlab-ci.yml 内のローカル定義は、インクルードされた定義を上書きします。
注意:include によってソースされた異なる YAML ファイル間でYAML アンカーを使うことはサポートされていません。 同じファイル内のアンカーだけを参照する必要があります。 YAML アンカーを使う代わりに、extends キーワードを使うことができます。

include:local

include:local は.gitlab-ci.ymlと同じリポジトリのファイルをインクルードします。 これはルートディレクトリ (/) からの相対的なフルパスで参照されます。

使用できるのは、設定ファイルが置かれているブランチと同じブランチの Git で現在追跡されているファイルだけです。言い換えると、include:localを使う場合は、.gitlab-ci.yml とローカルファイルの両方が同じブランチにあることを確認しましょう。

すべてのネストされたインクルードは同じプロジェクトのスコープ内で実行されるので、ローカルインクルード、プロジェクトインクルード、リモートインクルード、テンプレートインクルードを使用することができます。

注意: Gitサブモジュールのパスを使ったローカルファイルのインクルードはサポートされていません。

使用例： 

include:
  - local: '/templates/.gitlab-ci-template.yml'
ヒント:ローカルインクルードは、追従しないシンボリックリンクの代わりとして使うことができます。

これは、短いローカルインクルードとして定義することができます。 

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

include:file

GitLab 11.7 で導入されました。

同じGitLabインスタンス下にある別の非公開プロジェクトのファイルをインクルードするには、include:fileを使います。 このファイルは、ルートディレクトリ(/)からの相対的なフルパスを使って参照されます。使用例： 

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'

refを指定することもできます。デフォルトはプロジェクトのHEAD です： 

include:
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: v1.0.0
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

すべてのネストされたインクルードはターゲットプロジェクトのスコープ内で実行されるので、ローカル(ターゲットプロジェクトからの相対的な)インクルード、プロジェクトインクルード、リモートインクルード、テンプレートインクルードを使用することができます。

include:remote

include:remote を使用すると、別の場所からのファイルをインクルードすることができます。 HTTP/HTTPS を使用して、完全な URL を使用して参照されます。リモートURLの認証スキーマはサポートされていないため、リモートファイルは単純なGETリクエストで公開されなければなりません。使用例： 

include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'

すべてのネストされたインクルードは、パブリックユーザとしてコンテキストなしで実行されるので、別のリモートまたはパブリックプロジェクト、またはテンプレートのみが許可されます。

include:template

GitLab 11.7 で導入されました。

include:template を使うと、GitLabに同梱されている.gitlab-ci.yml テンプレートをインクルードできます。

使用例： 

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

複数のファイルinclude:template： 

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

すべてのネストされたインクルードは、ユーザーの許可を得てのみ実行されるので、プロジェクトインクルード、リモートインクルード、テンプレートインクルードを使用することができます。

ネストされたインクルード

GitLab 11.9 で導入されました。

入れ子になったインクルードでは、インクルードのセットを構成することができます。

合計100個のインクルードは許可されていますが、重複したインクルードは設定エラーとみなされます。

GitLab 12.4以降、すべてのファイルを解決するための制限時間は30秒となっています。

includes その他の例

その他のincludes 例 のリストがあります。

パラメータの詳細

CI/CDパイプラインを設定するためのパラメータについて詳しく説明します。

image

ジョブで使用するDockerイメージを指定するために使用します。

使用例:

image:name

Dockerの拡張設定オプションです。

詳しくは、imageで利用可能な設定をご覧ください。

image:entrypoint

Dockerの拡張設定オプションです。

詳しくは、imageで利用可能な設定をご覧ください。

services

imageで指定されたベースイメージにリンクされたサービスDockerイメージを指定するために使用します。

使用例:

services:name

Dockerの拡張設定オプションです。

詳しくは、servicesで利用可能な設定をご覧ください。

services:alias

Dockerの拡張設定オプションです。

詳しくは、servicesで利用可能な設定をご覧ください。

services:entrypoint

Dockerの拡張設定オプションです。

詳しくは、servicesで利用可能な設定をご覧ください。

services:command

Dockerの拡張設定オプションです。

詳しくは、servicesで利用可能な設定をご覧ください。

script

script はジョブが必要とする唯一の必須キーワードです。 これはRunnerによって実行されるシェルスクリプトです。 使用例： 

job:
  script: "bundle exec rspec"

スクリプト用のYAMLアンカーが利用可能です。

このパラメータには、配列を使用して複数のコマンドを含めることもできます。 

job:
  script:
    - uname -a
    - bundle exec rspec
注意: script コマンドはシングルクォートもしくはダブルクォートで囲む必要がある場合があります。 たとえば、コロン (:)を含むコマンドはYAML パーサーが全体を “key: value” のペアではなく文字列として解釈するために、クォートで囲む必要があります。 特殊な文字を使うときは注意してください。:,{,},[,],,,&,*,#,?,|,-,<,>,=,!,%,@,`。

スクリプトコマンドのいずれかがゼロ以外の終了コードを返した場合、ジョブは失敗し、それ以降のコマンドは実行されません。この動作は、終了コードを変数に格納することで回避できます。 

job:
  script:
    - false || exit_code=$?
    - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;

before_script と after_script

GitLab 8.7 で導入され、GitLab Runner v1.2 が必要です。

before_script は、デプロイジョブを含む各ジョブの前に、任意のアーティファクトのリストア後に実行するコマンドを定義するために使用します。 これは配列でなければなりません。

before_script で指定されたスクリプトは、メインscriptで指定されたスクリプトと連結され、単一のシェルで一緒に実行されます。

after_script は、失敗したジョブも含めて、各ジョブの後に実行されるコマンドを定義するために使用されます。 これは配列でなければなりません。

after_script で指定されたスクリプトは、before_script やscript スクリプトとは別に、新しいシェルで実行されます。その結果として：

  • 現在の作業ディレクトリをデフォルトに戻します。
  • before_script やscriptで定義されたスクリプトによる変更にはアクセスできません：
    • script のスクリプトでエクスポートされた変数やコマンドのエイリアス。
    • before_scriptやscript のスクリプトによってインストールされたソフトウェアのように、（RunnerのExecutorに依存する）作業ツリー外の変更。
  • 5分にハードコードされた別のタイムアウトを持っています。詳細は関連するイシューを参照してください。
  • ジョブの終了コードには影響を与えないようにしてください。script セクションが成功し、after_script がタイムアウトまたは失敗した場合、ジョブはコード0 (Job Succeeded) で終了します。

ジョブごとに設定すれば、グローバルに定義されたbefore_script やafter_scriptを上書きすることが可能です： 

default:
  before_script:
    - global before script

job:
  before_script:
    - execute this instead of global before script
  script:
    - my command
  after_script:
    - execute this after my script

before_script と after_script では YAML アンカーを利用できます。

スクリプトの出力を色付け

スクリプトの出力は、ANSI エスケープコードを使って色をつけるか、ANSI エスケープコードを出力するコマンドやプログラムを実行することで色をつけることができます。

以下は、Bashでカラーコードを使用する例です。 

job:
  script:
    - echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again."

カラーコードをシェル変数で定義したり、カスタム環境変数でも定義することができるので、コマンドが読みやすく再利用しやすいです。

例えば、上記と同じ例で、before_scriptで定義された変数を使います： 

job:
  before_script:
    - TXT_RED="\e[31m" && TXT_CLEAR="\e[0m"
  script:
    - echo -e "${TXT_RED}This text is red,${TXT_CLEAR} but this part isn't${TXT_RED} however this part is again."
    - echo "This text is not colored"

以下は、PowerShellでカラーコードを使用する例です。 

job:
  before_script:
    - $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m"
  script:
    - Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again."
    - Write-Host "This text is not colored"

複数行のコマンド

| (リテラル) と> (折りたたみ) の YAML マルチラインブロックスカラーインジケータを使うことで、読みやすくするために長いコマンドを複数行のコマンドに分割できます。

警告:複数のコマンドが1つのコマンド文字列にまとめられている場合、最後のコマンドの失敗または成功のみが報告され、バグによりそれ以前のコマンドの失敗が不正に無視されます。 ジョブの成功がこれらのコマンドの成功または失敗に依存する場合は、コマンドを別々のscript: アイテムとして実行するか、必要に応じてコマンド文字列にexit 1 コマンドを適宜追加してください。

| (リテラル) YAML マルチラインブロックスカラーインジケータを使って、ジョブ記述のscript セクションに複数行にわたってコマンドを書くことができます。 それぞれの行は個別のコマンドとして扱われます。 最初のコマンドだけがジョブログで繰り返されますが、追加のコマンドは実行されます： 

job:
  script:
    - |
      echo "First command line."
      echo "Second command line."
      echo "Third command line."

上記の例では、ジョブログに以下のように表示されます。 

$ echo First command line # collapsed multi-line command
First command line
Second command line.
Third command line.

> (折りたたみ) YAML マルチラインブロックスカラーインジケータはセクション間の空行を新しいコマンドの開始として扱います： 

job:
  script:
    - >
      echo "First command line
      is split over two lines."

      echo "Second command line."

これは、> または| ブロックスカラーインジケータなしでマルチラインコマンドを書くのと同じように動作します： 

job:
  script:
    - echo "First command line
      is split over two lines."

      echo "Second command line."

上記の両方の例は、ジョブログに以下のように表示されます。 

$ echo First command line is split over two lines. # collapsed multi-line command
First command line is split over two lines.
Second command line.

> 、| ブロックスカラーインジケータが省略された場合、GitLab は空でない行を連結してコマンドを形成しますので、連結したときに実行できることを確認してください。

シェルのヒアドキュメントを|演算子や>演算子と一緒に使えます。 以下の例では、小文字を大文字に変換しています： 

job:
  script:
    - |
      tr a-z A-Z << END_TEXT
        one two three
        four five six
      END_TEXT

以下の結果になります。 

$ tr a-z A-Z << END_TEXT # collapsed multi-line command
  ONE TWO THREE
  FOUR FIVE SIX

stage

stage はジョブごとに定義され、グローバルに定義されたstages に依存します。ジョブを異なるステージにグループ化することができ、同じstage のジョブは (一定の条件の下で) 並列実行されます。使用例： 

stages:
  - build
  - test
  - deploy

job 0:
  stage: .pre
  script: make something useful before build stage

job 1:
  stage: build
  script: make build dependencies

job 2:
  stage: build
  script: make build artifacts

job 3:
  stage: test
  script: make test

job 4:
  stage: deploy
  script: make deploy

job 5:
  stage: .post
  script: make something useful at the end of pipeline

独自のRunnerを使用する

独自のRunnerを使用する場合、GitLab Runnerはデフォルトで一度に1つのジョブのみを実行します（詳細はRunnerグローバル設定のconcurrent フラグを参照）。

以下の場合に限り、ジョブは独自のRunner上で並列に実行されます。

  • 別々のRunnerで実行される場合。
  • Runner のconcurrent の設定を変更した場合。

.pre と .post

GitLab 12.4で導入されました。

以下のステージは、すべてのパイプラインで利用可能です。

  • .preは、常にパイプラインの最初のステージであることが保証されています。
  • .postは、常にパイプラインの最終ステージであることが保証されています。

ユーザー定義のステージは、.pre の後、.postの前に実行されます。

.gitlab-ci.ymlで順序がずれて定義されていても、.pre と.post の順序を変更することはできません。 例えば、以下は同等の設定です：

  • 順番通りに定義されている例: 

     stages:
   - .pre
   - a
   - b
   - .post

  • 順番がずれて定義されている例: 

     stages:
   - a
   - .pre
   - b
   - .post

  • 明示的に定義されていない例: 

     stages:
   - a
   - b
注意:.pre または.post ステージのジョブのみを含む場合、パイプラインは作成されません。

extends

GitLab 11.3 で導入されました。

extends はextends を使うジョブが継承するエントリー名を定義します。

これはYAMLアンカーを使う代替案で、もう少し柔軟で読みやすいです。 

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

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

上記の例では、rspec ジョブは.tests テンプレートジョブを継承しています。 GitLab はキーに基づいて逆ディープマージを実行します。 GitLab は以下を行います：

  • rspec の内容を.tests に再帰的にマージします。
  • キーの値はマージしません。

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

rspec:
  script: rake rspec
  stage: test
  only:
    refs:
      - branches
    variables:
      - $RSPEC
注意：script: rake test はscript: rake rspecで上書きされていることに注意してください。

rake testを含めたい場合は、before_script とafter_scriptを参照してください。

この例の .tests は隠しジョブですが、通常のジョブを継承することも可能です。

extends は複数レベルの継承をサポートしていますが、3つ以上のレベルを使用することは推奨されていません。 サポートされている最大入れ子レベルは10です。 次の例では2つのレベルの継承を行っています： 

.tests:
  only:
    - pushes

.rspec:
  extends: .tests
  script: rake rspec

rspec 1:
  variables:
    RSPEC_SUITE: '1'
  extends: .rspec

rspec 2:
  variables:
    RSPEC_SUITE: '2'
  extends: .rspec

spinach:
  extends: .tests
  script: rake spinach

GitLab 12.0以降では、複数の親を extends することも可能です。

マージの詳細

extends はハッシュをマージすることはできますが、配列をマージすることはできません。 マージに使用されるアルゴリズムは「最も近いスコープを優先」なので、最後のメンバーからのキーは常に他のレベルで定義されたものを上書きします。 たとえば、以下のようになります： 

.only-important:
  variables:
    URL: "http://my-url.internal"
    IMPORTANT_VAR: "the details"
  only:
    - master
    - stable
  tags:
    - production
  script:
    - echo "Hello world!"

.in-docker:
  variables:
    URL: "http://docker-url.internal"
  tags:
    - docker
  image: alpine

rspec:
  variables:
    GITLAB: "is-awesome"
  extends:
    - .only-important
    - .in-docker
  script:
    - rake rspec

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

rspec:
  variables:
    URL: "http://docker-url.internal"
    IMPORTANT_VAR: "the details"
    GITLAB: "is-awesome"
  only:
    - master
    - stable
  tags:
    - docker
  image: alpine
  script:
    - rake rspec

上の例では、以下に注意してください。

  • variables セクションはマージされましたが、URL: "http://my-url.internal"はURL: "http://docker-url.internal"で上書きされています。
  • tags: ['production'] はtags: ['docker']で上書きされています。
  • script がマージされたのではなく、script: ['echo "Hello world!"'] がscript: ['rake rspec']で上書きされています。配列はYAML アンカーを使って結合できます。

extends とinclude の併用

extends はincludeと組み合わせて、設定ファイル全体で動作します。

例えば、ローカルに以下のようなincluded.yml ファイルがある場合： 

.template:
  script:
    - echo Hello!

.gitlab-ci.ymlの中では 、次のように使うことができます： 

include: included.yml

useTemplate:
  image: alpine
  extends: .template

これは.template ジョブで定義されたecho Hello! を実行するuseTemplate というジョブを実行し、ローカルジョブで定義されているようにalpine Dockerイメージを使用します。

rules

GitLab 12.3 で導入されました。

rules キーワードは、ジョブをパイプラインに追加するかどうかを決定するジョブポリシーを設定する方法です。

一致するまで、個々のルール句のリストを順番に評価します。 一致した場合、設定に応じて、そのジョブはパイプラインに含まれるか、パイプラインから除外されます。 含まれる場合、ジョブには特定の属性が追加されます。

注意:rules はonly/exceptと組み合わせて使用できません。 これを実行しようとすると、linterは key may not be used with rules というエラーを返します。

ルール属性

rules で許可されるジョブ属性は以下の通りです：

  • when: 定義されていない場合、デフォルトはwhen: on_successです。
    • when: delayedとして使用する場合は、start_inも必要です 。
  • allow_failure: 定義されていない場合、デフォルトはallow_failure: falseです。

ルールがtrueと評価され、かつ when がnever以外の値を持つ場合、そのジョブはパイプラインに含まれます。

使用例： 

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'
      when: delayed
      start_in: '3 hours'
      allow_failure: true

将来的には、ルールに追加のジョブ設定が追加される可能性があります。 有用なものが利用できない場合は、イシューを開いてください。

ルールで使える条件句

利用可能なルールの条件句は以下の通りです。

条件句 説明
if if 文を評価することで、パイプラインからジョブを追加または除外します。only:variablesに似ています。
changes 変更されたファイルに基づいて、パイプラインからジョブを追加または除外します。only:changesと同じです。
exists 特定のファイルの存在に基づいて、パイプラインからジョブを追加または除外します。

一致するルールが見つかるまで、ルールは順番に評価されます。 一致するルールが見つかった場合は、パイプラインにジョブを追加するかどうかの属性がチェックされます。 属性が定義されていない場合は、デフォルトでは以下のようになります。

  • when: on_success
  • allow_failure: false

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

  • ルールがマッチし、when: on_success,when: delayed またはwhen: alwaysを持つ場合。
  • 一致するルールがなく、最後の節が(ルールのない)when: on_success,when: delayedまたはwhen: always の場合。

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

  • 一致するルールがなく、独立したwhen: on_success、when: delayed 、when: alwaysがない場合。
  • ルールがマッチし、when: never を属性として持つ場合。

例えば、if 節を使用して、ジョブが実行されるタイミングを厳密に制限します： 

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: manual
      allow_failure: true
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

この例では:

  • パイプラインがマージリクエストのためのものである場合、最初のルールが一致します。そのため、ジョブがマージリクエストパイプラインに追加され、その属性は次のようになります。
    • when: manual (手動ジョブ)
    • allow_failure: true (手動ジョブが実行されなくてもパイプラインの実行を継続します)
  • パイプラインがマージリクエストのためのものではない場合、最初のルールがマッチせず、2番目のルールが評価されます。
  • パイプラインがスケジュールされたパイプラインであれば、2 番目のルールが一致し、ジョブはスケジュールされたパイプラインに追加されます。 属性が定義されていないので、ジョブの属性は次のようになります。
    • when: on_success (デフォルト）
    • allow_failure: false (デフォルト）
  • それ以外のすべての場合、ルールが一致しないため、ジョブは他のパイプラインに追加されません。

次のように、いくつかのケースではジョブを除外し、それ以外のケースではすべてのジョブを実行するようにルールを定義することもできます。 

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: never
    - when: on_success
  • パイプラインがマージリクエストのためのものである場合、ジョブはパイプラインに追加されません。
  • パイプラインがスケジューリングされたパイプラインの場合、ジョブはパイプラインに追加されません。
  • それ以外の場合、when: on_successにより、ジョブはパイプラインに追加されます。
注意 最終ルールとしてwhen: on_success、always、delayed を使用した場合、2つのパイプラインが同時に開始されることがあります。 プッシュパイプラインとマージリクエストパイプラインの両方が、同じイベント (オープンしているマージリクエストのソースブランチへのプッシュ) によってトリガーされる可能性があります。 詳細については、rules とonly/when: on_successの重要な違いを参照してください。

rules とonly/exceptの違い

only/except で定義されたジョブは、デフォルトではマージリクエストパイプラインをトリガーしません。明示的にonly: merge_requestsを追加する必要があります。

rules で定義されたジョブは、すべてのタイプのパイプラインをトリガーできます。 それぞれのタイプを明示的に設定する必要はありません。

使用例： 

job:
  script: "echo This creates double pipelines!"
  rules:
    - if: '$CUSTOM_VARIABLE == "false"'
      when: never
    - when: always

$CUSTOM_VARIABLE が false の場合、このジョブは実行されませんが、プッシュ (ブランチ) パイプラインとマージリクエストパイプラインの両方を含む、他のすべてのパイプラインで実行されます。 この設定では、オープンしているマージリクエストのソースブランチにプッシュするたびに、パイプラインの重複を引き起こします。 同じジョブでプッシュとマージリクエストの両方のパイプラインを明示的に許可することで、同じ効果を得ることができます。

workflow: rules を使用して、許可されるパイプラインの種類を制限することをお勧めします。 マージリクエストパイプラインのみ、またはブランチパイプラインのみを許可することで、パイプラインの重複をなくすことができます。 あるいは、ルールをより厳しく書き換えたり、最後のwhen節 (always,on_success またはdelayed) を使用しないようにすることもできます。

また、only/except のジョブとrules のジョブを同じパイプラインで混在させることは推奨しません。YAML エラーは発生しないかもしれませんが、only/except とrulesのデフォルトの動作が異なるため、正確な実行動作のデバッグは複雑になります。

rules:if

rules:if 節は、単純なif 文を評価することで、ジョブがパイプラインに追加されるかどうかを決定します 。 if文がtrueであれば、そのジョブはパイプラインに含まれるか、パイプラインから除外かのどちらかになります。わかりやすく言えば、if のルールは次のいずれかと解釈できます：

  • 「このルールがtrueと評価された場合、ジョブを追加します。」(デフォルト)
  • (when: neverを追加することで)「このルールがtrueと評価される場合、ジョブを追加しません。」

rules:if は only:variables とは少し異なり、1つのルールに対して1つの式文字列のみを受け付け、それらの配列は受け付けません。評価する式の集合は、&& または || を使用して1つの式に結合することができ、変数をマッチする構文を使用します。

if: 節は、定義済みの環境変数またはカスタム環境変数の値に基づいて評価されます。

使用例： 

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
      when: always
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/'
      when: manual
      allow_failure: true
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible

ジョブのwhen を決定するロジックに関するいくつかの詳細：

  • 提供されたルールがどれもマッチしない場合、ジョブはwhen: never に設定され、パイプラインに含まれません。
  • 条件句のないルール、たとえばif やchangesのないwhen やallow_failureのルールは、常にマッチし、到達すれば常に使用されます。
  • ルールがマッチし、when の定義がない場合、ルールはジョブのデフォルトの on_success として when を使用します。
  • when はルールごとに1回、またはジョブレベルで1回定義してすべてのルールに適用することもできます。ジョブレベルでのwhenとルール内でのwhenを混在させることはできません。

$CI_PIPELINE_SOURCE 変数の値をチェックすることで、only/except キーワードと同様の動作をすることができます。

値 説明
push ブランチやタグを含む、git push イベントをトリガーとするパイプラインの場合。
web プロジェクトのCI/CD > パイプラインメニューから、GitLab UIのパイプライン実行ボタンを使って作成したパイプラインの場合。
trigger トリガートークンを使用して作成されたパイプラインの場合。
schedule スケジュールパイプラインの場合。
api パイプラインAPIで起動されたパイプラインの場合。
external GitLab以外のCIサービスを利用する場合。
pipelines CI_JOB_TOKEN でAPIを使用して作成したマルチプロジェクトパイプラインの場合。
chat GitLab ChatOps コマンドを使用して作成したパイプラインの場合。
webide WebIDEを使用して作成したパイプラインの場合。
merge_request_event マージリクエストが作成または更新されたときに作成されるパイプライン用。 マージリクエストパイプライン、マージ結果パイプライン、マージトレインを有効にするために必要です。
external_pull_request_event GitHub 上の外部プルリクエストが作成または更新されたとき。 詳細は外部プルリクエスト用のパイプラインを参照してください。
parent_pipeline rulesの親子パイプラインによってトリガされるパイプラインの場合、親パイプラインによってトリガされるように、子パイプラインの設定でこれを使用します。

使用例： 

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: manual
      allow_failure: true
    - if: '$CI_PIPELINE_SOURCE == "push"'

この例では、スケジュールされたパイプラインで手動ジョブとして、または (ブランチまたはタグへの) プッシュパイプラインで、(デフォルトの) when: on_success を指定して、ジョブを実行します。 他の種類のパイプラインにはジョブを追加することはありません。

他の使用例： 

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

この例では、マージリクエストパイプラインとスケジュールパイプラインで、when: on_success としてジョブを実行します。 他の種類のパイプラインでは実行されません。

その他、if 節でよく使われる変数：

  • if: $CI_COMMIT_TAG：タグに対して変更がプッシュされた場合。
  • if: $CI_COMMIT_BRANCH：変更が任意のブランチにプッシュされた場合。
  • if: '$CI_COMMIT_BRANCH == "master"'：変更がmasterにプッシュされた場合。
  • if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'：変更がデフォルトブランチ（通常はmaster）にプッシュされた場合。デフォルトブランチが異なる可能性のある複数のブランチで同じ設定を再利用する場合に便利です。
  • if: '$CI_COMMIT_BRANCH =~ /regex-expression/'：コミットブランチが正規表現にマッチした場合。
  • if: '$CUSTOM_VARIABLE !~ /regex-expression/'：カスタム変数のCUSTOM_VARIABLE が正規表現にマッチしない場合。
  • if: '$CUSTOM_VARIABLE == "value1"'：カスタム変数のCUSTOM_VARIABLE がvalue1と完全に一致する場合。
rules:changes

ジョブをパイプラインに追加すべきかどうかを判断するために、rules: changes 節は Git のプッシュイベントによって変更されたファイルをチェックします。

rules: changes はonly: changes やexcept: changesとまったく同じように動作し、パスの配列を受け取ります。 同様に、Git のプッシュイベントがない場合は常に true を返します。 ブランチパイプラインやマージリクエストパイプラインにのみ使用する必要があります。

使用例： 

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - changes:
        - Dockerfile
      when: manual
      allow_failure: true

この例では:

  • workflow: rules はすべてのジョブのマージリクエストパイプラインのみを許可します。
  • Dockerfile が変更された場合、ジョブを手動ジョブとしてパイプラインに追加し、(allow_failure: trueにより)ジョブがトリガーされなくてもパイプラインの実行を継続できるようにします。
  • Dockerfile が変更されていない場合、(when: neverと同じように)ジョブをパイプラインに追加しません。
rules:exists

GitLab 12.4で導入されました。

exists はパスの配列を受け取り、リポジトリにファイルとして存在する場合にマッチします。

使用例： 

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

また、グロブパターンを使用して、リポジトリ内の任意のディレクトリにある複数のファイルをマッチさせることもできます。

使用例： 

job:
  script: bundle exec rspec
  rules:
    - exists:
        - spec/**.rb
注意: パフォーマンス上の理由から、パターン付き ** の使用は 10000 回のチェックに制限されています。 10000 回目のチェック以降は、パターン付きグロブを使用したルールは常に一致します。
rules:allow_failure

GitLab 12.8で導入されました。

以下のように allow_failure: true により、rules:内でジョブの失敗を許可したり、手動ジョブがパイプラインの実行を止めないようにできます。 rules:を使用するすべてのジョブで、allow_failure:が定義されていない場合のデフォルトはallow_failure: falseです。

ルールレベルのrules:allow_failure オプションは、ジョブレベルのallow_failure オプションよりも優先され、特定のルールによってジョブがトリガされた場合にのみ適用されます。 

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

この例では、最初のルールがマッチした場合、ジョブはwhen: manual とallow_failure: trueを持ちます。

複雑なルール節

if、changes、existsの各節を AND で結合するには、これらを同じルールで使用します。

以下の例をご覧ください：

  • Dockerfile またはdocker/scripts/のファイルが変更され、かつ$VAR == "string value"の場合、手動ジョブが実行されます。
  • そうでなければ、ジョブはパイプラインに含まれません。 
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: '$VAR == "string value"'
      changes: # Will include the job and set to when:manual if any of the follow paths match a modified file.
        - Dockerfile
        - docker/scripts/*
      when: manual
  # - when: never would be redundant here, this is implied any time rules are listed.

only/except で現在利用可能なbranches やrefs のようなキーワードは、rules ではまだ利用できません。このようなキーワードは、この文脈での使用法や動作について個別に検討されているためです。今後のキーワードの改善については、rulesを改善するためのエピックで議論されており、誰でも提案や要望を追加することができます。

only/except (基本)

注意: rules構文は、ジョブを実行するかしないかを定義するための、より強力で改良された解決方法です。 パイプラインを最大限に活用するために、only/except の代わりにrules を使うことを検討してください。

only とexcept は、ジョブが作成されるタイミングを制限するジョブポリシーを設定する2つのパラメータです：

  1. only ジョブを実行するブランチとタグの名前を定義します。
  2. except ジョブを実行しないブランチとタグの名前を定義します。

ジョブポリシーの使い方には、いくつかのルールがあります。

  • only とexcept は一緒に使用できます。only とexcept の両方がジョブで定義されている場合、参照（ブランチやタグ）はonly とexceptでフィルタリングされます。
  • only とexcept では正規表現（サポートされている正規表現構文）を使用できます。
  • only およびexcept では、リポジトリパスを指定して、フォーク先でのジョブの実行を制限できます。

さらに、only とexcept では特別なキーワードを使用することができます：

値 説明
branches パイプラインのGit参照がブランチの場合。
tags パイプラインのGit参照がタグの場合。
api パイプラインAPIで起動されたパイプラインの場合。
external GitLab以外のCIサービスを利用する場合。
pipelines CI_JOB_TOKENを使用してAPIを使用して作成したマルチプロジェクトパイプラインの場合。
pushes ブランチやタグを含む、git push イベントをトリガーとするパイプラインの場合。
schedules スケジュールパイプラインの場合。
triggers トリガートークンを使用して作成されたパイプラインの場合。
web プロジェクトのCI/CD > パイプラインメニューから、GitLab UIのパイプライン実行ボタンを使って作成したパイプラインの場合。
merge_requests マージリクエストが作成または更新されたときに作成されるパイプライン用です。マージリクエストパイプライン、マージ結果パイプライン、マージトレインを有効にします。
external_pull_requests GitHub上の外部プルリクエストが作成または更新されたとき（詳細は外部プルリクエスト用のパイプラインを参照してください）。
chat GitLab ChatOps コマンドを使用して作成したパイプラインの場合。

以下の例では、job はissue-で始まるブランチに対してのみ実行され、それ以外のブランチではスキップされます： 

job:
  # use regexp
  only:
    - /^issue-.*$/
  # use special keyword
  except:
    - branches

パターンマッチはデフォルトで大文字小文字を区別します。/pattern/i のようにi フラグ修飾子を使うと、大文字小文字を区別しないパターンになります： 

job:
  # use regexp
  only:
    - /^issue-.*$/i
  # use special keyword
  except:
    - branches

以下の例では、タグがプッシュされた場合、APIトリガーで明示的にビルドがリクエストされた場合、スケジュールパイプラインの場合にjobが実行されます： 

job:
  # use special keywords
  only:
    - tags
    - triggers
    - schedules

リポジトリのパスを使用して、親リポジトリに対してのみジョブを実行させ、フォークされたリポジトリに対しては実行させないようにできます。 

job:
  only:
    - branches@gitlab-org/gitlab
  except:
    - master@gitlab-org/gitlab
    - /^release/.*$/@gitlab-org/gitlab

上記の例では、master と名前の先頭にrelease/が付いているブランチを除く、gitlab-org/gitlab上のすべてのブランチに対してjob を実行します。

ジョブにonly のルールがない場合、デフォルトでonly: ['branches', 'tags'] が設定されます。except のルールがない場合、空白になります。

例えば、 

job:
  script: echo 'test'

は以下のように解釈されます。 

job:
  script: echo 'test'
  only: ['branches', 'tags']

正規表現

@は参照のリポジトリパスの先頭を表すために使用されるため、正規表現で@文字を含む参照名にマッチさせるには、16 進文字コード\x40を使用する必要があります。

タグやブランチ名だけが正規表現でマッチできます。リポジトリのパスが与えられている場合は、文字列としてのみマッチします。

タグ名やブランチ名に正規表現を使用してマッチさせる場合、参照名の全体が正規表現にマッチする必要があり、正規表現は/で囲まれていなければなりません(正規表現のフラグは終わりの/の後ろに追加してください)。そのため、issue-/.*/はissue-で始まるタグ名やブランチ名にはマッチしません。

ヒント 正規表現がタグ名やブランチ名の部分文字列だけにマッチするのを避けるには、^ と$ アンカーを使います。 たとえば、/issue/ だけだとsevere-issuesというブランチにもマッチしますが、（/^issue-/と同等の）/^issue-.*$/はマッチしません。

only/except でサポートされる正規表現

警告:これは GitLab 11.9.4 で導入された破壊的な変更です。

GitLab 11.9.4で、only とexcept で使われる正規表現を、内部的にRE2で変換するようになりました。

これはRuby正規表現のサブセットのみを利用できることを意味します。RE2では計算の複雑さから利用できる機能が制限されており、否定の先読みのように、GitLab 11.9.4から利用できなくなった機能もあります。

GitLab 11.9.7 から GitLab 12.0 までのバージョンでは、GitLab は管理者が有効にすることができる機能フラグを提供しています。 これにより、以前に許可されていた構文のバージョンとの互換性を保持することができ、ユーザーは新しい構文への移行をスムーズに行うことができます。 

Feature.enable(:allow_unsafe_ruby_regexp)

only/except (上級)

警告：これは_アルファ版の_機能であり、予告なしに変更されることがあります！

GitLabは単純な設定と複雑な設定の両方をサポートしているので、配列やハッシュのスキームを利用することができます。

以下の4つのキーが利用可能です。

  • refs
  • variables
  • changes
  • kubernetes

only またはexceptの下で複数のキーを使用した場合、キーは結合された単一式として評価されます。 つまり、以下のようになります：

  • only: は「すべての条件が一致したらこのジョブを含める」ことを意味します。
  • except: は、「いずれかの条件が一致したらこのジョブを除外する」ことを意味します。

onlyでは、個々のキーは論理的にANDで結合されます：

(any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active)

以下の例では、test ジョブは以下のonlyすべて がtrueのときに作成されます：

  • スケジュールパイプライン、またはmasterで実行されているパイプライン。
  • variables キーワードがマッチいている。
  • プロジェクトのkubernetes サービスがアクティビティである。 
test:
  script: npm run test
  only:
    refs:
      - master
      - schedules
    variables:
      - $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/
    kubernetes: active

except は、この評価式全体の否定として実装されています：

NOT((any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active))

この関係式は、ORを使用して、次のように表現できます。

(any of refs) OR (any of variables) OR (any of changes) OR (if Kubernetes is active)

以下の例では、test ジョブは以下のいずれかがtrueの場合は作成されません：

  • masterで実行されているパイプライン。
  • リポジトリのルートディレクトリにあるREADME.md ファイルが変更されている。 
test:
  script: npm run test
  except:
    refs:
      - master
    changes:
      - "README.md"

only:refs/except:refs

refs ポリシーはGitLab 10.0で導入されました。

refs キーは、単純なonly/except設定と同じ値を取ることができます。

以下の例では、スケジュールパイプラインの場合、またはmasterブランチで実行されたパイプラインの場合にのみ、deploy ジョブが作成されます： 

deploy:
  only:
    refs:
      - master
      - schedules

only:kubernetes/except:kubernetes

kubernetes ポリシーはGitLab 10.0で導入されました。

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

以下の例では、deploy ジョブは、プロジェクト内で Kubernetes サービスがアクティブな場合にのみ作成されます： 

deploy:
  only:
    kubernetes: active

only:variables/except:variables

variables ポリシーは GitLab 10.7 で導入されました。

variables キーワードは変数の評価式を定義するために使われます。言い換えると、定義済みの変数、プロジェクト変数、グループ変数、環境変数を使って、GitLabがジョブを作成するかどうかを決定するための評価式を定義することができます。

変数の評価式の使用例: 

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

もう1つの使用例では、コミットメッセージによってジョブを除外しています。 

end-to-end:
  script: rake test:end-to-end
  except:
    variables:
      - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/

変数の評価式の詳細はこちらをご覧ください。

only:changes/except:changes

changes ポリシーが導入されました。

changes キーワードをonly またはexcept と一緒に使うことで、Git のプッシュイベントによって変更されたファイルに基づいてジョブを作成するかどうかを定義することができます。

つまり、only:changes のポリシーは、以下のようなパイプラインに有効です：

  • $CI_PIPELINE_SOURCE == 'push'
  • $CI_PIPELINE_SOURCE == 'merge_request_event'
  • $CI_PIPELINE_SOURCE == 'external_pull_request_event'

上記3つ以外のソースを持つパイプラインのように、Gitのプッシュイベントがない場合、changes は指定されたファイルが新しいか古いかを判断することができず、常にtrueを返します。

基本的なonly: changesの使用例： 

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

上のシナリオでは、GitLab の既存のブランチにコミットをプッシュすると、docker build のジョブが作成されます。ただし、コミットのひとつに次のいずれかの変更が含まれている必要があります：

  • Dockerfile ファイル。
  • docker/scripts/ ディレクトリ内の任意のファイル。
  • dockerfiles ディレクトリとサブディレクトリ内の任意のファイル。
  • more_scripts ディレクトリ内のrb、py、sh の拡張子を持つファイル。
警告:only:changes を使って、パイプラインが成功した場合にのみマージリクエストを許可するようにした場合、only:merge_requestsも使していないと、望ましくない動作が発生する可能性があります。

グロブパターンを使ってリポジトリのルートディレクトリやリポジトリ内の_任意の_ディレクトリにある複数のファイルにマッチさせることもできますが、二重引用符でくくらないと GitLab は.gitlab-ci.ymlのパースに失敗します。使用例： 

test:
  script: npm run test
  only:
    changes:
      - "*.json"
      - "**/*.sql"

次の例は、リポジトリのルートディレクトリにある拡張子.md のファイルに変更が検出された場合、build ジョブをスキップします： 

build:
  script: npm run build
  except:
    changes:
      - "*.md"
警告: この機能をマージリクエストパイプラインで使用せず、新しいブランチやタグで使用する際には、注意すべき点がいくつかあります。
警告：この機能をスケジュールパイプラインで使用する際には、いくつかの注意点があります。
マージリクエストパイプラインで only:changes を使用する

マージリクエストパイプラインを使用すると、マージリクエストで変更されたファイルに基づいて作成されるジョブを定義することができます。

ソースブランチの正しいベース SHA を推測するために、このキーワードをonly: [merge_requests]と組み合わせることをお勧めします。こうすることで、それ以降のコミットからファイルの差分が正しく計算され、マージリクエストのすべての変更がパイプラインで正しくテストされます。

使用例： 

docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    refs:
      - merge_requests
    changes:
      - Dockerfile
      - service-one/**/*

上記のシナリオでは、service-one ディレクトリのファイルかDockerfileのどちらかを変更するマージリクエストが作成または更新された場合、GitLab はdocker build service one ジョブを実行します。

マージリクエストパイプラインとonly: [change]が組み合わされても、only: [merge_requests] を省略した場合、望ましくない動作が起こる可能性があることに注意してください。

使用例： 

docker build service one:
  script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG .
  only:
    changes:
      - Dockerfile
      - service-one/**/*

上の例では、service-one/**/*内のファイルへの変更が原因でパイプラインが失敗する可能性があります。その後、このファイルへの変更は含まず、 Dockerfileファイルへの変更を含むコミットがプッシュされ、Dockerfileの変更だけをテストするのでパイプラインが成功する可能性があります。GitLab は、まだ修正されていない変更が原因で失敗したパイプラインにもかかわらず、成功している最新のパイプラインをチェックして、マージリクエストをマージ可能として表示します。

この設定では、最新のパイプラインが以前のパイプラインで発生した失敗を適切に修正しているかどうかを確認する必要があります。

マージリクエストパイプライン以外で only:changes を使用する

マージリクエストパイプライン以外では、パイプラインはマージリクエストと関連づけられていないブランチやタグ上で実行されます。この場合、直近の SHA を用いて差分が計算されます。これは git diff HEAD~ と同等です。これは、次のように想定外の動作を引き起こす可能性があります：

  • 新しいブランチや新しいタグを GitLab にプッシュする際には、このポリシーは常に「true」と評価されます。
  • 新しいコミットをプッシュすると、直近のコミットをベースSHAとして、変更されたファイルが計算されます。
スケジュールパイプラインでonly:changes を使用する

スケジュールパイプラインでは、only:changesは常に「true」として評価されます。

needs

  • GitLab 12.2で導入されました。
  • GitLab 12.3では、needs 配列のジョブ数の最大値が5から50に引き上げられました。
  • GitLab 12.8で導入された needs: [] は、ジョブをすぐに開始できるようにします。

needs: キーワードを使用すると、.gitlab-ci.ymlで有向非巡回グラフ(DAG)を実装でき、ジョブの実行順を柔軟にできます。

これにより、いくつかのジョブを他のジョブを待たずに実行することができ、ステージの順番を無視して複数のステージを同時に実行することができます。

次の例を考えてみましょう。 

linux:build:
  stage: build

mac:build:
  stage: build

lint:
  stage: test
  needs: []

linux:rspec:
  stage: test
  needs: ["linux:build"]

linux:rubocop:
  stage: test
  needs: ["linux:build"]

mac:rspec:
  stage: test
  needs: ["mac:build"]

mac:rubocop:
  stage: test
  needs: ["mac:build"]

production:
  stage: deploy

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

  • Linter:lint のジョブはneedsがない(needs: [])ので、build ステージの完了を待たずにすぐに実行されます。

  • Linux パス:linux:rspec とlinux:rubocop ジョブは、mac:build ジョブの終了を待たずに、linux:build ジョブが終了するとすぐに実行されます。

  • macOS パス:mac:rspec とmac:rubocop ジョブは、linux:build ジョブの終了を待たずに、mac:build ジョブが終了するとすぐに実行されます。

  • production ジョブは、前のジョブがすべて終了するとすぐに実行されます。この場合、linux:build、linux:rspec、linux:rubocop、mac:build、mac:rspec、mac:rubocopが前のジョブに該当します。

要件と制限

  • needs: が only/except ルールのために作成されていないジョブやそもそも存在しないジョブを指すように設定されている場合は、YAML エラーのパイプラインが作成されます。
  • needs:配列で1つのジョブが必要とするジョブの最大数は制限されています。
    • GitLab.com の場合、制限は 10 です。 詳細については、インフラの課題を参照してください。
    • セルフマネージド型インスタンスの場合、以下の制限があります。
      • ci_dag_limit_needs機能フラグが有効な場合(デフォルト)の制限は10です。
      • ci_dag_limit_needs機能フラグが無効な場合の制限は50です。
  • needs:の参照するジョブがparallel:としてマークされている場合は、そのジョブの実行は、すべての並列ジョブに依存します。
  • 前のステージのジョブを使う必要がある点で、needs: と dependencies: は似ています。つまり、循環的な依存関係を作ることはできません。 今のところ、同じステージのジョブに依存できませんが、サポートの予定があります。
  • 上記と関連して、キーワードneeds:を持つまたは参照されるすべてのジョブで、明示的にステージを定義する必要があります。
needs:ジョブの制限を変更する

needs:内で定義できる最大ジョブ数のデフォルトは10ですが、フィーチャーフラグを使って50に変更することができます。 50に変更するには、Railsコンソールセッションを起動して、以下を実行します： 

Feature::disable(:ci_dag_limit_needs)

10に戻すには、反対に次のコマンドを実行します。 

Feature::enable(:ci_dag_limit_needs)

needsでアーティファクトのダウンロード

GitLab 12.6 で導入されました。

needsを使用する場合、アーティファクトのダウンロードは、artifacts: true（デフォルト）またはartifacts: falseで制御されます。

GitLab 12.6以降、ジョブでアーティファクトのダウンロードを制御するために、dependenciesキーワードとneedsを組み合わせて使用できません。needsを使用しないジョブでは、dependenciesは有効なキーワードとして使用できます。

以下の例では、rspecジョブではbuild_jobのアーティファクトをダウンロードしますが、rubocopジョブではダウンロードしません。 

build_job:
  stage: build
  artifacts:
    paths:
      - binaries/

rspec:
  stage: test
  needs:
    - job: build_job
      artifacts: true

rubocop:
  stage: test
  needs:
    - job: build_job
      artifacts: false

さらに、以下の3つの構文の例では、rspec ジョブは、artifacts がbuild_job_1に対してtrueであり、build_job_2 とbuild_job_3の両方に対してデフォルトのtrueであるため、3つのbuild_jobsすべてからアーティファクトをダウンロードします。 

rspec:
  needs:
    - job: build_job_1
      artifacts: true
    - job: build_job_2
    - build_job_3

needs を使用してプロジェクト横断のアーティファクトをダウンロード

GitLab 12.7 で導入されました。

needs を使用すると、同じプロジェクト内の他の参照（ブランチ、またはタグ）、または異なるプロジェクト内のパイプラインの最大5つのジョブからアーティファクトをダウンロードできます： 

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

build_job は、group/project-name プロジェクトのmaster ブランチで成功した最新のbuild-1 ジョブからアーティファクトをダウンロードします。

同一プロジェクト内のパイプライン間でのアーティファクトのダウンロード

needsは、projectキーワードとして現在のプロジェクトを指定することで、現在のプロジェクトの他のパイプラインのアーティファクトをダウンロードするために使用できます。また、ダウンロード先の参照を指定することもできます。次の例では、build_jobは、最新の成功したbuild-1ジョブのアーティファクトを、other-refを指定してダウンロードします。 

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: group/same-project-name
      job: build-1
      ref: other-ref
      artifacts: true
注意: parallel:で実行されているジョブからのアーティファクトのダウンロードはサポートされていません。

tags

tags は、このプロジェクトの実行が許可されているすべてのRunnerから特定のRunnerを選択するために使用します。

Runnerの登録中に、Runnerのタグを指定することができます（例：ruby、postgres、development）。

tags を使用すると、指定されたタグが割り当てられたRunnerでジョブを実行できます： 

job:
  tags:
    - ruby
    - postgres

上記の設定では、ruby とpostgres の両方のタグが定義されているRunnerによって、job がビルドされます。

タグはまた、異なるプラットフォーム上で異なるジョブを実行するための素晴らしい方法です。例えば、タグosx を持つ OS X Runner とタグwindowsを持つ Windows Runner がある場合、以下のジョブはそれぞれのプラットフォーム上で実行されます： 

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

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

allow_failure

allow_failureを使用すると、ジョブの失敗がパイプラインの他の部分に影響しないようにできます。when: manual構文を使用する手動ジョブを除いて、allow_failureのデフォルト値はfalseです。rules:構文で使用する場合は、when: manualジョブを含めて、allow_failureのデフォルト値はfaseです。

allow_failureを有効にしてジョブが失敗した場合、ジョブはUI上でオレンジ色の警告を表示しますが、パイプラインの論理フローはジョブが成功したとみなし、ブロックされません。

他のすべてのジョブが成功したと仮定すると、ジョブのステージとそのパイプラインは同じオレンジ色の警告を表示します。 しかし、関連するコミットは警告なしで「成功」とマークされます。

以下の例では、job1とjob2は並列に実行されます。job1はallow_failure: trueとマークされているため、たとえ失敗しても、次のステージの実行が停止することはありません。 

job1:
  stage: test
  script:
    - execute_script_that_will_fail
  allow_failure: true

job2:
  stage: test
  script:
    - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
    - deploy_to_staging

when

when は、ジョブが失敗した場合や失敗したにもかかわらず実行されるジョブを制御するために使用されます。

when には以下のいずれかの値を設定できます：

  1. on_success - 前のステージのすべてのジョブが成功した(あるいは、allow_failureとマークされているため成功したとみなされる)場合にのみジョブを実行します 。 これがデフォルトです。
  2. on_failure - 前のステージのジョブが少なくとも1つ失敗した場合にのみジョブを実行します。
  3. always - 前のステージのジョブのステータスに関係なく、ジョブを実行します。
  4. manual - ジョブを手動で実行します(GitLab 8.10で追加されました)。詳細は、以下のマニュアルアクションを参照してください。
  5. delayed - 一定期間後にジョブを実行します（GitLab 11.14で追加）。詳細は、以下の遅延アクションを参照してください。

使用例： 

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

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

上記のスクリプトは:

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

when:manual

  • GitLab 8.10 で導入されました。
  • 手動アクションのブロッキングがGitLab 9.0で導入されました。
  • 保護アクションがGitLab 9.2で導入されました。

手動アクションは、自動的に実行されるのではなく、ユーザーが明示的に起動する必要がある特殊なタイプのジョブです。 手動アクションの使用例としては、本番環境へのデプロイが挙げられます。 手動アクションは、パイプライン、ジョブ、環境、デプロイの各画面から起動することができます。 詳細については、環境のドキュメントを参照してください。

手動アクションの動作として、オプションとブロックがあります。 手動アクションをブロックすると、そのアクションが定義されたステージでパイプラインの実行がブロックされます。 ブロックされた手動アクションを実行した人が_Play_ボタンをクリックすると、パイプラインの実行を再開することができます。

パイプラインがブロックされていると、「パイプラインが成功した時にマージ」が設定されている場合はマージされません。 ブロックされたパイプラインには manual と呼ばれる特別なステータスを持ちます。 when:manual 構文を使用すると、手動アクションはデフォルトではブロックしない動作になります。 手動アクションをブロッキする動作にしたい場合は、.gitlab-ci.ymlでジョブの定義にallow_failure: false を追加する必要があります。

オプションの手動アクションはデフォルトで allow_failure: true が設定されており、その成否はパイプライン全体のステータスには寄与しません。 つまり、たとえ手動アクションが失敗しても、パイプラインは成功と判定されます。

注意: rules:を使用する場合、手動ジョブを含め、allow_failure のデフォルト値は false になります。

手動アクションは書き込みアクションとみなされるので、ユーザーがアクションを起動する際は、保護ブランチのパーミッションが使用されます。言い換えると、パイプラインの手動アクションを起動するには、そのブランチをマージする権限が必要です。保護環境を利用して、不正なユーザーによって実行されないように、より厳密に手動デプロイを保護することが可能です。

注意：when:manual とtrigger を一緒に使用すると、jobs:#{job-name} when should be on_success, on_failure or alwaysというエラーが発生します。これは、when:manual がトリガーの使用を妨げているためです。
手動ジョブを保護する

保護環境を使用して、手動ジョブの実行を許可されたユーザーを定義することができます。 保護環境に関連付けられたユーザーのみが手動ジョブを実行することを許可することで、以下のようないくつかの特別なユースケースを実装することが可能です。

  • より正確に誰が環境にデプロイできるかを制限します。
  • 承認されたユーザーが「承認」するまでパイプラインをブロックできるようにします。

このためには:

  1. ジョブにenvironment を追加します。使用例： 

    deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
    - master

  2. 保護環境の設定で、環境 ( 上の例ではproduction ) を選択し、手動ジョブの実行を許可するユーザー、ロール、グループをAllowed to Deployリストに追加します。 このリストに含まれるユーザーだけがこの手動ジョブを実行することができます。

さらに、allow_failure: falseを追加してブロックする手動ジョブとして定義した場合、手動ジョブが実行されるまでパイプラインの次のステージは実行されません。 これは、ブロックする手動ジョブを実行することで、後のパイプラインステージの実行を「承認」することを許可されたユーザーのリストを定義するために使用できます。

when:delayed

GitLab 11.4で導入されました。

遅延ジョブは、一定期間後にスクリプトを実行するためのものです。これは、すぐにジョブがpending状態になるのを避けたい場合に便利です。

start_inキーで期間を設定できます。start_in キーの値は、単位が指定されていない限り、経過時間を秒単位で表します。start_inキーは1週間以内でなければなりません。有効な値の例としては、以下のようなものがあります。

  • '5'
  • 10 seconds
  • 30 minutes
  • 1 day
  • 1 week

ステージ内に遅延ジョブがある場合、遅延ジョブが終了するまでパイプラインは進行しません。つまり、このキーワードは、異なるステージ間に遅延を挿入する場合にも使用できます。

遅延ジョブのタイマーは、前のステージが終了した直後に開始されます。 他のタイプのジョブと同様に、遅延ジョブのタイマーは前のステージが成功しない限り開始しません。

次の例では、前のステージが完了してから30分後に実行されるtimed rollout 10%という名前のジョブを作成します。 

timed rollout 10%:
  stage: deploy
  script: echo 'Rolling out 10% ...'
  when: delayed
  start_in: 30 minutes

(Unschedule) ボタンをクリックすることで、遅延ジョブのタイマーを停止することができます。 このジョブは、手動でジョブを実行しない限り実行されることはありません。

Playボタンをクリックすると、遅延ジョブをすぐに開始することができます。GitLab Runnerがすぐにジョブをピックアップして、ジョブを開始します。

environment

environment は、特定の環境にデプロイするためのジョブを定義するために使用されます。environment が指定され、その名前の環境が存在しない場合、自動的に新しい環境が作成されます。

最も単純な形では、environment キーワードは次のように定義できます： 

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

上記の例では、deploy to production のジョブはproduction 環境にデプロイするものとしてマークされます。

environment:name

  • GitLab 8.11 で導入されました。
  • GitLab 8.11以前では、環境名はenvironment: productionのような文字列で定義することができました。現在では、name キーワードで定義することが推奨されています。
  • name パラメータは、事前定義済み変数やセキュア変数や.gitlab-ci.yml variablesを含む、定義されたの CI 変数を使用することができます。 しかし、scriptで定義された変数を使用することはできません。

environmentの名前には以下を使用できます：

  • 半角英字
  • 半角数字
  • スペース
  • -
  • _
  • /
  • $
  • {
  • }

一般的な名前は、qa、staging、productionですが、ワークフローに適した任意の名前を使うことができます。

environmentキーワードの直後に環境名を定義する代わりに、別の値として定義することも可能です。その場合は、environmentの下にあるname キーワードを使用します： 

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

environment:url

  • GitLab 8.11 で導入されました。
  • GitLab 8.11以前では、URLはGitLabのUIでしか追加できませんでした。現在では、.gitlab-ci.ymlで定義することが推奨されています。
  • url パラメータは、事前定義済み変数やセキュア変数や.gitlab-ci.yml variablesを含む、定義されたの CI 変数を使用することができます。 しかし、scriptで定義された変数を使用することはできません。

これはオプションの値で、設定すると GitLab のさまざまな場所にボタンが表示され、クリックすると定義された URL に移動します。

下の例において、ジョブが正常に終了すると、マージリクエストと環境/デプロイページにhttps://prod.example.comを指し示すボタンが作成されます。 

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

environment:on_stop

  • GitLab 8.13 で導入されました。
  • GitLab 8.14 以降では、ストップアクションが定義されている環境では、関連するブランチが削除されたときに自動的にストップアクションが実行されます。

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

例については、environment:action のセクションをお読みください。

environment:action

GitLab 8.13 で導入されました。

action キーワードはon_stop とともに使用され、環境を閉じるために呼び出されるジョブで定義されます。

使用例: 

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review_app

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

上記の例では、review環境にデプロイするためにreview_app ジョブを設定しました。また、on_stopの下に新しいstop_review_app ジョブを定義しました。review_app ジョブが正常に終了すると、whenで定義した内容に基づいてstop_review_app ジョブが起動します。この場合、manual に設定したので、実行するには GitLab のウェブインターフェイスを使った手動操作が必要になります。

また、この例ではGIT_STRATEGY をnone に設定しています。これは、stop_review_appジョブが自動的にトリガーされたときに GitLab Runner がブランチを削除した後にコードをチェックアウトしようとしないようにするためです。

注：上記の例はグローバル変数を上書きしています。停止環境ジョブがグローバル変数に依存している場合、GIT_STRATEGYを設定する際にアンカー変数を使用することで、グローバル変数を上書きせずに変更することができます。

stop_review_app ジョブには以下のキーワードが定義されている必要があります：

  • when -参照
  • environment:name
  • environment:action

さらに、両方のジョブはrulesもしくはonly/except の設定が一致している必要があります。上の例で、設定が一致していない場合、stop_review_app ジョブはreview_app ジョブを含むすべてのパイプラインに含まれず、action: stop をトリガーして自動的に環境を停止することができないかもしれません。

environment:auto_stop_in

GitLab 12.8で導入されました。

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

例えば、 

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

review_app ジョブが実行され、レビューアプリが作成されると、環境の有効期限が1 dayに設定されます。

詳細については、環境の自動停止に関するドキュメントを参照してください。

environment:kubernetes

GitLab 12.6 で導入されました。

kubernetes ブロックは、プロジェクトに関連付けられた Kubernetes クラスター へのデプロイを設定するために使用されます。

使用例： 

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

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

詳しくは、kubernetesで利用可能な設定をご覧ください。

注：Kubernetesの設定は、GitLabによって管理されているKubernetesクラスタではサポートされていません。 GitLabによって管理されているクラスタのサポートの進捗状況については、関連するイシューを参照してください。

動的な環境

  • GitLab 8.12 と GitLab Runner 1.6 で導入されました。
  • $CI_ENVIRONMENT_SLUG は GitLab 8.15 で導入されました。
  • name とurl パラメータは、事前定義済み変数、セキュア変数、.gitlab-ci.yml variablesを含む、定義された CI 変数を使用することができます。 しかし、scriptで定義された変数を使用することはできません。

使用例： 

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

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

もちろん、これはアプリケーションをホストするサーバが適切に設定されていることが前提となります。

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

cache

  • GitLab Runner v0.7.0 で導入されました。
  • cache はグローバルおよびジョブごとに設定できます。
  • GitLab 9.0 からは、デフォルトでパイプラインとジョブ間でキャッシュが有効になり、共有されるようになりました。
  • GitLab 9.2からは、アーティファクトより先にキャッシュが復元されるようになりました。
さらに詳しく:キャッシュがどのように機能するのか、またキャッシュの依存関係のドキュメントでベストプラクティスを見つけましょう。

cache は、ジョブ間でキャッシュするファイルやディレクトリのリストを指定するために使用します。 使用できるパスは、ローカルの作業コピー内にあるものだけです。

cache がジョブの範囲外で定義されている場合、それはグローバルに設定されており、すべてのジョブがその定義を使用することを意味します。

cache:paths

paths ディレクティブを使用して、キャッシュされるファイルやディレクトリを選択します。 パスはプロジェクトディレクトリ ($CI_PROJECT_DIR) からの相対パスで、プロジェクトディレクトリの外部に直接リンクすることはできません：

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

rspec:
  script: test
  cache:
    paths:
      - binaries/*.apk
      - .config

ジョブで定義されたキャッシュはグローバルに定義されたオプションを上書きします。次のrspecジョブはbinaries/だけをキャッシュします： 

cache:
  paths:
    - my/files

rspec:
  script: test
  cache:
    key: rspec
    paths:
      - binaries/

キャッシュは異なるジョブ間で共有されるので、想定しない内容でキャッシュが上書きされる可能性があります。異なるcache:keyを設定することで、ジョブごとに異なるキャッシュを持つことができます。

cache:key

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

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

key ディレクティブは、ジョブ間のキャッシュの範囲を定義することができます。すべてのジョブに対して単一のキャッシュを持つことも、ジョブごとにキャッシュすることも、ブランチごとにキャッシュすることも、ワークフローに合った方法でキャッシュすることもできます。 このようにして、キャッシュを細かく調整し、異なるジョブ間、あるいは異なるブランチ間でデータをキャッシュすることができます。

cache:key として任意の 定義済みの変数を使用することができます。設定されていない場合のデフォルトのキーは、文字列のdefault になります。これは、GitLab 9.0以降 からのデフォルトで、パイプラインとジョブの間ですべてのキャッシュが共有されることを意味します。

注意:cache:key 変数には、/ のような文字や、それに相当するURIエンコードした %2F を含めることはできません。ドットだけの値(.、%2E)も禁止されています。

以下は、ブランチごとのキャッシュを有効にする例です。 

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - binaries/

Windowsバッチを使用してシェルスクリプトを実行する場合は、$ を%に置き換える必要があります： 

cache:
  key: "%CI_COMMIT_REF_SLUG%"
  paths:
    - binaries/
cache:key:files

GitLab v12.5 で導入されました。

cache:key:files キーワードは、cache:key の機能を拡張し、キャッシュの再利用を容易にし、リビルドの頻度を減らすことで、後続のパイプラインの実行を高速化します。

cache:key:files を使用するには、キャッシュキーを生成するために使用するファイルを指定しなければなりません。 キャッシュkeyは、指定したファイルを変更した直近のコミットから計算された SHA チェックサムになります (2 つのファイルがリストアップされている場合は最大 2 つまで)。どちらのファイルもコミットで変更されていない場合の、フォールバックキーはdefaultです。 

cache:
  key:
    files:
      - Gemfile.lock
      - package.json
  paths:
    - vendor/ruby
    - node_modules

この例では、Gemfile.lock と package.json ファイルに関連付けられた Ruby と Node.js の依存関係のキャッシュを作成しています。これらのファイルが変更されるたびに、新しいキャッシュキーが計算され、新しいキャッシュが作成されます。つまり、cache:key:filesで同じ Gemfile.lock と package.json を指定して実行するジョブには、同じキャッシュが使用されます。

cache:key:prefix

GitLab v12.5 で導入されました。

prefix パラメータはkey:files に追加機能を加え、与えられたprefix とcache:key:filesで計算された SHA を組み合わせたキーを構成できるようにします。 例えば、testのprefix を追加すると、キーはtest-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5のようになります。どちらのファイルもコミットで変更されていない場合、defaultに接頭辞が追加されるので、この例のキーはtest-defaultとなります。

cache:keyと同様、prefix は任意の定義済み変数を使用できますが、以下の変数は使用できません：

  • / 文字（または同等の URI エンコード%2F）。
  • . （または同等のURIエンコード%2E）のみで構成される値。 
cache:
  key:
    files:
      - Gemfile.lock
    prefix: ${CI_JOB_NAME}
  paths:
    - vendor/ruby

rspec:
  script:
    - bundle exec rspec

たとえば、$CI_JOB_NAME のprefix を追加すると、キーはrspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5 のようになり、ジョブキャッシュは異なるブランチで共有されます。ブランチでGemfile.lockを変更すると、そのブランチはcache:key:filesの新しい SHA チェックサムを持つことになります。 新しいキャッシュキーが生成され、そのキーに対して新しいキャッシュが作成されます。Gemfile.lock が見つからない場合、defaultに接頭辞が追加されるため、この例のキーはrspec-defaultになります。

cache:untracked

untracked: true を設定して、git リポジトリ内で追跡されていないすべてのファイルをキャッシュします： 

rspec:
  script: test
  cache:
    untracked: true

Gitで追跡されていないファイルや、binariesにあるファイルをすべてキャッシュします： 

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

cache:policy

GitLab 9.4 で導入されました。

キャッシュ処理のデフォルトの動作は、実行の開始時にファイルをダウンロードし、終了時に再アップロードすることです。 これはジョブによって行われた変更を将来の実行のために永続化することを可能にし、pull-push キャッシュポリシーとして知られています。

ジョブがキャッシュされたファイルを変更しないことが分かっている場合、そのジョブでpolicy: pull を設定することで、アップロードのステップをスキップすることができます。 一般的に、これはキャッシュが確実に更新されることを保証するために、より早いステージで通常のキャッシュジョブと組み合わせられます： 

stages:
  - setup
  - test

prepare:
  stage: setup
  cache:
    key: gems
    paths:
      - vendor/bundle
  script:
    - bundle install --deployment

rspec:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - bundle exec rspec ...

これにより、特に多数のキャッシュを使用するジョブが並列に実行されている場合には、ジョブの実行を高速化し、キャッシュサーバの負荷を軽減することができます。

さらに、以前の内容を参照せずに無条件にキャッシュを再作成するジョブがある場合、そのジョブでpolicy: push 、ダウンロードステップをスキップすることができます。

artifacts

  • Windows以外のGitLab Runner v0.7.0 で導入されました。
  • GitLab Runner v.1.0.0でWindowsに対応しました。
  • GitLab 9.2からは、アーティファクトの前にキャッシュが復元されるようになりました。
  • すべてのExecutorに対応しているわけではありません。
  • ジョブのアーティファクトは、デフォルトでは成功したジョブに対してのみ収集されます。

artifacts は、ジョブがsuccess、failure、alwaysの場合に、添付されるべきファイルとディレクトリのリストを指定するために使用されます。

ジョブの終了後、アーティファクトはGitLabに送られ、UIからダウンロードできます。

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

artifacts:paths

パスはプロジェクトディレクトリ ($CI_PROJECT_DIR) からの相対パスであり、その外部に直接リンクすることはできません。globパターンとfilepath.Matchをワイルドカードとして使用することができます。

アーティファクトを取得できるジョブを制限するには、dependenciesを参照してください。

binaries内のすべてのファイルと.configを送信します： 

artifacts:
  paths:
    - binaries/
    - .config

他のジョブでのアーティファクトの取得を無効にするには、dependenciesを空にして定義します。 

job:
  stage: build
  script: make build
  dependencies: []

一時的なビルドのアーティファクトでビルドサーバーのストレージがいっぱいにならないように、タグ付けされたリリースだけでアーティファクトを作成したい場合があります。

タグに対してのみアーティファクトを作成します（default-job ではアーティファクトは作成されません）： 

default-job:
  script:
    - mvn test -U
  except:
    - tags

release-job:
  script:
    - mvn package -U
  artifacts:
    paths:
      - target/*.war
  only:
    - tags

ディレクトリにもワイルドカードを使うことができます。xyzで終わるディレクトリ内のファイルをすべて取得したい場合の使用例 ： 

job:
  artifacts:
    paths:
      - path/*xyz/*

artifacts:exclude

exclude を使用すると、アーティファクトにファイルが追加されないようにすることができます。

artifacts:pathsと同様に、exclude のパスはプロジェクトディレクトリからの相対パスとなります。globパターンとfilepath.Matchに従うワイルドカードを使用することができます。

たとえば、binaries/にあるすべてのファイルを保存し、binaries/のサブディレクトリにある*.o のファイルは保存しないようにします： 

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

artifacts:untracked でマッチしたファイルはartifacts:exclude でも除外できます。

artifacts:expose_as

GitLab 12.5で導入されました。

expose_as キーワードは、マージリクエストUI でジョブのアーティファクトを公開するために使用できます。

1つのファイルにマッチする例: 

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

この設定により、GitLabは関連するマージリクエストにfile1.txtを指すartifact1というリンクを追加します。

ディレクトリ全体にマッチする例: 

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

以下に注意してください。

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

artifacts:name

GitLab 8.6 と GitLab Runner v1.1.0 で導入されました。

name ディレクティブでは、作成されたアーティファクトアーカイブの名前を定義することができます。こうすることで、GitLab からアーカイブをダウンロードするときに便利な、一意な名前を各アーカイブにつけることができます。artifacts:name変数には、定義済みの変数を使用することができます。デフォルトの名前はartifactsで、ダウンロードするとartifacts.zip になります。

注意: ブランチ名にスラッシュが含まれている場合 (たとえばfeature/my-feature)、アーティファクトの適切な命名のために、$CI_COMMIT_REF_NAME の代わりに$CI_COMMIT_REF_SLUGを使用することをお勧めします。

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

job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/

ブランチまたはタグの名前で、バイナリディレクトリのみを含むアーカイブを作成します。 

job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

ジョブ名とブランチまたはブランチの名前で、バイナリディレクトリのみを含むアーカイブを作成します。 

job:
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

ステージ名とブランチ名で、アーカイブを作成します。 

job:
  artifacts:
    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

Windowsバッチを使用してシェルスクリプトを実行する場合は、$ を%に置き換える必要があります： 

job:
  artifacts:
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
    paths:
      - binaries/

Windows PowerShellを使用してシェルスクリプトを実行する場合は、$ を$env:に置き換える必要があります： 

job:
  artifacts:
    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
    paths:
      - binaries/

artifacts:untracked

artifacts:untracked を使うと、（artifacts:pathsで定義したパスのファイルに加えて）アーティファクトとして Git の未追跡ファイルをすべて追加することができます。

注:artifacts:untracked はリポジトリの.gitignore ファイルの設定を無視します。

すべてのGitの未追跡ファイルをアーティファクトに追加します。 

artifacts:
  untracked: true

Gitの未追跡ファイルとbinaries内のファイルをすべて送信します： 

artifacts:
  untracked: true
  paths:
    - binaries/

すべての未追跡ファイルを送信しますが、*.txtは除外します： 

artifacts:
  untracked: true
  exclude:
    - *.txt

artifacts:when

GitLab 8.9 と GitLab Runner v1.3.0 で導入されました。

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

artifacts:when には以下のいずれかの値を設定できます：

  1. on_success - ジョブが成功した場合のみ、アーティファクトをアップロードします。これはデフォルトです。
  2. on_failure - ジョブが失敗した場合のみ、アーティファクトをアップロードします。
  3. always - ジョブステータスに関係なく、アーティファクトをアップロードします。

ジョブが失敗したときだけアーティファクトをアップロードする。 

job:
  artifacts:
    when: on_failure

artifacts:expire_in

GitLab 8.9 と GitLab Runner v1.3.0 で導入されました。

expire_in を使うと、アーティファクトがアップロードされて GitLab に保存された時点から数えて、有効期限が切れて削除されるまでの期間を指定できます。 有効期限が定義されていない場合、デフォルトではインスタンス全体の設定(デフォルトでは 30 日) になります。

ジョブページのKeepボタンを使用すると、有効期限を上書きしてアーティファクトを永久に保存することができます。

有効期限が切れると、アーティファクトはデフォルトで毎時削除され（cronジョブで）、もうアクセスできなくなります。

expire_in の値は、単位が指定されていない限り、秒単位の経過時間です。 有効な値の例：

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

アップロード後、1週間後にアーティファクトを失効させること。 

job:
  artifacts:
    expire_in: 1 week
注意:GitLab 13.0以降、参照用の最新のアーティファクトを削除しないようにロックし、有効期限に関係なく保持することができます。 この機能はデフォルトでは無効になっており、本番環境での使用には適していません。テスト用に、:keep_latest_artifact_for_ref と:destroy_only_unlocked_expired_artifacts 機能フラグを有効にすることで有効にすることができます。

artifacts:reports

artifacts:reports キーワードは、ジョブからテストレポート、コード品質レポート、セキュリティレポートを収集するために使われます。 また、これらのレポートを GitLab の UI (マージリクエスト、パイプラインビュー、セキュリティダッシュボード) で公開します。

これらは、利用可能なレポートの種類です。

パラメータ 説明
artifacts:reports:junit junit レポートは、JUnit XML ファイルを収集します。
artifacts:reports:dotenv dotenv レポートは、環境変数一式を収集します。
artifacts:reports:cobertura cobertura レポートは、Cobertura カバレッジ XML ファイルを収集します。
artifacts:reports:terraform terraform レポートは Terraformtfplan.json ファイルを収集します。
artifacts:reports:codequality codequality レポートは、CodeQuality のイシューを収集します。
artifacts:reports:sast sast レポートは、静的アプリケーションセキュリティテストの脆弱性を収集します。
artifacts:reports:dependency_scanning dependency_scanning レポートでは、依存関係スキャンの脆弱性を収集しています。
artifacts:reports:container_scanning container_scanning レポートはコンテナスキャンの脆弱性を収集します。
artifacts:reports:dast dast レポートは、動的アプリケーションセキュリティテストの脆弱性を収集します。
artifacts:reports:license_management license_management レポートはライセンスを収集します（GitLab 13.0 から削除されました）。
artifacts:reports:license_scanning license_scanning レポートはライセンスを収集します。
artifacts:reports:performance performance レポートは、ブラウザパフォーマンスメトリクスを収集します。
artifacts:reports:load_performance load_performance レポートは、負荷パフォーマンスのメトリクスを収集します。
artifacts:reports:metrics metricsレポートは 、メトリクスを収集します。

dependencies

GitLab 8.6 と GitLab Runner v1.1.1 で導入されました。

デフォルトでは、以前のすべてのステージからのすべてのartifacts が渡されますが、dependencies パラメータを使用して、アーティファクトを取得するジョブの限定リスト (またはジョブなし) を定義できます。

この機能を使用するには、ジョブのコンテキストでdependencies を定義し、アーティファクトがダウンロードされるべきすべての以前のジョブのリストを渡します。 現在のステージより前に実行されたステージからのジョブのみを定義できます。 現在のステージまたは次のステージからのジョブを定義すると、エラーが表示されます。 空の配列を定義すると、そのジョブのアーティファクトのダウンロードはスキップされます。dependenciesを使用する場合、以前のジョブのステータスは考慮されないため、失敗したジョブや実行されなかった手動ジョブであっても、エラーは発生しません。

次の例では、build:osx とbuild:linuxの2つのアーティファクトを持つジョブを定義します。test:osx が実行されると、build:osxからのアーティファクトがダウンロードされ、ビルドのコンテキストで抽出されます。test:linux とbuild:linuxからのアーティファクトについても同じことが起こります。

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

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
依存するジョブが失敗する場合

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

依存関係に設定されているジョブのアーティファクトが期限切れまたは消去された場合、依存するジョブは失敗します。

注意：管理者にこのスイッチを入れてもらい、以前の動作を取り戻すことができます。

coverage

GitLab 8.17 で導入されました。

coverage では、ジョブの出力からコードカバレッジを抽出する方法を設定できます。

正規表現は、ここで期待される唯一の有効な値の種類です。 したがって、正規表現文字列を一貫して明示的に表すためには、/ で囲むことが必須です。 特殊文字を文字通りにマッチさせたい場合は、特殊文字をエスケープする必要があります。

簡単な使用例： 

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

retry

retry では、ジョブが失敗した場合に何回再試行するかを設定できます。

ジョブが失敗してretry が設定されている場合、retry キーワードで指定された回数まで再度処理されます。

retry が2に設定されている場合、ジョブが2回目の実行（1回目の再試行）で成功すると、再試行は行われません。 retryの値は0以上2以下の正の整数でなければなりません（最大2回の再試行、合計3回の実行）。

すべての失敗条件で再試行する簡単な使用例： 

test:
  script: rspec
  retry: 2

デフォルトでは、ジョブはすべての失敗ケースで再試行されます。 再試行する失敗をより適切に制御するために、retry は以下のキーを持つハッシュにすることができます：

  • max最大再試行回数。
  • when再試行する失敗条件。

Runnerシステム障害のみ最大2回再試行する： 

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

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

複数の失敗条件で再試行するために、when は失敗条件の配列にすることもできます： 

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

when に指定可能な値：

  • always: 失敗したら再試行（デフォルト）。
  • unknown_failure: 失敗理由が不明な場合に再試行します。
  • script_failure: スクリプトが失敗したときに再試行します。
  • api_failure: API失敗時に再試行します。
  • stuck_or_timeout_failure: ジョブがスタックまたはタイムアウトした場合に再試行します。
  • runner_system_failure: Runnerシステムに障害が発生した場合（ジョブのセットアップに失敗した場合など）に再試行します。
  • missing_dependency_failure: 依存関係が見つからない場合に再試行します。
  • runner_unsupported: Runnerがサポートされていない場合は再試行します。
  • stale_schedule: 遅延したジョブが実行できなかった場合に再試行します。
  • job_execution_timeout: スクリプトがジョブに設定された最大実行時間を超えた場合に再試行します。
  • archived_failure: ジョブがアーカイブされ、実行できない場合に再試行します。
  • unmet_prerequisites: ジョブが前提条件のタスクを完了できなかった場合に再試行します。
  • scheduler_failure: スケジューラがジョブのRunnerへの割り当てに失敗した場合に再試行します。
  • data_integrity_failure: 構造的整合性の問題が検出された場合は再試行します。

ジョブ実行の特定の段階における再試行回数は、変数を用いて指定することができます。

timeout

GitLab 12.3 で導入されました。

timeout は特定のジョブのタイムアウトを設定できます： 

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

test:
  script: rspec
  timeout: 3h 30m

ジョブレベルのタイムアウトは、プロジェクトレベルのタイムアウトを超えることができますが、Runner固有のタイムアウトを超えることはできません。

parallel

GitLab 11.5で導入されました。

parallelはジョブの並列実行数を設定します。この値は2以上50以下でなければなりません。

これは、並行して実行される同じジョブのインスタンスをN個作成します。 これらのインスタンスには、job_name 1/N からjob_name N/Nまで順次名前が付けられます。

ジョブごとに、 環境変数 CI_NODE_INDEX とCI_NODE_TOTAL が設定されます。

ジョブを並列実行するようにマークするには、設定ファイルにparallel を追加する必要があります。 例えば、以下のようになります： 

test:
  script: rspec
  parallel: 5
ヒント:並列ジョブ間でテストスイートを並列化します。 言語によって、これを容易にするツールは異なります。

Semaphore Test BoostersとRSpecを使って、Rubyのテストを実行する簡単な例です。 

# Gemfile
source 'https://rubygems.org'

gem 'rspec'
gem 'semaphore_test_boosters'

test:
  parallel: 3
  script:
    - bundle
    - bundle exec rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL
注意:semaphore_test_boostersは作成者に使用統計を報告することに注意してください。

その後、新しいパイプラインビルドのジョブタブに移動すると、RSpecジョブが3つの別々のジョブに分割されていることが確認できます。

trigger

trigger は、ダウンストリームパイプラインのトリガーを定義できます。 trigger の定義から作成されたジョブがGitLabによって開始されると、ダウンストリームパイプラインが作成されます。

このキーワードにより、2種類のダウンストリームパイプラインを作成することができます。

注：trigger とwhen:manual を併用すると、jobs:#{job-name} when should be on_success, on_failure or alwaysというエラーが発生します。これは、trigger がトリガーの使用を妨げているためです。

マルチプロジェクトパイプラインのためのシンプルなtrigger 構文

ダウンストリームトリガーを設定する最も簡単な方法は、trigger キーワードとダウンストリームプロジェクトへのフルパスを使用することです： 

rspec:
  stage: test
  script: bundle exec rspec

staging:
  stage: deploy
  trigger: my/deployment

マルチプロジェクトパイプラインのための複雑なtrigger 構文

GitLabがダウンストリームパイプラインを作成する際に使用するブランチ名を設定することが可能です。 

rspec:
  stage: test
  script: bundle exec rspec

staging:
  stage: deploy
  trigger:
    project: my/deployment
    branch: stable

トリガーされたパイプラインからステータスをミラーリングすることが可能です。 

trigger_job:
  trigger:
    project: my/project
    strategy: depend

アップストリームのパイプラインからステータスをミラーリングすることが可能です。 

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

子パイプラインの trigger 構文

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

子パイプラインを作成する場合は、子パイプラインのCI設定を含むYAMLファイルへのパスを指定します。 

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

マルチプロジェクトパイプラインと同様に、トリガーされたパイプラインからステータスをミラーリングすることが可能です。 

trigger_job:
  trigger:
    include:
      - local: path/to/child-pipeline.yml
    strategy: depend
生成された設定ファイルで子パイプラインをトリガーする

GitLab 12.9で導入されました。

また、動的に生成された設定ファイルから子パイプラインを起動することも可能です。 

generate-config:
  stage: build
  script: generate-ci-config > generated-config.yml
  artifacts:
    paths:
      - generated-config.yml

child-pipeline:
  stage: test
  trigger:
    include:
      - artifact: generated-config.yml
        job: generate-config

generated-config.yml はアーティファクトから抽出され、子パイプラインをトリガーするための設定として使用されます。

trigger:strategy でパイプラインを連携させる

デフォルトでは、trigger ジョブは、ダウンストリームパイプラインが作成されるとすぐに、success ステータスで完了します。

ダウンストリーム（マルチプロジェクトまたは子）パイプラインが完了するまで、trigger ジョブを強制的に待機させるには、strategy: dependを使用します。 これにより、トリガーされたパイプラインが完了するまで、トリガージョブは「実行中」ステータスで待機します。ダウンストリームジョブが完了した時点で、trigger ジョブも完了します。 

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

これはパイプラインの実行を線形に保つのに役立ちます。 上の例では、後続ステージのジョブはトリガーされたパイプラインが正常に完了するのを待ってから開始しますが、その代償として並列化率が下がります。

APIコールによるパイプラインのトリガー

triggerは、トリガートークンを使ってパイプラインを作成したときに、APIコールで特定のブランチ、タグ、コミットを強制的にリビルドするために使用されます。

trigger パラメーターと混同しないでください。

詳しくは、トリガーのドキュメントをご覧ください。

interruptible

GitLab 12.3 で導入されました。

interruptibleは、新しいパイプラインの実行によって冗長になったジョブをキャンセルすることを示します。 デフォルトは false です。この値は、冗長パイプラインの自動キャンセル機能が有効になっている場合にのみ使用されます。

有効にすると、同じブランチのパイプラインは、次の場合にキャンセルされます。

  • 新しいパイプラインの実行で余剰となる。
  • すべてのジョブが割り込み可能な状態に設定されているか、割り込み不可能なジョブが開始されていないかのどちらかです。

保留中のジョブは常に中断可能であるとみなされます。

ヒント:ジョブを中断可能なものとして設定し、一度開始したジョブを安全にキャンセルできるようにします (例えば、ビルドジョブ)。

ここでは、簡単な例をご紹介します： 

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 will never be canceled, even though set as interruptible."
  interruptible: true

上記の例では、新しいパイプラインの実行によって、既存の実行中のパイプラインが

  • step-1 のみが実行中または保留中の場合は、キャンセルされます。
  • step-2 の実行を開始するとキャンセルされません。
注意: 割り込み禁止ジョブが実行されると、最終的なジョブの状態にかかわらず、パイプラインがキャンセルされることはありません。

resource_group

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

ある環境で複数のジョブやパイプラインを同時に実行すると、デプロイ時のエラーにつながることがあります。

これらのエラーを回避するために、resource_group 属性を使用して、Runner が特定のジョブを同時に実行しないようにすることができます。

.gitlab-ci.ymlのジョブにresource_group キーが定義されている場合、ジョブの実行は同じプロジェクトの異なるパイプライン間で相互に排他的です。同じリソースグループに属する複数のジョブが同時にエンキューされている場合、ジョブのうち 1 つだけが Runner によって選択され、他のジョブはresource_group が空くまで待機します。

ここでは、簡単な例をご紹介します： 

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

この場合、あるパイプラインで deploy-to-production ジョブが実行されているときに、別のパイプラインで新しい deploy-to-production ジョブが作成されると、現在実行中/保留中の deploy-to-production ジョブが終了するまで、そのジョブは実行されません。 その結果、本番環境で同時デプロイが発生しないようにすることができます。

環境ごとにresource_groupを複数定義することができます。この良いユースケースは、物理デバイスにデプロイする場合です。複数の物理デバイスがあり、それぞれにデプロイできますが、デバイスごとのデプロイは常に1つだけです。

注：このキーには、文字、数字、-、_、/、$、{、}、.、およびスペースのみを含めることができます。/で開始または終了することはできません。

詳しくは、「デプロイメントの安全性」をご覧ください。

release

GitLab 13.2 で導入されました。

release はジョブがリリースを作成することを示し、オプションでリリースアセットのURLが含まれます。

これらの方式に対応しています。

リリースはジョブがエラーなく処理された場合にのみ作成されます。 リリース作成中にRails APIがエラーを返した場合、release ジョブは失敗します。

release-cli Docker イメージ

release-cliに使用するDockerイメージを以下のディレクティブで指定する必要があります： 

image: registry.gitlab.com/gitlab-org/release-cli:latest

Script

すべてのジョブは、最低限script タグを必要とします。:release ジョブは:script タグの出力を使用できますが、その必要がない場合は、プレースホルダースクリプトなどを使用できます： 

script:
  - echo 'release job'

GitLabの次期バージョンでこの要件を取り除くためのイシューが存在します。

パイプラインは、例えば、複数のrelease ジョブを持つことができます： 

ios-release:
  script:
    - echo 'iOS release job'
  release:
     tag_name: v1.0.0-ios
     description: 'iOS release v1.0.0'

android-release:
  script:
    - echo 'Android release job'
  release:
     tag_name: v1.0.0-android
     description: 'Android release v1.0.0'

release:tag_name

tag_name は必須です。既存のgitタグを参照することも、ユーザーが指定することもできます。

指定したタグがリポジトリに存在しない場合、パイプラインの関連するSHAから新しいタグが作成されます。

GitタグからReleaseを作成する場合の例。 

job:
  release:
    tag_name: $CI_COMMIT_TAG
    description: changelog.txt

任意のユニークなタグを作成することも可能で、その場合は only: tags は必須ではありません 。セマンティック・バージョニングの例です： 

job:
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: changelog.txt
  • リリースは、ジョブのメインスクリプトが成功した場合にのみ作成されます。
  • リリースが既に存在する場合は更新されず、release キーワードを指定したジョブは失敗します。
  • release セクションは、script タグの後、after_scriptの前に実行されます。

release:name

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

release:description

リリースの説明を指定します。

release:ref

release: tag_name がまだ存在しない場合は、ref からリリースが作成されます。 ref にはコミット SHA、別のタグ名、ブランチ名を指定することができます。

release:milestones

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

release:released_at

リリースが可能になる日時。 定義されていない場合は現在の日時がデフォルト。 ISO 8601形式（2019-03-15T08:00:00Z）で期待されます。

完全な release の例

上記の release の個々の例を組み合わせると、次のようなコードスニペットになります。 タグを生成する方法によって、2つのオプションがあります。 これらのオプションは併用できないので、どちらかを選択してください：

  • Gitタグをプッシュしたとき、またはUIで「リポジトリ」>「タグ」でGitタグを追加したときにリリースを作成する。 

     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 release_job'
   release:
      name: 'Release $CI_COMMIT_TAG'
      description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined
      tag_name: '$CI_COMMIT_TAG'                                      # elsewhere in the pipeline.
      ref: '$CI_COMMIT_TAG'
      milestones:
        - 'm1'
        - 'm2'
        - 'm3'
      released_at: '2020-07-15T08:00:00Z'  # Optional, will auto generate if not defined,
                                           # or can use a variable.

  • デフォルトブランチに変更がプッシュされたときに、変数で定義された新しいGitタグを使って自動的にリリースを作成すること。 

     release_job:
   stage: release
   image: registry.gitlab.com/gitlab-org/release-cli:latest
   rules:
     - if: $CI_COMMIT_TAG
       when: never                                 # Do not run this job when a tag is created manually
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when the default branch changes
   script:
     - echo 'running release_job'
   release:
      name: 'Release $CI_COMMIT_SHA'
      description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the tag_name
      tag_name: 'v${MAJOR}.${MINOR}.${REVISION}'                      # variables must be defined elsewhere
      ref: '$CI_COMMIT_SHA'                                           # in the pipeline.
      milestones:
        - 'm1'
        - 'm2'
        - 'm3'
      released_at: '2020-07-15T08:00:00Z'          # Optional, will auto generate if not defined,
                                                   # or can use a variable.

releaser-cli コマンドライン

:release ノード下のエントリはbash コマンドラインに変換され、release-cliを含むDockerコンテナに送られます。script エントリからrelease-cli を直接呼び出すこともできます。

上記のYAMLは、次のようなCLIコマンドに変換されます。 

release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3"

pages

pages は、ウェブサイトを提供するために使用できる静的なコンテンツを GitLab にアップロードするための特別なジョブです。 特別な構文なので、以下の二つの要件を満たす必要があります：

  • 静的コンテンツは、public/ ディレクトリの下に配置する必要があります。
  • artifacts を、public/ ディレクトリへのパスとともに定義する必要があります。

以下の例は、プロジェクトのルートからpublic/ ディレクトリにすべてのファイルを移動しています。.public の回避策は、cp がpublic/ を自分自身にコピーして無限ループにならないようにするためです： 

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - master

詳しくはGitLab Pagesのユーザードキュメントをご覧ください。

variables

GitLab Runner v0.5.0から導入されました。

注：変数の名前と値には、整数（文字列も同様）が使用できます。小数は使用できません。

GitLab CI/CD では、.gitlab-ci.yml 内で変数を定義し、ジョブ環境に渡すことができます。これらはグローバルに設定することも、ジョブごとに設定することもできます。variables キーワードをジョブレベルで使用すると、グローバルな YAML 変数や事前に定義された同名の変数が上書きされます。

これらはGitリポジトリに保存され、機密性のないプロジェクトの設定などを保存するためのものです。 

variables:
  DATABASE_URL: "postgres://postgres@postgres/my_database"

YAML で定義された変数は、作成されたすべてのサービスコンテナに設定されるため、微調整を行うことができます。

ユーザー定義の変数以外に、Runner自身が設定する変数もあります。一例として、CI_COMMIT_REF_NAME はプロジェクトがビルドされるブランチやタグ名の値を持ちます。.gitlab-ci.ymlで設定できる変数とは別に、GitLabのUIで設定できる変数もあります。

variablesのYAMLアンカーが利用可能です。

変数とその優先順位について、詳しくはこちらをご覧ください。

Git strategy

  • GitLab 8.9で実験的な機能として導入されました。
  • GIT_STRATEGY=none はGitLab Runner v1.7+が必要です。
注意：将来のリリースでは、変更または完全に削除される可能性があります。

最近のアプリケーションコードの取得に使用するGIT_STRATEGY は、variables セクションでグローバルまたはジョブごとに設定できます。指定しない場合は、プロジェクト設定のデフォルトが使用されます。

設定可能な値は、clone、fetch、noneの3つです。

clone は最も遅いオプションです。 ジョブごとにリポジトリをゼロからクローンし、ローカルの作業コピーが常にクリーンであることを保証します。 

variables:
  GIT_STRATEGY: clone

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

variables:
  GIT_STRATEGY: fetch

none もローカルの作業コピーを再利用しますが、すべての Git オペレーションをスキップします (GitLab Runner の pre-clone スクリプトがある場合はそれも含めて)。 これは、アーティファクトだけを操作するジョブ (たとえばdeployなど) に便利です。Git リポジトリのデータは存在するかもしれませんが、確実に古くなっているので、キャッシュやアーティファクトからローカルの作業コピーに取り込まれたファイルだけに頼るべきです。 

variables:
  GIT_STRATEGY: none
注: GIT_STRATEGY はKubernetes Executor ではサポートされていませんが、将来的にサポートされる可能性があります。最新情報については、Kubernetes Executor 機能提案でのGit strategyサポートを参照してください。

Git submodule strategy

GitLab Runner v1.10+が必要です。

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

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

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

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

     git submodule sync
 git submodule update --init

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

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

この機能が正しく動作するためには、サブモジュールが（.gitmodules 内で）どちらかで設定されていなければならないことに注意してください：

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

Git checkout

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

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

falseに設定した場合、Runnerは次のようになります：

  • fetch の場合 - リポジトリを更新し、現在のリビジョンで作業コピーを残してください、
  • clone の場合 - リポジトリをクローンし、デフォルトブランチで作業コピーを残してください。

この設定をtrue にすると、clone とfetchの両方の戦略で、Runnerは作業コピーをCIパイプラインに関連するリビジョンにチェックアウトします： 

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

Git clean flags

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

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

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

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

もし GIT_CLEAN_FLAGS が：

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

使用例： 

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

Git fetch extra flags

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

GIT_FETCH_EXTRA_FLAGS 変数はgit fetchの動作を制御するために使用されます。variables セクションでグローバルまたはジョブごとに設定できます。

GIT_FETCH_EXTRA_FLAGS は、git fetch コマンドで可能なすべてのオプションを受け付けますが、GIT_FETCH_EXTRA_FLAGS のフラグは、変更できないデフォルトのフラグの後に追加されることに注意してください。

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

もし GIT_FETCH_EXTRA_FLAGS が：

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

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

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

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

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

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

Job stages attempts

GitLabで導入され、GitLab Runner v1.9+が必要です。

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

変数 説明
GET_SOURCES_ATTEMPTS ジョブを実行しているソースのフェッチを試行した回数
ARTIFACT_DOWNLOAD_ATTEMPTS ジョブ実行中のアーティファクトのダウンロード試行回数
RESTORE_CACHE_ATTEMPTS ジョブを実行しているキャッシュの復元試行回数
EXECUTOR_JOB_SECTION_ATTEMPTS GitLab12.10以降、No Such Container エラーが発生した後にジョブのセクションを実行する試行回数(Docker Executor のみ)。

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

使用例： 

variables:
  GET_SOURCES_ATTEMPTS: 3

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

Shallow cloning

GitLab 8.9で実験的な機能として導入されました。

注意: GitLab 12.0から、新しく作成されたプロジェクトは自動的にデフォルトのgit depth の値が50になりまます。

GIT_DEPTHを使って、フェッチとクローンの深さを指定できます。 これにより、リポジトリのシャロウクローンが可能になり、コミット数の多いリポジトリや古くて大きなバイナリのクローンを大幅に高速化できます。 この値はgit fetch とgit cloneに渡されます。

注意:深さ1を使用し、ジョブのキューまたは再試行ジョブがある場合、ジョブは失敗する可能性があります。

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

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

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

variables:
  GIT_DEPTH: "3"

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

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

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

注：これはcustom_build_dir がRunnerの設定で有効になっている場合にのみ使用できます。これはdocker とkubernetes のexecutorのデフォルトの設定です。

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

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name

test:
  script:
    - pwd

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

並行処理を行う

1 を超える同時実行数を使用する executor は、builds_dirがジョブ間で共有されている場合、複数のジョブが同じディレクトリで作業している可能性があるため、失敗につながる可能性があります。 GitLab Runner はこのような状況を防ごうとはしません。Runner 設定の要件に従うかどうかは、管理者と開発者次第です。

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

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

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

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

test:
  script:
    - pwd

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

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

test:
  script:
    - pwd

ネストされたパス

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

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

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

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

YAML の特殊機能

アンカー (&)、エイリアス (*)、マップマージ (<<) のような特別な YAML 機能を使うことで、.gitlab-ci.ymlの複雑さを大幅に減らすことができます。

YAMLの様々な機能についてはこちらをご覧ください。

たいていの場合、extends キーワード のほうが使いやすいので、これらの特別な YAML 機能よりも優先して使うべきです。配列をマージするために YAML アンカーを使う必要があるかもしれません。

アンカー

GitLab 8.6 と GitLab Runner v1.1.1 で導入されました。

YAML には ‘アンカー’ という便利な機能があり、これを使うとドキュメント全体のコンテンツを簡単に複製できます。 アンカーはプロパティの複製や継承に使うことができ、隠しジョブのテンプレートとして使うのに最適です。 キーが重複している場合、GitLab はキーをもとに逆ディープマージを実行します。

以下の例では、アンカーとマップのマージを使っています。.job_templateのパラメータを継承する2つのジョブ、test1 とtest2が作成され、それぞれに独自のカスタムscript が定義されます： 

.job_template: &job_definition  # Hidden key that defines an anchor named 'job_definition'
  image: ruby:2.6
  services:
    - postgres
    - redis

test1:
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
  script:
    - test1 project

test2:
  <<: *job_definition           # Merge the contents of the 'job_definition' alias
  script:
    - test2 project

& はアンカーの名前（job_definition）を設定し、<< は「与えられたハッシュを現在のハッシュにマージする」ことを意味し、* は名前のアンカー（再び job_definition）をインクルードします。 拡張バージョンは次のようになります： 

.job_template:
  image: ruby:2.6
  services:
    - postgres
    - redis

test1:
  image: ruby:2.6
  services:
    - postgres
    - redis
  script:
    - test1 project

test2:
  image: ruby:2.6
  services:
    - postgres
    - redis
  script:
    - test2 project

別の例を見てみましょう。 今回は、アンカーを使用して2つのサービスセットを定義します。これにより、.job_templateで定義されたscript ディレクティブと、.postgres_services と.mysql_services で定義されたservicesディレクティブをそれぞれ共有する、test:postgres とtest:mysqlという2つのジョブが作成されます： 

.job_template: &job_definition
  script:
    - test project
  tags:
    - dev

.postgres_services:
  services: &postgres_definition
    - postgres
    - ruby

.mysql_services:
  services: &mysql_definition
    - mysql
    - ruby

test:postgres:
  <<: *job_definition
  services: *postgres_definition
  tags:
    - postgres

test:mysql:
  <<: *job_definition
  services: *mysql_definition

拡大版はこのような感じです。 

.job_template:
  script:
    - test project
  tags:
    - dev

.postgres_services:
  services:
    - postgres
    - ruby

.mysql_services:
  services:
    - mysql
    - ruby

test:postgres:
  script:
    - test project
  services:
    - postgres
    - ruby
  tags:
    - postgres

test:mysql:
  script:
    - test project
  services:
    - mysql
    - ruby
  tags:
    - dev

非表示のジョブがテンプレートとして使われています。

注意：tags: [dev] はtags: [postgres]で上書きされていることに注意してください。
注意：include機能を利用するとき、複数のファイルにまたがって YAML アンカーを使うことはできません。 アンカーは定義されたファイル内でのみ有効です。 YAML アンカーを使う代わりに、 キーワード](#extends)を使うことができます。

before_script とafter_script のYAML アンカー

GitLab 12.5で導入されました。

YAML アンカー は before_script とafter_scriptで使うことができ、複数のジョブに定義済みのコマンドリストを含めることができます。

使用例： 

.something_before: &something_before
  - echo 'something before'

.something_after: &something_after
  - echo 'something after'
  - echo 'another thing after'

job_name:
  before_script:
    - *something_before
  script:
    - echo 'this is the script'
  after_script:
    - *something_after

script の YAML アンカー

GitLab 12.5で導入されました。

YAMLアンカー をscriptで使用することで、複数のジョブにあらかじめ定義されたコマンドのリストを含めることが可能になります。

使用例： 

.something: &something
  - echo 'something'

job_name:
  script:
    - *something
    - echo 'this is the script'

variablesのYAMLアンカー

YAML アンカー を variables と一緒に使うことで、複数のジョブで変数の割り当てを簡単に繰り返すことができます。 また 、グローバル変数をオーバーライドするような特定の variables ブロックを必要とするジョブの柔軟性を高めることもできます。

以下の例では、SAMPLE_VARIABLE 変数の使用に影響を与えることなく、GIT_STRATEGY 変数をオーバーライドします： 

# global variables
variables: &global-variables
  SAMPLE_VARIABLE: sample_variable_value
  ANOTHER_SAMPLE_VARIABLE: another_sample_variable_value

# a job that needs to set the GIT_STRATEGY variable, yet depend on global variables
job_no_git_strategy:
  stage: cleanup
  variables:
    <<: *global-variables
    GIT_STRATEGY: none
  script: echo $SAMPLE_VARIABLE

ジョブを隠す

GitLab 8.6 と GitLab Runner v1.1.1 で導入されました。

一時的にジョブを「無効」にしたい場合、ジョブが定義されている行をすべてコメントアウトするのではなく、「無効」にすることができます。 

#hidden_job:
#  script:
#    - run test

代わりに名前をドット(.)で始めると、GitLab CI/CDで処理されません。以下の例では、.hidden_job は無視されます： 

.hidden_job:
  script:
    - run test

この機能を使ってジョブを無視するか、特別なYAML機能を使って、隠されたジョブをテンプレートに変換します。

パイプラインをスキップする

コミットメッセージに[ci skip] や[skip ci]が含まれている場合、コミットは作成されますが、パイプラインはスキップされます。

あるいは、Git 2.10以降を使用している場合は、ci.skip Git pushオプションを渡すこともできます。

Gitのプッシュを処理する

GitLab はgit push で複数の変更をプッシュする場合、ブランチとタグのパイプラインを最大 4 つまで作成します。

この制限は、更新されたマージ リクエスト パイプラインには影響しません。 マージ リクエストパイプラインを使用する場合、更新されたすべてのマージ リクエストにパイプラインが作成されます。

非推奨のパラメータ

以下のパラメータは非推奨です。

グローバルに定義された types

非推奨:types は非推奨で、将来のリリースで削除される可能性があります。代わりに typesを使用してください。

ジョブに定義された type

非推奨:type は非推奨で、将来のリリースで削除される可能性があります。代わりに typeを使用してください。

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

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

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

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