- 導入
- 設定パラメータ
- グローバルパラメータ
- パラメータの詳細
-
variables
- YAML の特殊機能
- パイプラインをスキップする
- Gitのプッシュを処理する
- 非推奨のパラメータ
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 CI/CDの使用例を参照してください。
- 企業で使われる大規模な
.gitlab-ci.yml
ファイルのサンプルとして、GitLab
の開発で使われている.gitlab-ci.yml
ファイルを参照してください。
GitLab CI/CDについての追加情報はこちらをご覧ください。
- CI/CDの簡単な設定の動画をご覧ください。
- あなたの組織におけるCI/CDの事例を作るウェブキャストを見て、CI/CDの利点とCI/CDによる自動化の結果を測定する方法を学ぶ。
- GitLabを使用して、[Verizonがリビルドを30日間から8時間以内に短縮した方法を学ぶ。
導入
パイプラインの設定はジョブから始まります。ジョブは .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_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にリリースオブジェクトを生成するよう指示します。 |
グローバルパラメータ
一部のパラメータはグローバルレベルで定義する必要があり、パイプライン内のすべてのジョブに影響を与えます。
グローバルデフォルト
いくつかのパラメータは、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
の要素の順序が、ジョブの実行順序を定義します。
- 同じステージのジョブは並列に実行されます。
- 次のステージのジョブは、前のステージのジョブが正常に終了した後に実行されます。
3つのステージを定義した次の例を考えてみましょう。
stages:
- build
- test
- deploy
- はじめに、
build
のジョブがすべて並列に実行されます。 -
build
のすべてのジョブが成功した場合、test
のジョブが並列に実行されます。 -
test
のすべてのジョブが成功した場合、deploy
のジョブが並列に実行されます。 -
deploy
のすべてのジョブが成功した場合、コミットは成功
とマークされます。 - 前のジョブのいずれかが失敗した場合、コミットは
失敗
とマークされ、それ以降のステージのジョブは実行されません。
また、特筆すべきエッジケースが2つあります。
-
.gitlab-ci.yml
にstages
が定義されていない場合、デフォルトではbuild
、test
、deploy
がジョブのステージとして使用されます。 - ジョブで
stage
を指定していない場合、ジョブにはtest
ステージが割り当てられます。
workflow:rules
GitLab 12.5で導入されました
トップレベルの workflow:
キーは、パイプラインの全体に適用され、パイプラインが作成されるかどうかを決定します。現在、ジョブ内で定義されたrules:
と同様に動作するように、単一のrules:
キーを受け入れます。これは、パイプラインの動的な設定を可能にするためです。
GitLab CI/CDとworkflow: rules
を初めて使う方には、workflow:rules
のテンプレートが役立ちます。
独自の workflow: rules
を定義するのに、現在利用可能な設定オプションは以下の通りです。
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
メソッドは変数展開をサポートしていません。
.gitlab-ci.yml
の設定は、パイプラインの作成時に評価されます。
設定は時間的にスナップショットであり、データベースに永続化されています。参照された .gitlab-ci.yml
の設定を変更しても、次のパイプラインが作成されるまで GitLab には反映されません。インクルード
で定義されたファイルは
-
.gitlab-ci.yml
にあるものをディープマージされます。 - キーワード
include
の位置にかかわらず、常に最初に評価され、.gitlab-ci.yml
の内容とマージされます。
.gitlab-ci.yml
内のローカル定義は、インクルードされた定義を上書きします。include
によってソースされた異なるYAMLファイル間で使用することはサポートされていません。同一ファイル内のアンカーのみを参照する必要があります。YAMLアンカーを使う代わりに、extends
キーワードを使うことができます。
include:local
include:local
は .gitlab-ci.yml
と同じリポジトリのファイルをインクルードします。
ルートディレクトリ(/)
からの相対的なフルパスを使用して参照されます。
設定ファイルと同じブランチにある、すでにGitで管理されているファイルしか使えません。つまり、include:local
を使う場合は、.gitlab-ci.yml
とローカルファイルの両方が同じブランチにあることを確認してください。
すべてのネストされたインクルードは同じプロジェクトのスコープ内で実行されるので、ローカルインクルード、プロジェクトインクルード、リモートインクルード、テンプレートインクルードを使用することができます。
使用例。
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イメージを指定するために使用します。
使用例:
- 簡単な定義例は、
.gitlab-ci.yml
からのimage
とservices
の定義を参照してください。 - 詳しい使用方法については、Dockerインテグレーションのドキュメントを参照してください。
image:name
詳しくは、「image
の利用可能な設定」を参照してください。
image:entrypoint
詳しくは、「image
の利用可能な設定」を参照してください。
services
image
で指定したベースイメージにリンクしたサービスのDockerイメージを指定するために使用します。
使用例:
- 簡単な定義例は、
.gitlab-ci.yml
からのimage
とservices
の定義を参照してください。 - 詳しい使用方法については、Dockerインテグレーションのドキュメントを参照してください。
- サービスの使用例としては、GitLab CI/CDのサービスを参照してください。
services:name
詳細については、「services
で利用可能な設定」を参照してください。
services:alias
詳細については、「services
で利用可能な設定」を参照してください。
services:entrypoint
詳細については、「services
で利用可能な設定」を参照してください。
services:command
詳細については、「services
で利用可能な設定」を参照してください。
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
(成功
)でジョブは終了します。
グローバルに定義された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マルチラインブロックスカラ指標を使用して、長いコマンドを複数行のコマンドに分割して可読性を向上させることができます。
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
.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です。
.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
キーワードは、パイプラインにジョブを追加するかどうかを決定するジョブポリシーを設定する方法です。
一致するまで、個々のルール句のリストを順番に評価します。 一致した場合、設定に応じて、そのジョブはパイプラインに含まれるか、パイプラインから除外されます。 含まれる場合、ジョブには特定の属性が追加されます。
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
/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
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
(基本)
rules
構文は、ジョブがいつ実行されるべきか、あるいは実行されないべきかを定義するための改良された、より強力な解決方法です。 パイプラインを最大限に活用するために、only/except
ではなく、rules
を使用することを検討してください。only
とexcept
はジョブが作成されるタイミングを制限するためにジョブポリシーを設定する2つのパラメータです。
-
only
は、ジョブが実行されるブランチとタグの名前を定義します。 -
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
-で始まるタグ名やブランチ名にはマッチしません。
^
と$
アンカーを使用できます。例えば、/issue/
だけの場合はsevere-issues
というブランチ名にマッチしますが、(/^issue-.*$/
と同等の)/^issue-/
はマッチしません。
only
/except
でサポートされる正規表現
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)
次の例では、以下のすべてが「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
の拡張子を持つファイル。
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:この機能をマージリクエストパイプラインで使用せず、新しいブランチやタグで使用する際には、注意すべき点がいくつかあります。
マージリクエストパイプラインで 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
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
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
は、以下のいずれかの値を設定することができます。
-
on_success
- 前のステージのすべてのジョブが成功した(あるいは、allow_failure
とマークされているため成功したとみなされる)場合にのみジョブを実行します 。 これがデフォルトです。 -
on_failure
- 前のステージの少なくとも1つのジョブが失敗した場合にのみジョブを実行します。 -
always
- 前のステージのジョブのステータスと関係なくジョブを実行します。 -
manual
- ジョブを手動で実行します (GitLab 8.10 で追加されました)。 詳細は、以下のマニュアルアクションを参照してください。 -
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
上記のスクリプトは:
-
build_job
が失敗した場合のみ、cleanup_build_job
を実行します。 - 成功・失敗に関わらず、常にパイプラインの最後のステップとして
cleanup_job
を実行します。 - 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
が設定されており、その成否はパイプライン全体のステータスには寄与しません。 つまり、たとえ手動アクションが失敗しても、パイプラインは成功と判定されます。
手動アクションは書き込みアクションとみなされるので、ユーザーがアクションを起動する際は、保護ブランチのパーミッションが使用されます。言い換えると、パイプラインの手動アクションを起動するには、そのブランチをマージする権限が必要です。保護環境を利用して、不正なユーザーによって実行されないように、より厳密に手動デプロイを保護することが可能です。
when:manual
と trigger
を一緒に使用すると、jobs:#{job-name} when
should be on_success, on_failure or always
というエラーになります。これは、when:manual
はtriggerの使用を妨げるためです。手動ジョブを保護する
保護環境を使用して、手動ジョブの実行を許可されたユーザーを定義することができます。 保護環境に関連付けられたユーザーのみが手動ジョブを実行することを許可することで、以下のようないくつかの特別なユースケースを実装することが可能です。
- より正確に誰が環境にデプロイできるかを制限します。
- 承認されたユーザーが「承認」するまでパイプラインをブロックできるようにします。
このためには:
-
ジョブに
environment
を追加します。 例えば:deploy_prod: stage: deploy script: - echo "Deploy to production server" environment: name: production url: https://example.com when: manual only: - master
-
保護環境の設定で、環境(上の例では
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
- GitLab 8.9 で導入されました。
- 環境についてのドキュメントでは、環境についての詳細と、多くの例を見つけることができます。
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 がコードをチェックアウトしようとしないようにしています。
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
で利用可能な設定」を参照してください。
動的な環境
使用例
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
) からの相対パスで指定してください。以下のように、ワイルドカードのグロブパターンを使用できます。
-
GitLab Runner 13.0 以降では、
doublestar.Glob
を使用できます。 - GitLab Runner 12.10 以前のバージョンでは、
filepath.Math
を使用できます。
以下の例では、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
になります。つまり、すべてのジョブ間でキャッシュが共有されます。
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
- GitLab 13.1 で導入されました。
- GitLab Runner 13.1 が必要です。
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
になります。
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の未追跡ファイルをアーティファクトとして追加するために使用します。
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には
、以下のいずれかの値を設定することができます。
-
on_success
- ジョブが成功したときのみ、アーティファクトをアップロードします。 これはデフォルトです。 -
on_failure
- ジョブが失敗したときのみ、アーティファクトをアップロードします。 -
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
- GitLab Premium11.8で導入されました。
- 12.8でGitLab Coreに移行しました。
triggerは
、下流パイプラインのトリガーを定義することができます。trigger
定義から作成されたジョブがGitLabによって開始されると、下流パイプラインが作成されます。
このキーワードにより、2種類の下流パイプラインを作成することができます。
注:triggerと
when:manual
を一緒に使うと、jobs:#{job-name} when should be on_success, on_failure or always
, becausewhen:manual
prevents 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を含むことができます。
これらの方式に対応しています。
tag_name
-
name
(オプション) -
description
(オプション) -
ref
(オプション) -
milestones
(オプション) -
release_at
(オプション)
リリースは、ジョブがエラーなく処理された場合のみ作成されます。 リリース作成中に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の次期バージョンでこの要件を取り除くためのイシューが存在します。
パイプラインが複数のリリースジョブを
持つ例。
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 clean
flags のデフォルトは-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と
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に
設定するディレクトリは、実行ファイルと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の
複雑さを大幅に軽減することができます。
ほとんどの場合、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]
に上書きされたことに注意してください。
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/