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についての追加情報はこちらをご覧ください。

Note: 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です。

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

各ジョブは一意の名前を持たなければなりませんが、ジョブ名として使用できないの予約されたキーワードがいくつかあります。

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

GitLabエンタープライズエディションでは、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 (removed in GitLab 13.0)、artifacts:reports:performance、artifacts:reports:load_performanceartifacts: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にリリースオブジェクトを生成するよう指示します。
Note: パラメータ types と type は 非推奨 です。

グローバルパラメータ

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

グローバルデフォルト

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

以下のジョブパラメータは、default:ブロック内で定義することができます。

以下の例では、ruby:2.5イメージをデフォルトとして設定されており、すべてのジョブで使用されます。ただし、rspec 2.6ジョブだけはruby:2.6イメージを使用しています。 

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

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

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

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

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

また、特筆すべきエッジケースが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つが一致するまで評価されます。一致するものがない場合は、最後の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メソッドは変数展開をサポートしていません。

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

インクルードで定義されたファイルは

  • .gitlab-ci.ymlにあるものをディープマージされます。
  • キーワード include の位置にかかわらず、常に最初に評価され、.gitlab-ci.yml の内容とマージされます。
Tip: マージを使用して、ローカル定義に含まれるCI/CDコンフィギュレーションをカスタマイズしてオーバーライドします。.gitlab-ci.yml 内のローカル定義は、インクルードされた定義を上書きします。
Note: YAMLアンカーをincludeによってソースされた異なるYAMLファイル間で使用することはサポートされていません。同一ファイル内のアンカーのみを参照する必要があります。YAMLアンカーを使う代わりに、extendsキーワードを使うことができます。

include:local

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

設定ファイルと同じブランチにある、すでにGitで管理されているファイルしか使えません。つまり、include:localを使う場合は、.gitlab-ci.ymlとローカルファイルの両方が同じブランチにあることを確認してください。

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

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

使用例。 

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

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

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

スクリプトは、ジョブが必要とする唯一の必須キーワードです。Runnerが実行するシェルスクリプトです。使用例: 

job:
  script: "bundle exec rspec"

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

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

job:
  script:
    - uname -a
    - bundle exec rspec
Note: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 (成功)でジョブは終了します。

グローバルに定義された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マルチラインブロックスカラ指標を使用して、長いコマンドを複数行のコマンドに分割して可読性を向上させることができます。

Warning: 複数のコマンドを一つのコマンド文字列にまとめた場合、最後のコマンドの失敗や成功のみが報告され、バグによる以前のコマンドの失敗は間違えて無視されます。 ジョブの成功がこれらのコマンドの成否に依存する場合は、これらのコマンドを別個の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.

> (folded) 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に依存します。 これは、ジョブを異なるステージにグループ化し、同じステージのジョブを(一定の条件のもとで)並列に実行することを可能にします。 例えば、以下のような場合には、ジョブを複数のステージにグループ化することができます。 

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のcuncurrent設定を変更した場合。

.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
Note:パイプラインは、.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
Note:script: rake test は script: rake rspecで上書きされていることに注意してください。

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

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

extends は複数レベルの継承をサポートしていますが、3つ以上のレベルを使用することは推奨されていません。 サポートされている最大ネスティングレベルは10です。 

.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と組み合わせて、設定ファイル全体で動作します。

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

.template:
  script:
    - echo Hello!

.gitlab-ci.ymlの中では、次のように使用できます。 

include: included.yml

useTemplate:
  image: alpine
  extends: .template

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

rules

GitLab 12.3 で導入されました。

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

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

Caution: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により、ジョブはパイプラインに追加されます。
Caution最終のルールとしてとして when: on_success、always、delayed を使用すると、2 つのパイプラインが同時に開始されることがあります。 プッシュパイプラインとマージリクエストパイプラインは、同じイベント (オープンしているマージリクエストのソースブランチへのプッシュ) によって開始されることがあります。

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つの式に結合することができ、変数にマッチする構文を使用します。

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_failureruleのようなルールは、常にマッチし、到達した場合には常に使用されます。
  • ルールがマッチし、whenが定義されていない場合、ルールはジョブのデフォルトのwhenとしてon_successを使用します。
  • 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
Note: パフォーマンス上の理由から、パターン付きの exists の使用は 10000 回のチェックに制限されています。 10000 回目のチェック後、パターン付きのグロブを持つルールは常に「true」と判定されます。
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句、change句、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 (基本)

Note: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 コマンドを使用して作成したパイプラインの場合。

以下の例では、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

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

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上のすべてのブランチに対してジョブを実行します。

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

例えば、 

job:
  script: echo 'test'

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

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

正規表現

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

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

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

Tipタグ名やブランチ名の一部に正規表現がマッチするのを防ぐために、^と$アンカーを使用できます。例えば、/issue/だけの場合はsevere-issuesというブランチ名にマッチしますが、（/^issue-.*$/と同等の）/^issue-/はマッチしません。

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

Warning:これは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 (上級)

Warning:これは_アルファ_機能であり、予告なしにいつでも変更される可能性があります。

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)

次の例では、以下のすべてが「true」の場合にのみtestジョブが作成されます。

  • スケジュールされているパイプライン、またはmasterで実行されているパイプライン。
  • 変数キーワードがマッチしている。
  • プロジェクトの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)

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

  • 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設定と同じ値を取ることができます。

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

deploy:
  only:
    refs:
      - master
      - schedules

only:kubernetes/except:kubernetes

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

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

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

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ポリシーは、GitLab 11.4 で導入されました。

only や except でchanges キーワードを指定すると、Gitプッシュで変更されたファイルに基づいて、ジョブを作成するかどうかを定義することができます。

つまり、only:changesポリシーは、以下のパイプラインの場合に有用です。

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

上記の3つ以外のソースのパイプラインのように、Gitプッシュイベントがない場合は、指定したファイルが新しいのか古いのか変更を判断することができず、常に「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ジョブが作成されます。ただし、プッシュされたコミットの1つで、以下のファイルのいずれかが変更されている必要があります。

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

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

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

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

build:
  script: npm run build
  except:
    changes:
      - "*.md"

CAUTION:Waring:この機能をマージリクエストパイプラインで使用せず、新しいブランチやタグで使用する際には、注意すべき点がいくつかあります。

Waring:この機能をスケジュールパイプラインで使用する際には、いくつかの注意点があります。
マージリクエストパイプラインで 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 で、nees配列のジョブ数の最大値が 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ジョブは、linux:buildジョブが終了するとすぐに実行され、mac:buildが終了するのを待たずに実行されます。

  • macOS パス: mac:rspec と mac:rubocop ジョブは mac:build ジョブが終了するとすぐに実行され、linux: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:を持つまたは参照されるすべてのジョブで、明示的にstageを定義する必要があります。
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つの構文例のartifactsは、build_job_1ではtrue、build_job_2とbuild_job_3では両方ともデフォルトのtrueとなります。そのため、rspecは3つのすべてのビルドジョブのアーティファクトをダウンロードします。 

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
Note:parallel:で実行されているジョブからのアーティファクトのダウンロードはサポートされていません。

tags

tagsは、このプロジェクトの利用可能なすべてのRunnerから特定のRunnerを選択するために使用されます。

Runnerを登録する際に、Runnerのタグを指定することができます。

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

job:
  tags:
    - ruby
    - postgres

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

タグは、複数のプラットフォームで異なるジョブを実行するためにも使用できます。例えば、OS X Runnerに osx というタグを付け、Windows Runnerにwindowsというタグを付けた場合、以下のようなジョブがそれぞれのプラットフォーム上で実行されます。 

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 が設定されており、その成否はパイプライン全体のステータスには寄与しません。 つまり、たとえ手動アクションが失敗しても、パイプラインは成功と判定されます。

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

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

Note: when:manual と trigger を一緒に使用すると、jobs:#{job-name} when should be on_success, on_failure or alwaysというエラーになります。これは、when:manualはtriggerの使用を妨げるためです。
手動ジョブを保護する

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

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

このためには:

  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で導入されました。

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

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

environmnetキーワードを定義する、最も単純な例は次のようなものです。 

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パラメータは、定義されたCI変数のいずれかを使用することができます。事前定義済み変数、セキュア変数、.gitlab-ci.ymlのvariables などがあります。しかし、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以前はGitLabのUIでのみURLを追加することができましたが、現在は.gitlab-ci.ymlで定義することが推奨されています。
  • urlパラメータは、定義されたCI変数のいずれかを使用することができます。事前定義済み変数、セキュア変数、.gitlab-ci.ymlのvariables などがあります。しかし、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のWeb UIからの手動操作が必要になります。

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

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

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

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

さらに、両方のジョブは rulesまたは only/exceptの設定を一致させる必要がありあます。上の例で、設定が一致していない場合は、review_appジョブを含むパイプラインにstop_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日に設定されます。

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

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で利用可能な設定」を参照してください。

Note:Kubernetes設定はGitLabが管理するKubernetesクラスターではサポートされません。サポートの進捗状況については、関連する課題を参照してください。

動的な環境

  • GitLab 8.12 と GitLab Runner 1.6 で導入されました。
  • CI_ENVIRONMENT_SLUGはGitLab 8.15で導入されました。
  • nameとurlパラメータでは、定義されたCI変数のいずれかを使用することができます。事前定義済み変数、セキュア変数、.gitlab-ci.ymlのvariablesなどがあります。しかし、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 revew appジョブは、review/$CI_COMMIT_REF_NAMEという名前の環境を動的に作成します。この$CI_COMMIT_REF_NAMEはRunnerによって設定される環境変数です。また、環境名に基づいて設定される、$CI_ENVIRONMENT_SLUG変数は、URLに含めるのに適しています。 例えば、レビューアプリのデプロイが 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) からの相対パスで指定してください。以下のように、ワイルドカードのグロブパターンを使用できます。

以下の例では、binariesフォルダの.apkで終わるファイルと.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になります。つまり、すべてのジョブ間でキャッシュが共有されます。

Note:: 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 を使用すると、指定のプレフィックスと cache:key:files で計算された SHA を組み合わせてキャッシュキーを構成できます。 例えば test というプレフィックスを追加すると、 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というプレフィックスを追加すると、キャッシュキーは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 に従ったものを使うことができます。

拡張子が*.oのファイルを除く、binaries/以下のすべてのファイルを保存する例: 

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

artifacts:untracked でマッチしたファイルを、artifacts:exclude を使って除外することもできます。

artifacts:expose_as

GitLab 12.5で導入されました。

expose_as キーワードを使用すると、マージリクエスト 画面でジョブのアーティファクトを公開することができます。

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

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

この設定では、GitLabは file.txtを指すartifact 1というリンクをマージリクエストに追加します。

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

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

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

  • 変数を使用して artifacts:path を定義すると、マージリクエスト画面にアーティファクトが表示されません。
  • マージリクエストごとに公開できるアーティファクトは最大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 で、ダウンロードされたときには artifacts.zipになります。

Note: ブランチ名にスラッシュが含まれている場合 (例えば 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:path で定義したパスのファイルに加えて)すべてのGitの未追跡ファイルをアーティファクトとして追加するために使用します。

Note: 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以降、ref 用の最新のアーティファクトを削除できないようにロックし、有効期限に関わらず保持することができます。 この機能はデフォルトでは無効で、実運用には適していません。 テスト用に:keep_latest_artifact_for_refと:destroy_only_unlocked_expired_artifacts feature flagsを有効にすると、この機能は使用できるようになります。

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レポートでは、Terraformのtfplan.jsonファイルを収集します。
artifacts:reports:codequality CodeQualityレポートは、CodeQualityの問題を収集します。
artifacts:reports:sast sastレポートは、Static Application Security Testingの脆弱性を収集するものです。
artifacts:reports:dependency_scanning dependency_scanningレポートは、Dependency Scanning の脆弱性を収集します。
artifacts:reports:container_scanning container_scanningレポートは、Container Scanning の脆弱性を収集します。
artifacts:reports:dast dastレポートは、Dynamic Application Security Testingの脆弱性を収集したものです。
artifacts:reports:license_management license_managementレポートは、Licenses を収集します（GitLab 13.0 から削除されました）。
artifacts:reports:license_scanning license_scanningレポートは、Licenses を収集します。
artifacts:reports:performance パフォーマンスレポートは、Browser Performanceのメトリックスを収集します。
artifacts:reports:load_performance load_performanceレポートは、負荷性能のメトリックスを収集します。
artifacts:reports:metrics メトリックスレポートは、メトリックスを収集します。

dependencies

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

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

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

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

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

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: ランナーシステムの障害（例えば、ジョブセットアップの失敗）があった場合に再試行します。
  • missing_dependency_failure: 依存関係が見つからない場合に再試行する。
  • runner_unsupported: ランナーがサポートされていない場合、再試行する。
  • stale_schedule: 遅延されたジョブが実行されなかった場合に再試行する。
  • job_execution_timeout: スクリプトがジョブに設定された最大実行時間を超えた場合、再試行します。
  • archived_failure: ジョブがアーカイブされ、実行できない場合に再試行する。
  • unmet_prerequisites: ジョブが前提条件となるタスクを完了できなかった場合に再試行します。
  • scheduler_failure: スケジューラがランナーへのジョブ割り当てに失敗した場合に再試行します。
  • 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以下でなければなりません。

ジョブ名1/Nから ジョブ名N/Nまで順番に名前が付けられ、同じジョブのインスタンスがN個並列に実行されます。

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

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

test:
  script: rspec
  parallel: 5

TIP:TIP:テストスイートを並列ジョブで並列化する。 言語によって、これを容易にするツールは異なる。

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, becausewhen:manualprevents triggers being used というエラーが発生します。

マルチプロジェクトパイプラインのためのシンプルな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でパイプラインを連携させる

デフォルトでは、下流パイプラインが作成されると同時に、トリガージョブは 成功ステータスで完了します。

トリガージョブが下流（マルチプロジェクトまたは子）パイプラインの完了を待つようにするには、strategy: dependを使用します。 これにより、トリガージョブはトリガされたパイプラインが完了するまで「running」ステータスで待機します。 その時点で、トリガージョブは完了し下流のジョブと同じステータスを表示します。 

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

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

  • ステップ1のみ実行中または保留中の場合、キャンセルされる。
  • ステップ2の実行を開始するとキャンセルされません。

注）注意：無停止型ジョブが実行されると、最終的なジョブの状態にかかわらず、パイプラインがキャンセルされることはありません。

resource_group

GitLab 12.7で導入されました。

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

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

.gitlab-ci.ymlでジョブに対してresource_groupキーを定義すると、同一プロジェクトの異なるパイプライン間でジョブの実行が相互に排他的になります。 同じリソースグループに属する複数のジョブが同時にキューに入った場合、そのうち一つのジョブだけが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-cliDocker イメージ

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

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

Script

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

script:
  - echo 'release job'

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

パイプラインが複数のリリースジョブを持つ例。 

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用の個々の例を組み合わせると、次のようなコードになります。 タグをどのように生成するかによって、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コンテナに送られます。 また、スクリプトエントリから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にアップロードするための特別なジョブです。 特別な構文を持っているので、以下の2つの要件を満たしている必要があります。

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

以下の例では、プロジェクトのルートから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ではサポートされていませんが、将来的にはサポートされる可能性があります。 最新情報は、support Git strategy with Kubernetes executor feature proposalを参照してください。

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以降が必要です。 Dockerベースではない実行ファイルでGitLab Runnerを使用する場合、Gitバージョンがその要件を満たしているか確認してください。 以下と同等です。 

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

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

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

Git checkout

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

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

falseに設定すると、Runnerは次のようになります。

  • fetchするとき - リポジトリを更新し、作業コピーを現在のリビジョンに残します。
  • cloneするとき - リポジトリをcloneし、作業コピーはデフォルトブランチに残します。

この設定をtrueにすると、cloneとfetch の両方の戦略において、Runner は CI パイプラインに関連するリビジョンに作業コピーをcheckoutすることになります。 

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_CHECKOUT: "false "を指定すると、git cleanは無効になります。

GIT_CLEAN_FLAGSがある場合。

  • 指定しない場合、git cleanflags のデフォルトは-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 GitLab 12.10以降、ジョブ内のセクションでエラーが発生した後に実行しようとした回数。 No Such Containerエラーの後にジョブのセクションを実行する試行回数(Docker executorのみ)。

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

使用例。 

variables:
  GET_SOURCES_ATTEMPTS: 3

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

Shallow cloning

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

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

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

注：深さ1を使用し、ジョブのキューやリトライジョブがある場合、ジョブが失敗することがあります。

Git のフェッチやクローン作成はブランチ名などの参照に基づいて行われるので、Runnerは特定のコミット SHA をクローンすることはできません。 キューに複数のジョブがある場合や古いジョブを再試行している場合、テストするコミットはクローンする Git の履歴内にある必要があります。GIT_DEPTHを小さく設定すると、古いコミットを実行できなくなります。 ジョブログで未解決の参照を確認できます。 その場合はGIT_DEPTHを大きくして考え直した方がよいでしょう。

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

最後の3つのコミットのみを取得またはクローンする場合。 

variables:
  GIT_DEPTH: "3"

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

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

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

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

デフォルトでは、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に設定するディレクトリは、実行ファイルとrunners.bills_dirの設定に依存します。

並行処理を行う

builds_dirがジョブ間で共有されている場合、複数のジョブが同じディレクトリで作業する可能性があるためです。 GitLab Runner はこの状況を防ごうとしません。 Runner の設定要件に従うのは、管理者と開発者次第です。

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

  • CI_CONCURRENT_ID: 指定された実行者内で実行されているすべてのジョブの一意なIDです。
  • $CI_CONCURRENT_PROJECT_ID: Unique ID for all jobs running within the given executor and project.

どのようなシナリオでも、どのような実行環境でもうまく動作する最も安定した設定は、GIT_CLONE_PATHに$CI_CONCURRENT_IDを使用することです。 たとえば、次のようになります。 

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

test:
  script:
    - pwd

CI_CONCURRENT_PROJECT_IDは、$CI_PROJECT _PATH がリポジトリのパスを提供するので、$CI_PROJECT_ID と共に使用されるべきです。 つまり、グループ/サブグループ/プロジェクト。 例えば 

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

test:
  script:
    - pwd

ネストされたパス

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

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

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のパラメータを継承するtest1とtest2という 2 つのジョブを作成し、それぞれ独自のカスタムスクリプトを定義しています。 

.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つのサービスを定義します。 この例では、test:postgresとtest:mysqlという2つのジョブを作成し、それぞれ.job_templateで定義したscriptディレクティブと.postgres_servicesと.mysql_servicesで定義したservicesディレクティブを共有することにします。 

.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

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

注：タグ：[dev]はタグ：[postgres]に上書きされたことに注意してください。

注意: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は、1回のgit pushで複数の変更をpushする場合、最大で4つのブランチとタグのパイプラインを作成します。

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

非推奨のパラメータ

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

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

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

ジョブに定義されたtypes

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

グローバルに定義された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/