Edited at

GitLab CI/CDパイプライン設定リファレンス(日本語訳:GitLab CI/CD Pipeline Configuration Reference)

v12.0.3を元に翻訳を更新しました(2019/07/24)。

ググラビリティ向上の為にこちらのページも残してありますが、以下のページにも

アップロードしてあります。こちらの方が表など見やすいかと思います。

https://gitlab.com/stylez-co-jp/gitlab-ce/tree/dev-v12.0.3-ja.1/doc-ja/ci/yaml

本記事は、

doc/ci/yaml/README.md · master · GitLab.org / GitLab Community Edition · GitLab

https://docs.gitlab.com/ce/ci/yaml/


https://gitlab.com/gitlab-org/gitlab-ce/blob/v12.0.3/doc/ci/yaml/README.md

を翻訳した文章ですが、より詳しい内容の書籍が日本語で発売されました。

本記事に物足りないと感じた方は、ご購入をお勧めします。

現在、本記事は2017年時点の英語ドキュメントを元に翻訳していますが、古くなっているので更新を予定しています(現在進捗20%ほど)。内容は随分と変わってしまっていますので下記の内容は参考程度にお願いいたします。

英語の部分もまだありますが、半分を過ぎたので一旦公開いたします。 一旦完成です。

相対リンクなどは直す予定はありませんので、リンクをたどりたい方は以下のURLで公開しているものをご利用ください。

https://gitlab.com/stylez-co-jp/gitlab-ce/tree/dev-v12.0.3-ja.1/doc-ja/ci/yaml

リンクがあっても翻訳されているとは限りません。ご了承ください。

表などもgitlab.comの方が見やすいかと思います。

更新の通知を受け取りたい方は、「ストック」しておいていただければ更新通知をお送りいたします。

Variablesに関するリファレンスも翻訳しました。

よろしければこちらもどうぞ。

GitLab CI/CD Variables を翻訳しました。 - Qiita

https://qiita.com/ynott/items/4c5085b4cd6221bb71c5


GitLab実践ガイド - インプレスブックス

https://book.impress.co.jp/books/1116101163



本記事は、

doc/ci/yaml/README.md · master · GitLab.org / GitLab Community Edition · GitLab

https://gitlab.com/gitlab-org/gitlab-ce/blob/v12.0.3/doc/ci/yaml/README.md

を翻訳した記事です。



type: reference


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

GitLab CI/CD pipelinesは、プロジェクト毎に.gitlab-ci.ymlというYAMLファイルを使って設定します。

.gitlab-ci.ymlファイルにパイプラインの構造と実行順序を定義して以下の内容を実行します:



  • GitLab Runnerで何を動かすか。

  • 特定の条件になったときにどうするかを指定します。例えば、プロセスが成功または失敗した場合です。

こちらの章では、CI/CDパイプラインの設定について解説しています。その他のCI/CDの設定については以下を参照してください:

パイプラインの設定方法についての様々なサンプルについては以下を参照してください:

- GitLab CIの簡単な紹介については、quick start guide

- サンプル集については、 GitLab CI/CD Examples

- 企業での大規模な .gitlab-ci.yml 利用の場合には、.gitlab-ci.yml file for gitlab-ce

NOTE: 注意:

ミラーリングリポジトリでGitLabの外から取得の場合にはそのプロジェクト内でパイプライントリガーを有効にする必要がある場合があります。

Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates


イントロダクション

パイプライン設定はジョブから始まります。ジョブは、.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)といったスクリプトを実行することもできます。

ジョブ定義は、Runners に渡されて、Runner の実行環境で実行されます。

重要なことは、一つ一つのジョブはその他のジョブとは全く分離されており、全く連携しておらず独立して

実行されると言うことです。


.gitlab-ci.yml の構文チェック

GitLab CIのそれぞれの実行環境にはLintというデバッグツールが組み込まれていて、.gitlab-ci.ymlの構文

チェックを行います。プロジェクトのci/lint配下にLintがあります。URLでいうと

https://gitlab.example.com/gitlab-org/project-123/-/ci/lint になります。

(訳注:CI/CDパイプラインの右上のボタン)


ジョブ名として利用できない予約語

ジョブ名はそれぞれ重複しないようにする必要があり、さらにジョブ名として 利用できない予約語があります:


  • image

  • services

  • stages

  • types

  • before_script

  • after_script

  • variables

  • cache


予約語を使う場合

truefalse といった特定の値を使っていてバリデーションエラーがあった場合には、次のようにすると回避できる場合があります:


  • クオートでくくる


  • /bin/true等の別の表現に変更する


設定パラメーター

ジョブとは、ジョブの挙動を設定するパラメーターのリストになったものです。

以下のリストは、ジョブで使えるパラメーターです:

パラメーター名
詳細

script
Runnerで実行されるシェルスクリプト

image
利用するDockerコンテナイメージ。次の指定も可能: image:nameimage:entrypoint.

services
サービスで利用するDockerコンテナイメージ。次の指定も可能:: services:name, services:alias, services:entrypointservices:command.

before_script
ジョブを実行する前に動かすコマンドを設定。

after_script
ジョブを実行した後に動かすコマンドを設定。

stages
パイプラインのステージリストを定義。

stage
ジョブのステージ名を定義 (デフォルト: test).

only
ジョブが実行される条件を設定。次の指定も可能: only:refs, only:kubernetes, only:variables, and only:changes.

except
ジョブが実行されない条件を設定。次の指定も可能:: except:refs, except:kubernetes, except:variables, and except:changes.

tags
Runnerに設定されているタグを元に特定のRunnerで実行。

allow_failure
ジョブの失敗を許容する。失敗したジョブでは、コミットステータスが変更されない。

when
ジョブを実行するタイミング。次の指定も可能: when:manual and when:delayed.

environment
ジョブをデプロイする環境名。次の指定も可能: environment:name, environment:url, environment:on_stop, and environment:action.

cache
ジョブ間で共有するキャッシュのファイルリスト。次の指定も可能: cache:paths, cache:key, cache:untracked, and cache:policy.

artifacts
ジョブが成功したときに、ジョブに紐付ける成果物のファイルリストとディレクトリ。次の指定も可能: artifacts:paths, artifacts:name, artifacts:untracked, artifacts:when, artifacts:expire_in, artifacts:reports, and artifacts:reports:junit.

In GitLab Enterprise Edition, these are available: artifacts:reports:codequality, artifacts:reports:sast, artifacts:reports:dependency_scanning, artifacts:reports:container_scanning, artifacts:reports:dast, artifacts:reports:license_management, artifacts:reports:performance and artifacts:reports:metrics.

dependencies
複数のジョブの依存関係を設定する。そのジョブ間で成果物を渡すことができる。

coverage
ジョブのテストのカバレッジ抽出設定。

retry
失敗時に、ジョブを自動的にいつ、何回、リトライするかどうかを設定。

parallel
ジョブを実行するインスタンスを並列で実行する数を設定。

trigger
連携した下位のパイプラインの呼び出し先を設定。

include
外部のYAMLファイルを読み込んでジョブに追加する設定。次の指定も可能: include:local, include:file, include:template, and include:remote.

extends
他の場所に記述したジョブの内容を読み込んで拡張する設定。

pages
GitLabページを使ってジョブの結果をアップロードする設定。

variables
ジョブレベル毎にジョブの変数を設定。 |

NOTE: 注意:

typestypeパラメーターは、deprecatedとなっています。


パラメーター詳細

CI/CDパイプラインを構成するパラメーターの使い方について詳細に説明します。


script

script はジョブに唯一の必須のパラメーターです。 中身はシェルスクリプトです。

これがRunnerで実行されます。例えば:

job:

script: "bundle exec rspec"

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

job:

script:
- uname -a
- bundle exec rspec

NOTE: 注意:

場合によっては、 script のコマンドを シングルまたはダブルクオートでくくる必要があります。

例えば、コロン(:) を含んだコマンドは引用符で囲む必要があり、そうすることによりYAMLパーサーは

"key:value"のペアではなく文字列として解釈することができます。次の特殊文字を使う場合は注意

してください:

:, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `.


image

ジョブを実行するベースとなるa Docker imageを指定します。

詳細:


image:name

dockerコンテナを起動する時の拡張オプション

詳細な説明については、Available settings for imageを参照


image:entrypoint

dockerコンテナを起動する時の拡張オプション

詳細な説明については、Available settings for imageを参照


services

サービス用のDocker imageを指定するには、imageで事前にベースイメージ

と関連付けておきます。

詳細:


services:name

dockerコンテナを起動する時の拡張オプション

詳細な情報については、servicesに追加できる設定をみてください。


services:alias

dockerコンテナを起動する時の拡張オプション

詳細な情報については、servicesに追加できる設定をみてください。


services:entrypoint

dockerコンテナを起動する時の拡張オプション

詳細な情報については、servicesに追加できる設定をみてください。


services:command

dockerコンテナを起動する時の拡張オプション

詳細な情報については、servicesに追加できる設定をみてください。


before_script and after_script


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


before_script には、デプロイジョブを含む全てのジョブの起動前に実行されるコマンドを指定します。

しかし、実行されるのはartifactsが復元されたあとになります。

複数行の文字列か、配列での指定が可能です。

after_script には、失敗したジョブを含む全てのジョブの起動後に実行されるコマンドを指定します。

複数行の文字列か、配列での指定が可能です。

before_scriptで指定されるスクリプトは:


  • メインで指定されているscriptと結合して実行されます。scriptの定義と連結されると、
    ジョブレベルのbefore_scriptはグローバルレベルのbefore_scriptを上書きします。

  • 一つのシェルコンテキスト内でメインのscriptと同じように1つのものとして実行されます。

after_scriptで指定されるスクリプトは:


  • 現在のワーキングディレクトリをデフォルトに戻します。

  • シェル実行は、before_scriptscriptとは別の枠で実行されます。

  • 別の枠で実行されるので、before_scriptscriptで定義されたスクリプトの変更を
    以下のいずれかの場合、利用することができません:


    • シェル内。例えば、script のシェルの中でコマンドのエイリアスや変数を定義する

    • ワーキングツリーの外部(Runner実行環境に依存)。例えば、before_scriptscript
      で適用されたソフトウェアのインストール



ジョブ内にも before_scriptafter_script を定義でき、全体に定義しているものを個別に

上書きすることができます:

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


stages

stages は、ジョブで使うステージを定義するのに使います。全体レベルの設定となります。

stages には複数のパイプラインステージを定義します。stages に指定した要素の順番で

ジョブは順番に実行されます:


  1. 同じステージのジョブは、並列に実行されます。

  2. 前のステージのジョブが完全に実行に成功してから次のステージのジョブが実行されます。

次の例では、3つのステージが定義されています:

stages:

- build
- test
- deploy


  1. 最初にbuildの全てのジョブが並列に実行されます。


  2. buildのジョブが全て成功したら、testジョブが並列に実行されます。


  3. testのジョブが全て成功したら、deployジョブが並列に実行されます。


  4. deployのジョブが全て成功したら、このコミットはsuccessとマークされます。

  5. その前のジョブのいずれが失敗しても、コミットコマンドは、failedとマークされて、
    次のどのステージのジョブも実行されません。

注意しなければならない例外を2つ述べておきます:



  1. .gitlab-ci.ymlstages が定義されていない場合、buildtest
    deploy がデフォルトのジョブのステージです。

  2. ジョブが stage が定義されてない場合、ジョブは test ステージに割り当てられます。


stage

stageはジョブ毎に1つ定義し、全体レベルに定義されているstages に関連

しています。それぞれのステージ毎にジョブをグループにすることができ、同じstageのジョブは、

並列で実行されます。(certain conditions についても参照)

次のようになります:

stages:

- build
- test
- deploy

job 1:
stage: build
script: 依存したものをビルド

job 2:
stage: build
script: 成果物をビルド

job 3:
stage: test
script: テストを実施

job 4:
stage: deploy
script: デプロイを実施


自分指定のRunnerを使う

自分指定のRunnerを使う場合、デフォルトではGitLab Runnerを同時に1つだけ使うことができます。

(並列度についてのconcurrentフラグについては Runner global settingsを見てください)

自分指定のRunnerを使うときに並列になるのは以下の場合です:


  • 別々のRunnerで走らせた場合

  • Runnerのconcurrentで並列度が変更された場合。


only/except (基本)

onlyexcept の2つは、ジョブが開始されたときにそのジョブを実行するしないの実行条件を

設定するパラメーターです:



  1. onlyでは、ジョブを実行するブランチ名やタグ名を定義します。


  2. exceptでは、ジョブを 実行しない 時のブランチ名やタグ名を定義します。

ジョブの実行条件の使い方にはいくつか適用されるルールがあります:



  • onlyexceptは包含的に使えます。onlyexceptがジョブ内で両方定義
    されていた場合、onlyexceptの両方で絞り込めます。


  • onlyexceptには正規表現 (supported regexp syntax)が使えます。


  • onlyexceptフォークした場合のジョブを絞り込むのにリポジトリパスも指定できます。

onlyexceptに付加できる特殊なキーワードは以下の通りです。

キーワード
詳細

branches
パイプラインのgitリファレンスがブランチの時だけ実行

tags
パイプラインのgitリファレンスがタグの時だけ実行

api
パイプラインがトリガーAPIではなく、2番目のパイプラインAPIから呼び出された場合PI)

external
GitLab以外のCIサービスから呼び出されたときだけ実行

pipelines
複数プロジェクトのためのトリガーで、CI_JOB_TOKENを使ってAPIから呼び出された場合

pushes
パイプラインがユーザーからの git push で呼び出された場合

schedules

scheduled pipelines用.

triggers
パイプラインがトリガートークンを使って呼び出された場合

web
GitLab UIの Run pipeline ボタン(プロジェクトのパイプライン)を使ってパイプラインが呼び出された場合

merge_requests
マージリクエストが作成、更新されたとき (pipelines for merge requests参照)

chats

GitLab ChatOps コマンドでジョブが作成されたとき

以下の例では、jobは、issue-がリファレンスついている場合にのみ実行され、

ブランチでは全てスキップされます:

job:

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

デフォルトでは、大文字小文字を区別してマッチします。iフラグをつかって、

/pattern/iのようにすれば、大文字小文字の区別はありません:

job:

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

この例では、jobはタグのリファレンスがついている時にのみ実行され、また、

APIトリガーかPipeline Scheduleで呼び出された時にのみ実行されます:

job:

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

リポジトリパスも使うことができ、親リポジトリでのみ実行し、フォークされた

パスの場合には実行しません:

job:

only:
- branches@gitlab-org/gitlab-ce
except:
- master@gitlab-org/gitlab-ce
- release/.*@gitlab-org/gitlab-ce

この例では、masterブランチを除く、gitlab-org/gitlab-ceの全てのブランチでは、

jobを実行しますが、release/のプレフィックス名がついているものでは実行しません。

onlyを1つもない場合は、only: ['branches', 'tags']がデフォルトです。

exceptがない場合のデフォルトルールはありません。

以下のような例では、

job:

script: echo 'test'

以下と同じです:

job:

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


正規表現

@ は、リポジトリパスのリファレンスの先頭を意味する文字として利用されるので、

@を含むリファレンスにマッチする正規表現を書くためには、16進コードの\x40

を使って記述する必要があります。

タグ、または、ブランチの名前のみ正規表現でマッチさせることができます。

リポジトリのパスを指定している場合は、正規表現ではなく文字の通りにマッチします。

タグやブランチ名に正規表現をマッチさせる場合には、正規表現は、/で囲まれていて

パターンの正規表現でマッチさせたいタグやブランチ名全体を指定している必要があります。

(閉じ/の後に正規表現フラグがつきます)

その為、issue-/.*/ は全てのタグやブランチ名にはマッチせず、issue-で始まる

ものにしかマッチしません。

TIP: ヒント

正規表現でタグ名やブランチ名に部分一致するのを避けるためには、^$

使うのをおすすめします。

例えば、 /^issue-.*$/は、/^issue-/と同じです。

一方で、/issue/としてしまった場合は、severe-issuesブランチにもマッチしてしまいます。


only/except での正規表現サポート

CAUTION: 警告:

この破壊的変更は、GitLab 11.9.4で導入されました。

GitLab 11.9.4では、onlyexcept で内部的に使用される正規表現を

RE2に置き換え始めました。

つまり、Ruby Regexpで利用できる機能の全てが利用できるわけで

はなくなります。RE2は演算の負荷を下げるために限定した

機能しか提供していません。その為、GitLab 11.9.4では、いくつかの機能が使えなくなります。

例えば、否定先読みです。

GitLabのバージョン11.9.7から、12.0までは、安全ではない正規表現をユーザーが利用できるように管理者が

オンオフできるフラグを提供します。この機能は、新しい記述方法を後方互換のために用意し、ユーザーが

新しい記述方法に徐々に移行することができるようにします。

Feature.enable(:allow_unsafe_ruby_regexp)


only/except (アドバンスド)

CAUTION: 警告:

これは、アルファ版の機能です、予告なしにいつでも変更されることがあります!

シンプルな表現と複雑な表現の両方をGitLabではサポートしています。それにより、

配列とハッシュの両方のフォーマットを利用することができます。

以下の4つのキーが利用できます:


  • refs

  • variables

  • changes

  • kubernetes

onlyexceptの配下で上記それぞれの複数のキーをAND条件のように利用することができます:


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



only:refs/except:refs


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


refs では、simplified only/except configurationと同じような値を

設定できます。

以下の例では、deployジョブは、パイプラインがscheduledに定義されているか、または

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

その他の利用方法としては、コミットに特定のメッセージが入っている場合にジョブ実行を

避けるといったことができます。

end-to-end:

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

変数の評価について詳しく知りたい場合は、variables expressions を参照してください。


only:changes/except:changes


changes ポリシーは、GitLab 11.4 の introduced で導入されました。


changesonly もしくは except と合わせて使うと、git の push操作で変更された

ファイルの有無によってジョブを開始するかどうかを指定できます。

例:

docker build:

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

この例では、ブランチ内に複数のコミットがされている状況で、GitLabは、docker build を実行する

のですが、次のファイルが変更されるコミットがあるときにのみ、ジョブを実行するようになります:



  • Dockerfile ファイル


  • docker/scripts/ 内での変更


  • dockerfiles ディレクトリ内のサブディレクトリ内


  • more_scripts 配下の rbpysh の拡張子が付いているファイル

さらに、リポジトリ内のルートディレクトリから複数のファイルをパターンマッチすることもできます。もしくは、リポジトリ内の 全て についても可能です。

test:

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

NOTE: 注意:

上記の例では、globパターンだったので、パターンマッチ表現をダブルクオートでくくっています。もし、くくっていないglobパターンでは、

.gitlab-ci.ymlをパースするときにエラーが発生します。

下記の例だと、リポジトリのルート配下にある .md 拡張子のファイルのどれが変更されても、CI job は開始されません。

build:

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

CAUTION: 警告:

この機能を新しいブランチとタグで使用するときには注意点がいくつかあります。次のセクションを参照

してください。


新しいブランチやタグで changes を使う場合

GitLabへ 新しいブランチ新しいタグ をプッシュするときにも、ジョブを実行するかどうかを

GitLabでは評価します。しかし、この機能はマージリクエストには関連がありません。というのも、ユーザーが

マージリクエストを作る前にパイプラインは作成されてしまい、またこの時点ではターゲットとなるブランチも

不明だからです。


merge_requestschanges を使うには

マージリクエストでファイルの変更を検知してジョブを実行するかどうかを評価するように

定義するには、pipelines for 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 ジョブを起動します。


tags

tagsを指定すると、そのプロジェクトで利用できる全てのRunnerのなかから、そのタグを

つけられている特定のRunnerでジョブを実行させることができます。

RunnerにはGitLabに登録するときに、rubyとか postgresdevelopmentといった

タグを事前に付けておくことができます。

tagsにより特定のタグがついているRunnerに対してジョブを指定して実行することが

できるようになります:

job:

tags:
- ruby
- postgres

上記の指定では、rubypostgresタグの両方が設定されたRunnerでjobがビルドされます。

タグを指定するのは、異なったプラットフォームで違うジョブを実行するのに非常に適しています。

例えば、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 が設定されている場合、CI ツールの残り部分で影響を与えなければ、

そのジョブがエラーになっても終了しません。

ジョブがmanualでない限り、デフォルト値は、falseです。

これを有効にしていてジョブがエラーになったら、UI上でオレンジの警告メッセージが表示されます。

しかし、パイプラインの論理的なフロー上ではジョブは 成功/合格とされてブロックされることは

ありません。

それ以外のジョブが成功したとすると、そのジョブとパイプラインには同じオレンジ色のメッセージが

表示されます。ただし、関連するコミットは警告なしに"合格"とマークされます。

以下の例では、job1job2が並列に実行され、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 - 直前のステージで一つでもジョブが失敗したときにのみジョブを実行します。


  3. always - 直前のステージでジョブの状態がどうであるかにかかわらずジョブを実行します。


  4. manual - ジョブを手動で実行します(GitLab 8.10で追加されました)。以下のmanual actionsを参照してください。

例:

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. deploy_job を GitLab's UI から手動実行することができるようにします。


when:manual



  • GitLab 8.10. で導入されました

  • 手動操作の禁止は、GitLab 9.0 で導入されました。

  • 実行の保護は、GitLab 9.2 で導入されました


手動実行は自動的には実行されない特別なタイプのジョブです。

このアクションは、ユーザーが明示的に開始する必要があります。手動実行の使い方の

一つは、本番環境へのデプロイでしょう。パイプラインやジョブ、環境、デプロイ画面から

手動実行することができます。詳しくは、[environments documentation][env-manual]

を参照してください。

手動実行はオプションまたはブロックのどちらかを取ります。ブロッキングの場合は、

手動アクションはこれがで定義されている部分でパイプラインの実行をブロックします。

ブロックされている手動アクションは、誰かが play ボタンを押したらパイプラインの

実行が継続されます。

パイプラインがブロックされたら、パイプラインが成功したときにのみマージされると

していた場合、マージされません。ブロックされたパイプラインはステータスが manual

という特殊なものになります。デフォルトでは手動実行がブロックされることはありません。

手動実行で(失敗時に)ブロックしたい場合には、allow_failure: false.gitlab-ci.yml

のジョブ定義に追加してください。

手動実行のオプションは、デフォルトでallow_failure: trueとなっているので、全体の

パイプラインステータスには影響しません。手動実行が失敗した場合でも、パイプライン自体は

成功というステータスになります。

手動実行で書込み操作にあたるため、ユーザーがそのトリガーを実行したときには、

protected branchesのパーミッションが

必要になります。つまり、手動実行をパイプライン内で実行するためには、このブランチに

対するマージ権限を持っている必要があります。


when:delayed


GitLab 11.4の Introduced で導入されました。


遅延ジョブを使うとスクリプトが実行されて一定時間後に起動するジョブを作ることができます。

すぐにジョブが実行待ちステータスになってしまうのを避けたい場合に役に立ちます。

start_in キーで期間を設定します。start_in キーの値は指定しない場合は秒で経過時間を表します。start_inは1時間以内である必要があります。有効な値の例として次のようなものがあります:


  • 10 seconds

  • 30 minutes

  • 1 hour

ステージに遅延ジョブがあった場合、遅延ジョブが終了するまでパイプラインは進みません。

つまり、別々のステージ間で遅延を追加するのに使えると言うことです。

遅延ジョブのタイマーは、前のステージのジョブが完了した直後にスタートします。

他のタイプのジョブと同じで、直前のステージが終了しない限り、遅延ジョブのタイマーは開始しません。

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

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 に関してもっと詳しく知りたい、もしくはもっとサンプルが見たい場合は、documentation about environments を見てください。


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

簡単なものでは、environmentは次のように定義できます:

deploy to production:

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

上の例では、deploy to productionジョブにある、production環境への

デプロイを実行するものとして設定されています。


environment:name



  • GitLab 8.11 で導入されました。

  • GitLab 8.11 より以前は、environment: productionといった形式で環境名を指定できました。
    今の推奨は、nameキーワードの配下に定義してください。


  • nameパラメーターは、定義済みの任意のCI変数を何でも利用でき、
    定義済みの変数、.gitlab-ci.ymlの変数、シークレット変数などのvariables
    使用することができます。
    しかし、script配下の変数だけは利用できません。


environmentの名前には次のような文字を利用できます:


  • letters(アルファベット文字)

  • digits(数字)

  • spaces(空白)

  • -

  • _

  • /

  • $

  • {

  • }

一般的な名前はqastagingproductionですが、ワークフローで使用できる名前であれば何でも使用できます。

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's UI からのみURLを設定できました。
    今は、.gitlab-ci.ymlでの設定が推奨されています。


  • urlパラメーターは、定義済みの任意のCI変数を何でも利用でき、定義済みの変数、.gitlab-ci.ymlの変数、
    シークレット変数などのvariables を使用することができます。
    しかし、script配下の変数だけは利用できません。


これはオプションの値で、セット時にはGitLabの様々なところでボタンが表示され、

そのボタンを押すと、設定したURLに移動することができます。

次の例では、ジョブが成功したらマージリクエストボタンとhttps://prod.example.comのURLが

表示された、the environments/deploymentsページへのボタンが作成されます。

deploy to production:

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


environment:on_stop




  • Introduced GitLab 8.13 で導入されました。

  • GitLab 8.14から、environment にストップアクションが定義されている場合、
    関連したブランチが削除されるとGitLab が自動的に停止アクションを呼び出します。


環境を閉じる(停止する)には、environmenton_stopキーワードを使用します。

環境を閉じるために必要な別のジョブを定義することができます。

environment:actionのサンプルを見てください。


environment:action


Introduced GitLab 8.13 で導入されました。


actionのキーワードは、on_stopと組み合わせて使われ、環境を閉じるときに呼び出されるジョブとして定義されます。

例:

review_app:

stage: deploy
script: make deploy-app
environment:
name: review
on_stop: stop_review_app

stop_review_app:
stage: deploy
script: make delete-app
when: manual
environment:
name: review
action: stop

このサンプルでは、review_appのジョブでreview環境へデプロイし、on_stop

stop_review_appという新しいジョブを定義します。review_appジョブが一度

成功すると、stop_review_appジョブをwhenの条件で実行します。この場合、

実行するにはmanualに設定されているので GitLab のWebインターフェースから

手動実行 manual action で動かすことが必要です。

stop_review_appジョブには、次のキーワードを定義しておくのが必須です:



  • when - reference

  • environment:name

  • environment:action


  • stagereview_appと同じ場所にして、ブランチが削除されたときに自動的に
    停止する環境にする必要があります。


動的環境




  • Introduced GitLab 8.12 と GitLab Runner 1.6 で導入されました。

  • The $CI_ENVIRONMENT_SLUGintroduced GitLab 8.15 で導入されました。


  • nameurlパラメーターは、定義済みの任意の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 review app(レビュー用にデプロイ) ジョブでは、 review/$CI_COMMIT_REF_NAME

という名前の環境を動的に作成するという指定になっています。ここでは、$CI_COMMIT_REF_NAME

Runner が指定したenvironment variableです。

$CI_ENVIRONMENT_SLUG環境の名前を元にした変数ですが、URLの指定に最適です。

例えば、deploy as review appジョブがpowというブランチ名で実行された場合、

この環境はhttps://review-pow.example.com/のようなURLでアクセスできるようになります。

これは当然、アプリケーションが適切にホストする基盤となるサーバーで動いていることが前提です。

通常のケースでは、ブランチの動的環境を作成しReview Appとして使用するような場合です。

シンプルな例ですが、https://gitlab.com/gitlab-examples/review-apps-nginx/

Review Appsを見られます。


cache



  • GitLab Runner v0.7.0 で導入されました。


  • cache は、パイプライン全体に設定され、ジョブ毎に適用されます。

  • GitLab 9.0 から、キャッシュはデフォルトでパイプラインのジョブ間で共有されるのが
    デフォルトになりました。

  • GitLab 9.2 から、キャッシュは成果物がリストアされる前にリストアされます。


TIP: 詳細に知りたい場合:

キャッシュの動作について知りたい場合、オススメの設定方法を知りたい場合は、

caching dependencies documentationを見てください。

cacheは、ジョブ間で共有されるべきファイルとディレクトリをキャッシュするために利用されます。

プロジェクトワークスペース内のパスのみ利用することができます。

cacheがジョブのスコープ外で定義されていた場合、全てのジョブでその定義を利用する

グローバル設定となります。


cache:paths

pathsディレクティブを使用して、どのファイルまたはディレクトリをキャッシュするかを

選択します。ワイルドカードも使用できます。

以下の設定では、.apkで終わるbinaries配下の全てのファイルと.configのファイルがキャッシュされます:

rspec:

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

ローカルに定義したキャッシュオプションで、グローバルオプションを上書きします。

次の例では、rspecジョブでキャッシュされるのは、binaries/のみです:

cache:

paths:
- my/files

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

キャッシュはジョブ間で共有されるため、ジョブ毎に違うパスを使っている場合、それぞれに

cache:keyを設定して、それぞれ別の設定にする必要があります。そうしない場合は、

キャッシュが上書される可能性があります。


cache:key


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


キャッシュは、ジョブ間で共有されるため、異なるジョブに対して違うパスを設定している

場合、それぞれのcache:keyを設定する必要があります。そうしないと、キャッシュの

内容が上書きされる可能性があります。

keyを指定すると、ジョブ間のキャッシュはジョブ間でキャッシュの類似性を定義する

ことができ、全てのジョブで1つのキャッシュを定義するか、ジョブ毎で定義するか、

ブランチ毎でキャッシュする、または、ワークフローにマッチしたあなたの適切だと思う

方法で指定することができます。

cache:keyの変数には、 predefined variablesのどれでも

利用でき、設定されていない場合は、GitLab 9.0からdefaultが設定され、それによりデフォルト

では、全てのジョブとパイプライン間で全てのものが共有されます。

NOTE: 注意:

cache:key の変数には / 文字または、URIエンコードされた同等の %2F を使うことが

できません;同様に (., %2E) のみの値も利用できません。

例えば、ブランチ毎にキャッシュを有効にする場合は以下のようになります:

cache:

key: "$CI_COMMIT_REF_SLUG"
paths:
- binaries/

Windows Batch を利用する場合、シェルスクリプトの$%に変換する必要があります:

cache:

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


cache:untracked

untracked: trueをセットすると、Gitリポジトリ追跡対象外になっているファイルを

全てキャッシュします:

rspec:

script: test
cache:
untracked: true

binaries配下でGitリポジトリ追跡対象外のファイルを全てキャッシュする:

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



  • GitLab Runner v0.7.0 からWindowsプラットフォーム以外で導入。

  • GitLab Runner v.1.0.0 からWindowsをサポートしました。

  • GitLab 9.2 から、キャッシュはアーティファクトの生成の前に戻ります。

  • 今の全てのRunnerでサポートしている訳ではありません。

  • artifacts ジョブは、デフォルトで正常なジョブに対してのみ収集されます。


artifacts というのは、ジョブが成功、失敗、常時の状態で終了した後に

成果物やディレクトリをその後のジョブ上で利用する為に使います。

成果物は生成され、ジョブが成功した後にGitLabに送信され、GitLab UIからダウンロードできます。

成果物の詳細.


artifacts:paths

プロジェクトのワークスペース内のパスを指定することができます。全く違うジョブで生成ファイルを

やりとりする場合は、dependenciesを見てください。

binaries.configの全てのファイルを送信する場合:

artifacts:

paths:
- binaries/
- .config

成果物の送信をしない場合は、空の dependencies を定義してください:

job:

stage: build
script: make build
dependencies: []

一時的につくられた成果物の影響でビルドサーバーのDiskが一杯にならないように、タグがつけられたリリースでのみ、ファイルを生成したいと考えるかもしれません。

tags でのみ 成果物を生成(default-jobでは成果物を生成しません):

default-job:

script:
- mvn test -U
except:
- tags

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


artifacts:name


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


name は、成果物のアーカイブ名を指定するディレクティブです。その為、一意の名前を

設定するようにしておくとGitLabからアーカイブをダウンロードするときに便利です。

artifacts:name に取り得る変数は、predefined variables のどれでも利用できます。

artifacts は、ダウンロード時にデフォルトでは artifacts.zipになります。

NOTE: 注意:

ブランチ名にスラッシュが入っている場合(例 feature/my-feature)、正しくファイル名を

取り扱えるようにするために、$CI_COMMIT_REF_NAMEではなく$CI_COMMIT_REF_SLUG

使うことをお勧めします。

現在のジョブの名前を アーカイブ名として作成:

job:

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

binariesディレクトリに含まれたファイルを今のブランチやタグ名をアーカイブ名として作成:

job:

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

binariesディレクトリに含まれたファイルを今のジョブ名とブランチやタグ名をアーカイブ名として作成:

job:

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

現在のstageの名前とブランチ名でアーカイブを作成:

job:

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

Windows Batch を利用する場合、 シェルスクリプトの$%に変換する必要があります:

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を利用すると、すべてのGit未追跡ファイルを(artifacts:paths

定義されたパスに沿って)成果物として追加することができます。

NOTE: 注意:

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

Gitの未追跡ファイルを全て送信:

artifacts:

untracked: true

binariesディレクトリ内のファイルで、Gitで追跡されていないファイルだけ送信:

artifacts:

untracked: true
paths:
- binaries/


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にアップロードされ保存し始めてから、

削除されるまでにどれぐらいの期間、成果物を保存しておくか有効期限を指定することができます。

その期間を過ぎたら削除されます。有効期限が設定されていない場合は、デフォルトでは

instance wide settingで設定されます。

(通常は、30 日、GitLab.comでは削除されません)

ジョブのページで Keep ボタンを押すと、期限を変更して成果物をずっと残しておくことができます。

期限が切れた後、実際には成果物は毎時(Cron ジョブで)自動的に削除されますが、

有効期限が過ぎたらアクセスすることはできません。

expire_inの値は経過時間で示します。以下は利用可能な記載例です:


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


artifacts:reports


GitLab 11.2のIntroduced

導入されました。GitLab Runner 11.2以上が必要です。


reports設定キーワードは、ジョブからテストレポートを収集し、GitLabのUI

(マージリクエストやパイプラインビュー)から見られるようにするために利用します。

JUnit reportsと一緒に使う方法を読んで下さい。

NOTE: 注意:

テストレポートはジョブの実行結果(成功や失敗)にかかわらず収集されます。

artifacts:expire_inでこれらの成果物の有効期限を設定できます。

NOTE: 注意:

出力されたレポートファイルも参照する場合には、artifacts:paths

設定キーワードも含めて下さい。


artifacts:reports:junit


GitLab 11.2のIntroduced

導入されました。GitLab Runner 11.2以上が必要です。


junitレポートは、成果物としてJUnit XML filesを収集します。JUnitは、元々Javaで開発されていたものですが、JavaScriptやPython、Ruby等の

その他の言語についてもthird party ports

多数移植されています。

より詳細な内容やサンプルについては、JUnit test reports

参照できます。

以下は、Ruby's RSpecテストツールで生成されたJUnit XMLファイルを収集する例です:

rspec:

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

収集されたJUnitレポートは、成果物としてGitLabにアップロードされ、

マージリクエスト内に自動的に表示されます。

NOTE: 注意:

JUnitテストツールを使うと複数のXMLファイルが出力される場合は、一つのジョブ内で

複数のテストレポートファイルを指定することができますが、それらは自動的に1つの

ファイルに結合されてしまいます。

ファイル名のパターン(junit: rspec-*.xml)を使うか、ファイル名を配列リストとして

(junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml])と列挙するか、

配列とパターンを組み合わせて(junit: [rspec.xml, test-results/TEST-*.xml])

として下さい。


artifacts:reports:codequality [STARTER]


GitLab 11.5で導入されました。GitLab Runner 11.5以上が必要です。


codequalityレポートは、成果物としてCodeQuality issuesを収集します。

収集されたCode Qualityレポートは、成果物としてGitLabにアップロードされ、

マージリクエスト内に自動的に表示されます。


artifacts:reports:sast [ULTIMATE]


GitLab 11.5で導入されました。GitLab Runner 11.5以上が必要です。


sastレポートは、成果物としてSAST vulnerabilitiesを収集します。

収集されたSASTレポートは、成果物としてGitLabにアップロードされ、

マージリクエストとパイプラインビュー内に自動的に表示され、セキュリティーダッシュボードに

データを提供します。


artifacts:reports:dependency_scanning [ULTIMATE]


GitLab 11.5で導入されました。GitLab Runner 11.5以上が必要です。


dependency_scanningレポートは、成果物としてDependency Scanning vulnerabilitiesを収集します。

収集されたDependency Scanningレポートは、成果物としてGitLabにアップロードされ、

マージリクエストとパイプラインビュー内に自動的に表示され、セキュリティーダッシュボードに

データを提供します。


artifacts:reports:container_scanning [ULTIMATE]


GitLab 11.5で導入されました。GitLab Runner 11.5以上が必要です。


container_scanningレポートは、成果物としてContainer Scanning vulnerabilitiesを収集します。

収集されたContainer Scanningレポートは、成果物としてGitLabにアップロードされ、

マージリクエストとパイプラインビュー内に自動的に表示され、セキュリティーダッシュボードに

データを提供します。


artifacts:reports:dast [ULTIMATE]


GitLab 11.5で導入されました。GitLab Runner 11.5以上が必要です。


dastレポートは、成果物としてDAST vulnerabilitiesを収集します。

収集されたDASTレポートは、成果物としてGitLabにアップロードされ、

マージリクエストとパイプラインビュー内に自動的に表示され、セキュリティーダッシュボードに

データを提供します。


artifacts:reports:license_management [ULTIMATE]


GitLab 11.5で導入されました。GitLab Runner 11.5以上が必要です。


license_managementレポートは、成果物としてLicensesを収集します。

収集されたLicense Management レポートは、成果物としてGitLabにアップロードされ、

マージリクエストとパイプラインビュー内に自動的に表示され、セキュリティーダッシュボードに

データを提供します。


artifacts:reports:performance [PREMIUM]


GitLab 11.5で導入されました。GitLab Runner 11.5以上が必要です。


performanceレポートは、成果物としてPerformance metricsを収集します。

収集されたPerformanceレポートは、成果物としてGitLabにアップロードされ、

マージリクエストとパイプラインビュー内に自動的に表示され、セキュリティーダッシュボードに

データを提供します。


artifacts:reports:metrics [PREMIUM]


GitLab 11.10で導入されました。


metricsレポートは、成果物としてMetricsを収集します。

収集されたMetricsレポートは、成果物としてGitLabにアップロードされ、

マージリクエスト内に自動的に表示されます。


dependencies


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


この機能は、 artifactsと組み合わせて使い、別のジョブで使うために

受け渡しする成果物を定義することができます。

デフォルトではその前の全てのステージのartifactsが転送されるのに注意してください。

この機能を使うには、ジョブの中でdependenciesを定義して、その一つ前のジョブ内では

どの成果物をダウンロードするべきかのリストを定義します。

現在のステージの一つ前で実行されたステージからのみジョブを定義できます。

現在のステージまたは次のステージからジョブに定義すると、エラーになります。

ジョブ上で空の配列を定義すると、成果物を何もダウンロードしません。

dependenciesを使うと直前のジョブの状態が考慮されないので、

ジョブが失敗したり、手動ジョブが実行されなかった場合にエラーは発生しません。


次の例では、build:osxbuild:linuxの2つのジョブで成果物を定義されています。

test:osxが実行されるときにbuild:osxのビルドされた成果物をダウンロードされ、

展開されます。test:linuxでも同様で、build:linuxから成果物がダウンロードされます。

deployのジョブでは、stage の優先度により、その前の全てのジョブの成果物が

ダウンロードされます:

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


ジョブの成果物にdependencyが設定されていて、それがexpired

erasedされて

いる場合、依存しているジョブは失敗します。

NOTE: 注意:

旧来の挙動に戻す場合、管理者に

flip this switch

を依頼してください。


coverage


Introduced GitLab 8.17 で導入されました。


coverageを使ってジョブ結果出力からコードに対してどれぐらいのカバレッジがあるか取得

することができます。

ここで指定できるのは正規表現のみです。そのために正規表現の文字列であると明示的に

表現するために、 /で括る必要があります。特殊文字を文字としてマッチしたい場合は、

エスケープする必要があります。

簡単な例:

job1:

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


retry


Introduced GitLab 9.5で導入されました

Behaviour expanded

によりGitLab 11.5からどのフェイルで再試行するかどうか制御できるようになりました。


retryは、フェイル時にジョブを何回再試行するかを決めるものです。

retryが設定されている場合、ジョブが失敗するとretryキーワードで指定した

回数だけ再度実行します。

retryが2回に設定されていた状態で、ジョブが2回目(1回目の再試行)で成功でしたときには、

それ以上の再試行はされません。retry回数は正の整数で0よりも大きい必要がありますが、

2かそれ以下の値である必要があります(2の場合は全部で最大3回の試行になります)

全ての失敗の場合に再試行する簡単な例:

test:

script: rspec
retry: 2

デフォルトでは、全ての失敗のケースでジョブの再試行します。どのような失敗の場合には

どのような再試行をするのが適しているか、retryで次のハッシュを使って設定します:



  • max: 再試行の最大回数.


  • when: 再試行する失敗のケース.

Runnerのシステムフェイルの場合に最大2回再試行する:

test:

script: rspec
retry:
max: 2
when: runner_system_failure

Runnerのシステムフェイル以外で、上記のその他のフェイルがあった場合、ジョブは

再試行されません:

複数の失敗のケースで再試行する場合、whenに失敗のリストを適用することができます:

test:

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

whenで利用できる値は以下の通りです:



  • always: どの失敗でも再試行(デフォルト)


  • unknown_failure: 失敗の理由が不明な場合に再試行


  • script_failure: スクリプトの実行に失敗した場合に再試行


  • api_failure: APIフェイルの場合に再試行


  • stuck_or_timeout_failure: スタック、またはタイムアウトの時に再試行


  • runner_system_failure: Runnerシステムの失敗の時に再試行 (例:セットアップジョブが失敗)


  • missing_dependency_failure: 依存関係が失われている時に再試行


  • runner_unsupported: Runnerがサポート外の時に再試行


parallel


GitLab 11.5のIntroducedで導入されました。


parallelでジョブを並列に動かすインスタンス数を設定します。2以上50以下をこの値に設定します。

並列にジョブを動かす為にN個のインスタンスが起動されます。

順にjob_name 1/Nからjob_name N/Nまでの名前が付きます。

全てのジョブに対して、CI_NODE_INDEXCI_NODE_TOTAL environment variablesが設定されます。

簡単な例:

test:

script: rspec
parallel: 5


trigger [PREMIUM]


GitLab Premium 11.8のIntroducedで導入されました。


triggerは、下流のパイプラインを起動するトリガーを定義します。

trigger定義によりジョブが起動されたジョブがGitLabにより開始されると、

下流のパイプラインが作成されます。

マルチプロジェクトパイプラインについては、multi-project pipelinesを参照して下さい。


簡単な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


include




  • GitLab Premium 10.5で導入されました。

  • 10.6からStarter、Premium、Ultimateで利用できるようになりました。

  • GitLab 11.4からCoreに移行しました。


外部のYAMLファイルをinclude設定キーワードを使うと取り込むことができます。

includeで読み込む外部のYAMLは、.yml.yamlである必要があり、

その他のファイルは読み込まれません。

includeで定義できるファイルは以下の通りになります:



  • .gitlab-ci.ymlに書かれているファイルはネストしてマージします。


  • .gitlab-ci.ymlの内容は、includeの書かれている場所にかかわらず、
    最初に評価され、マージされます。

TIP: ヒント:

ローカルの定義がされているCI/CD設定についても対象としてカスタマイズを

マージしたり、上書きするのに使います。

NOTE: 注意:

includeで読み込まれた複数のYAMLファイルにまたがったYAMLエイリアスを使う

方法はサポートされていません。参照できるのは同じファイルのエイリアスで

ある必要があります。YAMLのアンカーを使う代わりに extends keywordを使えます。

includeで対応しているincloudeのメソッド:

usage examplesを参照。

NOTE: 注意:

どのメソッドであろうともそれらを含んだ.gitlab-ci.yml設定は、パイプライン作成時に

評価されます。その時のスナップショットとしてデータベースに設定は保存されます。

.gitlab-ci.ymlを参照した設定を変更しても、次のパイプラインが実行されるまでGitLabには反映されません。


include:local

.gitlab-ci.ymlと同じリポジトリにあるファイルをinclude:localで読み込みます。

ファイルはルートディレクトリ(/)からの相対パスを使って参照します。

設定ファイルがあるのと同じブランチでGitによって現在追跡されているファイルのみを使用できます。

言い換えれば、 include:localを使うとき、同じブランチに.gitlab-ci.ymlとローカル

ファイルの両方があるようにしてください。

ネストしたnested includesは全て、同じプロジェクトの範囲で起動するので、

ローカル、プロジェクト、リモート、またはテンプレートのインクルードを利用できます。

NOTE: 注意:

Gitサブモジュールのパス使ってローカルファイルを読み込む機能はサポートされていません。

例:

include:

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


include:file


in GitLab 11.7のIntroducedで導入されました。


同じ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'

ネストしたnested includesは全て、目的のプロジェクトの範囲で起動するので、

ローカル(目的のプロジェクトに対して)、プロジェクト、リモート、またはテンプレートのインクルード

を利用できます。


include:template


in GitLab 11.7のIntroducedで導入されました。


.gitlab-ci.ymlのテンプレートshipped with GitLabinclude:templateで読み込むことができます。

例:

# File sourced from GitLab's template collection

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

ネストしたnested includesは全て、ユーザーの権限で起動するので、

プロジェクト、リモート、またはテンプレートのインクルードで利用できます。


include:remote

HTTP/HTTPSを使って別の場所のファイルをフルパスのURLでinclude:remoteを使って

読み込みます。リモートファイルは、GETリクエストで単純に外部からアクセスできるもので

ある必要があります。 認証付きのリモートURLはサポートしていません。例:

include:

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

ネストしたファイルは、パブリックユーザーとして経緯なしで実行されるので、その他のリモート、

パブリックプロジェクト、テンプレートのみ利用できます。


ネストしたincludes


GitLab 11.9でIntroducedが導入されました。


ネストのインクルードを使用することにより、includeのセットを作れます。

includeを全部で50回まで利用できます。

インクルードが重複していると構成エラーになります。


includeの例

includeの例をもういくつか紹介します。


1行での記述と複数行の配列での記述

外部YAMLファイルの読み込みは、1行で記述する方法と複数行の配列形式

で記述する方法があります。次の例は全て有効です。

1行でinclude:localを記述:

include: '/templates/.after-script-template.yml'

複数行でincludeメソッドを記述:

include:

- 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
- '/templates/.after-script-template.yml'

includeにオプションを明示して1行で記述:

include:

remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'

include:remoteを配列にして1つ設定を記述:

include:

- remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'

includeにオプションを明示して複数の配列で記述:

include:

- remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
- local: '/templates/.after-script-template.yml'
- template: Auto-DevOps.gitlab-ci.yml

配列を使って混ぜた記述:

include:

- 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
- '/templates/.after-script-template.yml'
- template: Auto-DevOps.gitlab-ci.yml
- project: 'my-group/my-project'
ref: master
file: '/templates/.gitlab-ci-template.yml'


before_scriptをテンプレートにして再利用する

次の例では、.before-script-template.ymlの内容を自動的に取得し、.gitlab-ci.yml

と一緒に評価する方法です。

https://gitlab.com/awesome-project/raw/master/.before-script-template.ymlの内容は次の通りです:

before_script:

- apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
- gem install bundler --no-document
- bundle install --jobs $(nproc) "${FLAGS[@]}"

そして、.gitlab-ci.ymlの内容は次のようになっています:

include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'

rspec:
script:
- bundle exec rspec


外部のテンプレートの値を上書きする

次の例では、YAMLで定義された特定の値に注目して、productionのジョブの詳細を

別のファイルから読み込みつつ、.gitlab-ci.ymlでカスタマイズする方法です。

https://company.com/autodevops-template.ymlの内容は次の通りです:

variables:

POSTGRES_USER: user
POSTGRES_PASSWORD: testing_password
POSTGRES_DB: $CI_ENVIRONMENT_SLUG

production:
stage: production
script:
- install_dependencies
- deploy
environment:
name: production
url: https://$CI_PROJECT_PATH_SLUG.$KUBE_INGRESS_BASE_DOMAIN
only:
- master

そして、.gitlab-ci.ymlの内容は次のようになっています:

include: 'https://company.com/autodevops-template.yml'

image: alpine:latest

variables:
POSTGRES_USER: root
POSTGRES_PASSWORD: secure_password

stages:
- build
- test
- production

production:
environment:
url: https://domain.com

このようにPOSTGRES_USERPOSTGRES_PASSWORD変数は、.gitlab-ci.yml内の

URLで掲示されたautodevops-template.ymlで読み込まれていますが、それらは

さらに.gitlab-ci.ymlの新しい値で上書きされています。

読み込んでマージされることにより辞書型のマッピングを上書きしたり、

拡張したりできますが、配列のアイテムを読み込んで追加したりすることは

できません。例えば、productionのスクリプトにアイテムを追加する場合、

現在あるスクリプトのアイテムをもう一度記述する必要があります:

https://company.com/autodevops-template.ymlの内容は次の通りです:

production:

stage: production
script:
- install_dependencies
- deploy

そして、.gitlab-ci.ymlの内容は次のようになっています:

include: 'https://company.com/autodevops-template.yml'

stages:
- production

production:
script:
- install_dependencies
- deploy
- notify_owner

このケースでは、.gitlab-ci.ymlinstall_dependenciesdeploy

改めて記述されていない場合、結合されたproductionジョブのscriptの

配列の内容には入ってきません。


includeをネストして使う

次に複数のソースをincludeして複数のネストの方法を組み合わせた

使い方の例を紹介します。

この例では、まず.gitlab-ci.ymlがローカルの/.gitlab-ci/another-config.ymlを読み込みます:

include:

- local: /.gitlab-ci/another-config.yml

その/.gitlab-ci/another-config.ymlでは、そのほかのプロジェクトから/templates/docker-workflow.yamlを読み込みます:

include:

- template: Bash.gitlab-ci.yml
- project: group/my-project
file: /templates/docker-workflow.yml

その/templates/docker-workflow.ymlgroup/my-projectにあって、group/my-project

さらに2つのファイルを読み込みます:

include:

- local: /templates/docker-build.yml
- local: /templates/docker-testing.yml

このgroup/my-projectにある/templates/docker-build.ymlでは、docker-buildジョブを追加します:

docker-build:

script: docker build -t my-image .

group/my-projectにある2つ目の/templates/docker-test.ymlではdocker-testジョブを追加します:

docker-test:

script: docker run my-image /run/tests.sh


extends


GitLab 11.3で導入されました


継承するジョブをextendsにジョブ名を与えることで定義できます。

こちらの方が読みやすくて柔軟性があるYAML anchorsの別の書き方になります:

.tests:

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

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

上の例では、rspecジョブを.testsのテンプレートジョブから継承しています。

GitLabはキーを起点にさかのぼって読み込んで実行します。GitLabは次のことを行います:



  • rspecの内容を再帰的に読み込んでマージします。

  • キーの値はマージしません。

rspecのマージ結果は、以下のようになります:

rspec:

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

NOTE: 注意:

script: rake testscript: rake rspecで上書きされているということにご注意ください。

もし、rake testを含みたい場合は、

before_script and after_scriptを見て下さい。

この例の.testは、hidden keyですが、通常のジョブでも

同じように継承することができます。

マルチレベル継承をextendsではサポートしています。しかし、3レベル以上の継承は

おすすめしません。最大10のレベル(段階)のネストをサポートしています。

以下の例では継承を2レベル(段階)で行っています:

.tests:

only:
- pushes

.rspec:
extends: .tests
script: rake rspec

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

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

spinach:
extends: .tests
script: rake spinach

また、複数の親を利用したextendsも可能です。

"直近のスコープが勝つ"というマージアルゴリズムを使っています。

最後のメンバーのキーが常に他のレベルで定義されているものを上書きします。

例:

.only-important:

only:
- master
- stable
tags:
- production

.in-docker:
tags:
- docker
image: alpine

rspec:
extends:
- .only-important
- .in-docker
script:
- rake rspec

上記のrspecのジョブの結果は以下の通りです:

rspec:

only:
- master
- stable
tags:
- docker
image: alpine
script:
- rake rspec


extendsincludeを一緒に使う

includeと一緒にextendsを混ぜた設定ファイルを使って動かすことができます。

例えば、以下のようなincluded.ymlファイルがローカルにあるとします:

.template:

script:
- echo Hello!

そして、.gitlab-ci.yml内では、以下のように使えます:

include: included.yml

useTemplate:
image: alpine
extends: .template

手元のジョブでは、useTemplateジョブが呼び出されると、.templateで定義された

echo Hello!が実行され、alpineのDockerイメージが利用されます。


pages

pagesは、GitLabに静的コンテンツをアップロードしてウェブページを提供するための

特殊なジョブです。特殊な文法を持ち、以下の2つの要件を満たす必要があります:


  • すべての静的コンテンツは、public/ディレクトリーの配下に設置する必要があります。


  • artifactsのパスは、public/ディレクトリ配下に設定する必要があります。

以下の例では、プロジェクトのルートのファイルをすべてpublic/ディレクトリに移動します。

.public は、cppublic/ 自身をコピーして無限ループに陥るのを回避しています。

pages:

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

詳しくは、GitLab Pages user documentationを参照して下さい。


variables


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


NOTE: 注意:

整数 (同じように文字列も) は、変数名前と値のどちらにも利用できます。浮動小数点数は使うことができません。

GitLab CI/CDでは.gitlab-ci.ymlに変数を定義して、ジョブ環境にその変数を渡すことができます。

この変数は環境全体にもジョブ毎にも定義することができます。

ジョブレベルで定義したvariablesは、グローバルレベルで定義したYAMLの変数や定義済の変数を

上書きします。

これらは、Gitリポジトリに保存されますので、あまり機密性をもとめられないプロジェクトでの設定を

格納するためのものです。たとえば次のようになります。

variables:

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

これらの変数は、これ以降の実行される全てのコマンドやスクリプトで利用できます。

YAML で定義された変数は、同じように作成されたすべてのサービスコンテナにも適用できるため、

微調整用として利用できます。

変数は、job level単位でも定義することができます。

ユーザが定義する変数以外にも、Runner自身が設定する変数もあります。

set up by the Runner itself

一つの例としては、CI_COMMIT_REF_NAME というプロジェクトでビルドするブランチ名やタグ名です。.gitlab-ci.ymlで設定できる変数の他に、GitLabのUIで設定できるいわゆる秘密の変数もあります。

より詳細には、variables and their priorityを見てください。


Git strategy


GitLab 8.9 で実験的機能として導入されました。将来のバージョンで変更削除される

可能性があります。GIT_STRATEGY=none を指定するためには、 GitLab Runner v1.7以上が

必要です。


GIT_STRATEGYにより最新のソースコードを取得する時の挙動を指定することができます。

variablesセクションで全体設定もしくは、ジョブ毎に設定できます。

未指定の場合、プロジェクト設定のデフォルトが利用されます。

clonefetchnoneの3種類の挙動を指定できます。

cloneは一番遅くなるオプションです。ジョブ実行毎にリポジトリを一からクローンします。

プロジェクトのワークスペースが常に最新になることを保証します。

variables:

GIT_STRATEGY: clone

fetchの場合は、プロジェクトのワークスペースを再利用するので(存在しない場合はclone

実行します)、一番早くなります。一番最後のジョブが加えた変更をgit cleanでリセットして、

git fetchで最後のジョブが実行した後にコミットされている変更を取得します。

variables:

GIT_STRATEGY: fetch

noneも同様にプロジェクトのワークスペースを再利用しますが、Git の操作を全て(GitLab

Runnerのプレクローンスクリプトがあったとしても)スキップします。成果物に対してのみ動作

するジョブ(例えばdeploy)に最適です。Gitリポジトリーはあると思いますが、none

場合は、古くなっているはずなので、プロジェクトのキャッシュや成果物のファイルのみを

利用するようにしてください。

variables:

GIT_STRATEGY: none

NOTE: 注意: GIT_STRATEGYは、

Kubernetes executor

ではサポートされていませんが、近い将来サポートされるかもしれません。

進捗については、support Git strategy with Kubernetes executor feature proposalを見て下さい。


Git submodule strategy


GitLab Runner v1.10以上が必要


GIT_SUBMODULE_STRATEGY変数は、 ビルド前にソースコードを取ってくるときの

Git submodulesでの取得方法や取得の有無を制御する為のものです。

variablesセクションで全体設定もしくは、ジョブ毎に設定できます。

次の3つの値をとることができます:nonenormalrecursive:



  • noneを指定すると、プロジェクトのソースコード内の サブモジュールは含みません。

  • pre-v.10までの挙動と同じで、デフォルトです。



  • normalを指定すると、トップレベルのサブモジュールのみを含みます。以下の操作と同じです:

    git submodule sync
    
    git submodule update --init


  • recursiveにすると、submodule の全て(Submodule の Submodule)を含みます。


  • 以下の操作と同じです。この機能は、Git v1.8.1以降のバージョンが必要です。



  • DockerベースではないGitLab Runnerを実行者にしている場合は、この機能に必要な

    Git のバージョンになっているかどうか確認してください。

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


この機能を正しく動かす為の注意点は、submodulesで以下の設定を

(.gitmodules)内にどちらかをで正しく設定しておくことにあります:


  • 公開アクセスができるリポジトリ内のHTTP(S)のURLパス または、

  • 同じGitLabサーバーの他のリポジトリ関連パス

詳しくは、Git submodulesのドキュメントを確認してください。


Git checkout


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


GIT_CHECKOUT変数設定は、GIT_STRATEGYclonefetchに指定していて、

git checkoutを実施するかどうかを指定します。指定しない場合は、trueです。

variablesセクションで全体設定もしくは、ジョブ毎に設定できます。

falseに設定されていると、Runnerは以下のように動作します:



  • fetchの場合 - リポジトリーをアップデートして、ワーキングコピーを現在の
    リビジョンのままにします。


  • cloneの場合 - リポジトリーをクローンして、ワーキングコピーをデフォルトの
    ブランチのままにします。

trueに設定されていると、clonefetchでのストラテジーはどちらも、Runnerが

CIパイプラインに関連したリビジョンをワーキングコピーとしてチェックアウトするように

なります:

variables:

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


Git clean flags


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


GIT_CLEAN_FLAGS変数設定はソースコードをチェックアウトした後にgit cleanする

デフォルトの挙動を制御します。

variablesセクションで全体設定もしくは、ジョブ毎に設定できます。

GIT_CLEAN_FLAGSとしては、git clean

コマンドで利用できるオプションを全て受け付けられます。

GIT_CHECKOUT: "false"が指定されている場合は、git cleanは無効です。

GIT_CLEAN_FLAGSが以下の場合:


  • 未指定の場合、git cleanオプションはデフォルトの-ffdxになります。


  • noneの場合、git cleanは実行されません。

例:

variables:

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


Job stages attempts


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


実行ジョブが各ステージを実行しようとする試行の回数を次のように設定できます:

変数名
詳細

GET_SOURCES_ATTEMPTS
実行しているジョブでソースコードを取得する試行回数

ARTIFACT_DOWNLOAD_ATTEMPTS
実行しているジョブで成果物をダウンロードする試行回数

RESTORE_CACHE_ATTEMPTS
実行しているジョブでキャッシュのリストア試行回数

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

例:

variables:

GET_SOURCES_ATTEMPTS: 3

variablesセクションで全体設定もしくは、ジョブ毎に設定できます。


Shallow cloning


GitLab 8.9 で実験的機能として導入されました。将来のバージョンで完全に変更削除される可能性があります。


GIT_DEPTH を指定すると、Git の fetch と Clone の深さを指定することができます。

これを使うとリポジトリの深さを浅くクローニングができます。そうすることで多数のコミットや

古い、大きなバイナリを持つリポジトリのクローニングを大幅にスピードアップできます。

この値は、git fetchgit clone のコマンドにそのまま渡されます。

NOTE: 注意:

深さが1でジョブがキューに入ったり、リトライが発生すると、ジョブが

失敗する可能性があります。

Gitのfetchやcloneはブランチ名などのrefをベースに行うので、Runner は特定のコミットSHAを

指定してcloneすることはできません。キュー内に複数のジョブがある場合や古いジョブが再試行

した場合、テストが必要な対象のコミットが複製されたGitのヒストリー内にある必要があります。

GIT_DEPTHで値を小さすぎると、これらの古いコミットを実行することができなくなります。

この場合、ジョブのログにunresolved referenceと表示されます。その場合は、GIT_DEPTH

より高い値に変更し直すべきです。

GIT_DEPTH を設定すると Gitのヒストリーの一部だけ存在するため、git describe を使った

ジョブが正しく動かない可能性があります。

最新のコミットを3つのみfetchまたはcloneする:

variables:

GIT_DEPTH: "3"

variablesセクションで全体設定もしくは、ジョブ毎に設定できます。


非推奨パラメーター

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


types

CAUTION: 非推奨:

types は非推奨です。将来のバージョンで削除される可能性があります。

代わりにstagesを使って下さい。


type

CAUTION: 非推奨:

type は非推奨です。将来のバージョンで削除される可能性があります。

代わりにstageを使って下さい。


Custom build directories


Introduced Gitlab Runner 11.10で導入されました


NOTE: 注意:

この設定は、custom_build_dirRunner's configuration

設定で有効になっている場合にのみ利用することができます。

dockerkubernetesの実行環境ではデフォルトの設定です。

デフォルトでは、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.builds_dirの設定に依存します。


並列度の取り扱い

並列度を1以上に設定した実行環境では、同じディレクトリで複数のジョブが操作をするため、

もし、builds_dirがジョブ間で共有されていると、失敗を引き起こします。

GitLab Runnerはこのような状況を防ごうとはしません。そのようなRunnerの設定の要件に

合わせるかどうかは、管理者または開発者に任せられています。

このような状況をさけるために、$CI_BUILDS_DIRのパス内にRunnerが提供している2つの

一意な並列度のIDを追加して利用することができます。



  • $CI_CONCURRENT_ID: 実行環境内で動いている全てのジョブに一意なID


  • $CI_CONCURRENT_PROJECT_ID: 実行環境内とプロジェクト内で全てのジョブに一意なID

全ての実行環境でかつ、どのようなシナリオでも適切に動く最も安全な設定は、

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_PATHと一緒に使用する必要があります。すなわち、

group/subgroup/projectということになります。例:

variables:

GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH

test:
script:
- pwd


変数のパスのネスト

GIT_CLONE_PATHの値の展開は1回のみで、値に変数のネストには対応していません。

例えば、.gitlab-ci.ymlファイルで以下のような変数を2つとも設定して

いたとします:

variables:

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

GIT_CLONE_PATHは1回$CI_BUILDS_DIR/go/src/namespace/projectに展開

されますが、この中の$CI_BUILDS_DIRは展開されないので、エラーになります。


YAMLの特殊記法

アンカー(&)、エイリアス(*)とマップのマージ(<<)といった YAML の特殊機能

を使うこともできます。これらを使うと、.gitlab-ci.ymlの複雑な記述を大幅に減らする

ことができます。

YAMLのその他の機能について詳しくは YAML features を見てください。


隠しキー(ジョブ)


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


一時的に ジョブを'disable'するには、全てのジョブが設定されている行をコメントするよりも、

次のようにすることができます:

#hidden_job:

# script:
# - run test

ジョブ名を(.)で始まる名前にします。そうするとGitLab CIでは実行されなくなります。

次の例では、.hidden_jobというジョブは無視されます

.hidden_job:

script:
- run test

この機能を使えば、実行されないジョブを作ったり、YAMLの特殊機能special YAML featuresを使って、隠しキーをテンプレートに変換できます。


アンカー


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


YAMLには、ドキュメントにまたがって重複した内容をまとめて扱う'anchors'という

機能があります。Anchors を使うと、重複した内容や、継承するプロパティーに

使うことができます。ジョブの中でhidden keys

テンプレートとして扱う完璧な例です。

次のサンプルでは、アンカーとマップのマージの両方があります。test1test2という

2つのジョブを作り、.job_templateのパラメータを継承して、それを保持したカスタム

script を定義しています:

.job_template: &job_definition  # 隠しキーに'job_definition'というアンカー名を定義

image: ruby:2.1
services:
- postgres
- redis

test1:
<<: *job_definition # 'job_definition'のエイリアスの内容をマージ
script:
- test1 project

test2:
<<: *job_definition # 'job_definition'のエイリアスの内容をマージ
script:
- test2 project

&で(job_definition)という名前のアンカーを設定し、<<で示したハッシュを

ここに結合します。*は、アンカー名(再度job_definition) を指定しています。

展開されると以下のようになります:

.job_template:

image: ruby:2.1
services:
- postgres
- redis

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

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

他の例も見てみましょう。今度は、サービスを2つ定義してアンカーを定義しています。

そして、test:postgrestest:mysqlという2つのジョブを作っています。

この中で、.job_templateで示されたscriptが共有され、servicesの定義で、.postgres_services.mysql_servicesが参照されています:

.job_template: &job_definition

script:
- test project

.postgres_services:
services: &postgres_definition
- postgres
- ruby

.mysql_services:
services: &mysql_definition
- mysql
- ruby

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

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

これが展開されると以下のようになります:

.job_template:

script:
- test project

.postgres_services:
services:
- postgres
- ruby

.mysql_services:
services:
- mysql
- ruby

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

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

隠しキーがテンプレートととして便利に使えることが分かると思います。


Triggers

トリガーはパイプラインがトリガートークン付きで起動したときに、API呼び出しにより

特定のブランチやタグ、コミットを強制的にリビルドするときに使います。

triggerと混同しないでください。

詳しくは、Read more in the triggers documentation.

参照して下さい。


Git push操作

1回のgit push操作で複数の変更をpushするときに、GitLabでは

最大4つでブランチとタグのパイプラインの作成を行います。

この制限は、マージリクエストにおけるパイプラインリクエストのアップデート

に対しては影響しません。pipelines for merge requestsを使った場合、全てのマージリクエストの更新においてパイプラインが

作成されます。


ジョブのスキップ

コミットメッセージに[ci skip][skip ci]が入っていると大文字小文字のどちらで

あっても、そのコミットは作成されますが、ジョブ実行はスキップされます

他にも、Git 2.10以降であれば、ci.skip Git push option

渡すこともできます:

git push -o ci.skip

本翻訳のライセンス:

https://gitlab.com/gitlab-org/gitlab-ce/blob/master/LICENSE