LoginSignup
689
643

More than 3 years have passed since last update.

@ynott(Tetsrou YNO)in株式会社スタイルズ

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

Last updated at Posted at 2017-09-17

v12.10.2を元に翻訳をRulesの項まで更新しました(2020/06/01)
GitLab v13がリリースされるのもあり、更新作業中です(多分v13のリリースには間に合いません...)。翻訳が終わり次第更新する予定です(2020/05/14)
v12.0.3を元に翻訳を更新しました(2019/07/24)。

本記事は、
https://gitlab.com/gitlab-org/gitlab-ce/blob/v12.10.2/doc/ci/yaml/README.md
を翻訳中の文章です。

相対リンクなどは直す予定はありませんので、リンクをたどりたい方は以下のURLで公開しているものをご利用ください。
以下のGitLab側は近日更新予定
https://gitlab.com/stylez-co-jp/gitlab-ce/tree/dev-v12.0.3-ja.1/doc-ja/ci/yaml
リンクがあっても翻訳されているとは限りません。ご了承ください。
表なども上記リンクのgitlab.comの方が見やすいかと思います。

【宣伝】

本記事の電子書籍をBOOTHで以下の通り販売しております。
サークル詳細 | てっき～メディア | 技術書典
https://techiemedia.booth.pm/items/1579669

GitLab CIリファレンスに加えてクイックスタートガイドも収蔵しております。

＜宣伝終了＞

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

Variablesに関するリファレンスも翻訳しました。
よろしければこちらもどうぞ。

GitLab CI/CD Variables を翻訳しました。 - Qiita
https://qiita.com/ynott/items/4c5085b4cd6221bb71c5

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

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

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

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

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

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

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/CDには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
  • 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 ジョブを実行した後に動かすコマンドを設定。
stages パイプラインのステージリストを定義。
stage ジョブのステージ名を定義 (デフォルト: test).
only ジョブが実行される条件を設定。次の指定も可能: only:refs, only:kubernetes, only:variables, and only:changes.
except ジョブが実行されない条件を設定。次の指定も可能: except:refs, except:kubernetes, except:variables, and except:changes.
rules ジョブの指定された属性を評価、決定して、ジョブを作成するかどうかを決めるための条件リスト。only/exceptと同時には利用できません。
tags Runnerに設定されているタグを元に特定のRunnerで実行。
allow_failure ジョブの失敗を許容する。失敗したジョブでは、コミットステータスが変更されない。
when ジョブを実行するタイミング。次の指定も可能: when:manualとwhen:delayed.
environment ジョブをデプロイする環境名。次の指定も可能: environment:name, environment:url, environment:on_stopとenvironment:action.
cache ジョブ間で共有するキャッシュのファイルリスト。次の指定も可能: cache:paths, cache:key, cache:untrackedと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 失敗時に、ジョブを自動的にいつ、何回、リトライするかどうかを設定。
timeout プロジェクト全体の設定をよりも優先度の高い、ジョブ毎の個別タイムアウト設定を定義
parallel ジョブを実行するインスタンスを並列で実行する数を設定。
trigger 連携した下位のパイプラインの呼び出し先を設定。
include 外部のYAMLファイルを読み込んでジョブに追加する設定。次の指定も可能: include:local, include:file, include:templateと include:remote.
extends 他の場所に記述したジョブの内容を読み込んで拡張する設定。
pages GitLabページを使ってジョブの結果をアップロードする設定。
variables ジョブレベル毎にジョブの変数を設定。 ｜
interruptible 後から新しいパイプラインが実行されたときにジョブをキャンセルできるかどうかを設定。
resource_group ジョブの同時実行制限

NOTE: 注意:
typesとtypeパラメーターは、deprecatedとなっています。

デフォルトパラメータ設定

いくつかのパラメーターは、default:キーワードにより全てのジョブのデフォルト値として
グローバルに設定できます。デフォルト値は、ジョブ毎の設定値で上書きできます。

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

次の例では、rspec 2.6ジョブでのみ、ruby:2.6のイメージを利用しますが、
それ以外の全てのジョブはruby:2.5のイメージをデフォルトのイメージとして利用します:

default:
  image: ruby:2.5

rspec:
  script: bundle exec rspec

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

継承

GitLab 12.9.で導入されました。

inherit: パラメーターを使うとグローバルに定義されたデフォルト値や
変数を継承しないようにできます。

variables:やdefault:での全てのパラメーターの値を継承するしないの設定は、次のような書式です:

  • default: true or default: false
  • variables: true or 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

パラメーター詳細

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

script

script はジョブに唯一の必須のパラメーターです。 中身はシェルスクリプトです。
これがRunnerで実行されます。例えば：

job:
  script: "bundle exec rspec"

YAMLのスクリプト用のアンカーも利用できます。

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

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

NOTE: 注意:
場合によっては、 script のコマンドを シングルまたはダブルクオートでくくる必要があります。
例えば、コロン(:) を含んだコマンドは引用符で囲む必要があり、そうすることによりYAMLパーサーは
"key：value"のペアではなく文字列として解釈することができます。次の特殊文字を使う場合は注意
してください：
:, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `.

どこかのスクリプトコマンドがゼロ以外の終了コードを返してしまう場合、そのジョブは
エラーと見なされ、その先のコマンドは実行されません。その場合、終了コードを変数に
格納することにより回避してください:

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

image

ジョブを実行するベースとなる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とafter_script

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

before_script には、デプロイジョブを含むそれぞれのジョブの起動前に実行されるコマンドを指定します。
しかし、実行されるのはartifactsが復元されたあとになります。
これは配列である必要があります。

before_script で指定されたスクリプトは、ジョブのscriptで指定された
スクリプトと結合され、1つのシェル内でまとめて実行されます。

after_script には、失敗したジョブを含むそれぞれのジョブの実行後に実行されるコマンドを指定します。
これは配列である必要があります。

after_scriptで指定されるスクリプトは、新しいシェルで実行され、before_scriptやscriptスクリプト
とは分けられています。その為、以下のようになります:

  • 現在のワーキングディレクトリをデフォルトに戻します。
  • シェル実行は、before_scriptとscriptとは別の枠で実行されます。
  • 別の枠で実行されるので、before_scriptとscriptで定義されたスクリプトの変更を
    以下のいずれかの場合、利用することができません:
    • scriptスクリプト内で定義されたコマンドのエイリアスや変数を定義
    • ワーキングツリーの外部(Runner実行環境に依存)。例えば、before_scriptやscript
      で適用されたソフトウェアのインストール
  • タイムアウト時間は5分に固定されている。詳しくは関連するイシューを参照
  • ジョブの実行終了値に影響されない。もし script セクションが成功して、after_script
    がタイムアウトするか失敗した場合でも、コード0(Job Succeeded)でジョブは終了します。

ジョブ毎にbefore_scriptとafter_scriptを定義でき、全体に定義しているものを
上書きすることができます:

default:
  before_script:
    - global before script

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

YAMLのスクリプト用のアンカーも利用できます。

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.ymlにstagesが定義されていない場合、buildとtest、
    deployがデフォルトのジョブのステージです。
  2. ジョブがstageが定義されてない場合、ジョブはtestステージに割り当てられます。

.preと.post

GitLab 12.4で導入されました。

以下のステージは、様々なパイプラインで利用できます:

  • .preは常にパイプラインの一番最初のステージであることが規定されています。
  • .postは常にパイプラインの一番最後のステージであることが規定されています。

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

The order of .pre and .post cannot be changed, even if defined out of order in .gitlab-ci.yml.
For example, the following are equivalent configuration:

.gitlab-ci.ymlで間違った順番で定義されていたとしても、.preと.postの位置関係は変えることはできません。
例えば、以下の例は同じ設定になります:

  • 正しい順番で定義されている:

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

  • 間違って順番で定義されている:

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

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

    stages:
  - a
  - b

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

stage

stageはジョブ毎に1つ定義し、全体レベルに定義されているstagesに関連
しています。それぞれのステージ毎にジョブをグループにすることができ、同じstageのジョブは、
並列で実行されます。(certain conditionsについても参照)
次のようになります:

stages:
  - build
  - test
  - deploy

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

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

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

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

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

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

自分指定のRunnerを使う

自分指定のRunnerを使う場合、デフォルトではGitLab Runnerを同時に1つだけ使うことができます。
(並列度についてのconcurrentフラグについては Runner global settingsを見てください)

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

  • 別々のRunnerで走らせた場合
  • Runnerのconcurrentで並列度が変更された場合。

only/except (基本)

NOTE: 注意:
現在、rules構文を使ってジョブの実行ポリシーを設定する方法をお勧めしています。
onlyとexceptは、 非推奨の候補
となっているので、今後削除される可能性があります。

onlyとexceptの2つは、ジョブが開始されたときにそのジョブを実行するしないの実行条件を
設定するパラメーターです:

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

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

  • onlyとexceptは包含的に使えます。onlyとexceptがジョブ内で両方定義
    されていた場合、onlyとexceptの両方で絞り込めます。
  • onlyとexceptには正規表現 (supported regexp syntax)が使えます。
  • onlyとexceptフォークした場合のジョブを絞り込むのにリポジトリパスも指定できます。

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

キーワード 詳細
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参照)
external_pull_requests GitHub上で外部プルリクエストが作成または更新された場合 (Pipelines for external pull requestsを参照)
chat 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
  except:
    - master@gitlab-org/gitlab
    - /^release$/.*$/@gitlab-org/gitlab

この例では、masterブランチを除く、gitlab-org/gitlabの全てのブランチでは、
jobを実行しますが、release/のプレフィックス名がついているものでは実行しません。

onlyルールがない場合は、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では、onlyとexceptで内部的に使用される正規表現を
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

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

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

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

  • only: これは、"すべての条件が一致する場合にこのジョブを組み込む"を意味します。
  • except: これは、"いずれかの条件が一致した場合にこのジョブを除外する"という意味です

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

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

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

  • パイプラインがscheduled またはmasterで実行されている.
  • variablesキーワードがマッチしている。
  • プロジェクトでkubernetesサービスが有効になっている。
test:
  script: npm run test
  only:
    refs:
      - master
      - schedules
    variables:
      - $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/
    kubernetes: active

exceptはこの全ての式の否定として実装されている。

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

これは、キーが OR で結合されているかのように扱われることを意味します。この関係は次のように説明できます。

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

以下の例では、以下の上限のどれかでも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では、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で導入されました。

changesをonlyもしくは exceptと合わせて使うと、GitのPush操作で変更された
ファイルの有無によってジョブを開始するかどうかを指定できます。

これは、つまりonly:changesポリシーは、以下のような時のパイプラインで有用です:

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

Git pushイベントがない場合、例えば
上の三つ以外のソース
において、changesでは、与えられたファイルが新しいのか古いのか見分けがつかないので、
常にtrueを返します。

only: changesを使った基本的な例:

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

この例では、GitLabに既存のブランチにコミットをPushされた時に次のファイルが変更
されるコミットがあるときにのみ、それをトリガーにしてdocker buildジョブを
実行ジョブを実行します:

  • Dockerfileファイル
  • docker/scripts/内での変更
  • dockerfilesディレクトリ内のサブディレクトリ内
  • more_scripts配下のrb、py、shの拡張子が付いているファイル

CAUTION: 警告:
only:changesを パイプラインが成功したときにのみマージリクエストを許可すると一緒に使った場合、
only:merge_requestsも同時に利用しないと、
望まない挙動をする可能性があります。

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

また、グロブパターンを使用してリポジトリーのルートディレクトリや _全ての_ディレクトリ
配下のファイルを複数マッチさせることもできます。しかし、二重引用符でくくらないと、
.gitlab-ci.ymlのパースの段階でGitLabはエラーを返します。以下のような例です:

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

以下の例では、レポのルートディレクトリにある .md という拡張子を持つファイルに変更があっても
buildジョブをスキップします(実行しません):

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

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

CAUTION: 警告:
スケジュールされたパイプラインでこの機能を使用する際
に注意すべき点がいくつかあります。

merge_requestsパイプライン で only: changes を使うには

マージリクエストでファイルの変更を検知してジョブを実行するかどうかを評価するように
定義するには、pipelines for merge requestsを
使います。

ソースブランチの正しいベース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を使う

マージリクエストパイプラインがない場合、
マージリクエストと明示的に関連付けられていないブランチやタグ上で実行されます。
この場合、 git diff HEAD~と同じ、以前のSHAがdiffの計算に使用されるため、
以下のような予期せぬ動作をする可能性があります:

  • 新しいブランチや新しいタグをGitLabにプッシュする際には、このポリシーは常にtrueと評価します。
  • 新しいコミットをプッシュすると、変更されたファイルは(ベースSHAのような)前のコミットを使って
    計算されます。
Using only:changes with scheduled pipelines

only:changes always evaluates as "true" in Scheduled pipelines.
All files are considered to have "changed" when a scheduled pipeline
runs.

Scheduled pipelinesでは、only:changesは"true"と評価されます。
スケジュールされたパイプラインが走るとき、全てのファイルが更新されたものとして
扱われます。

rules

GitLab 12.3で導入されました。

rulesを使って、個々のルール設定を一つずつ順に一致するまで評価して、
ジョブに動的に属性を与えること後ができるようになります。
rulesは、only/exceptを置き換えることを目指しているため同時に組み合わせて利用する
ことはできない点に注意してください。そのように使用すると、文法チェック時に
key may not be used with rulesというエラーが発生します。

利用可能なルールは以下のようなものがあります:

例として、ifを使ってみます。以下の設定では、他のビルドの状態に関係なく、masterを
ターゲットとしたマージリクエストでのすべてのパイプラインでjobをビルドして実行
するように指定します:

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
      when: always
    - if: '$VAR =~ /pattern/'
      when: manual
    - when: on_success

この例では、最初のルールがifです:

  • これにマッチしたら、when:always属性がジョブに対して与えられます。
  • マッチしなかったら、マッチするものが見つかるまで2番目と3番目のルールが
    順次評価されます。つまり、ジョブにはこの後の2つのどちらかが割り振られます:
    • 2番目のルールにマッチしたら、when: manualが。この手動ジョブがトリガーされ、正常に完了するまでステージは完了しません。
    • 2番目のルールにマッチしなかったら、when: on_successが。3番目のルールは、
      条件がないので、到達時には必ずマッチします。

rules:if

rules:ifはonly:variablesとは少し違っていて、評価式が配列ではなくて単一の文字列の
式のみを受け付けるようになっています。評価される式のセットは、
変数のマッチング構文と&&や||を使って
1つの式に結合して使用する必要があります。

例:

job:
  script: "echo Hello, Rules!"
  rules:
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"' # This rule will be evaluated
      when: always
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' # This rule will only be evaluated if the target branch is not "master"
      when: manual
    - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # If neither of the first two match but the simple presence does, we set to "on_success" by default

提供されたルールのどれにも一致しない場合、ジョブにはwhen:neverが指定され、
パイプラインには組み込まれません。rules:whenが設定に全く含まれていない場合、
job:whenがデフォルトの挙動になり、その場合はデフォルトで引き続きon_success
です。

rules:changes

rules: changesは、パスの配列を受け取ってonly: changesとexcept: changesを全く
同じように動きます。Git pushイベントがない場合、同じように常にtrueを返します。
only/except: changesで詳細を確認してください。

例:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - changes: # Will include the job and set to when:manual if any of the follow paths match a modified file.
      - Dockerfile
      when: manual
    - if: '$VAR == "string value"'
      when: manual # Will include the job and set to when:manual if the expression evaluates to true, after the `changes:` rule fails to match.
    - when: on_success # If neither of the first rules match, set to on_success

この例では、以下のようにセットされたジョブです:

  • Dockerfileが変更されたか、$VAR == "string value"である場合、手動で実行になる。
  • その前の句が真と評価される事がない場合、最後のルールがwhen:on_successになります。

rules:exists

GitLab 12.4で導入されました。

existsにはpathの配列を指定して、それがリポジトリ内にあるファイルである場合には
マッチします。

例:

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

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

例:

job:
  script: bundle exec rspec
  rules:
    - exists:
      - spec/**.rb

NOTE: 注意:
パフォーマンス上の理由で、パターンでexistsを使った場合、チェックは10000回に
制限されています。10000番目のチェック後は、グロブパターンのルールは常にマッチします。

rules:allow_failure

GitLab 12.8で導入されました。

パイプライン自身を停止することなく、実行を待つ手動実行やジョブの実行の失敗を許容するallow_failure: trueをrules:を使うことができます。allow_failure:が定義されていない場合、rules:を使ったジョブは、
デフォルトで、allow_failure: falseです。

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

この例では、ルールにマッチしたらジョブにはwhen: manualとallow_failure: trueが割り当てられます。

Exclude jobs with rules: from certain pipelines

rules:が付いているジョブでは、予期せず2つのパイプラインが生成される可能性があります:

onlyとexceptのジョブでは、デフォルトではマージリクエスト時にパイプラインは起動しませんが、
rules:ではそうではありません。その為、onlyとexceptからrules:に移行したときに驚かれるかも
しれません。

マージリクエストがあるブランチに対するコミットでrules:を使っている時に2つのパイプラインが
起動する場合には、それを避ける方法として2つのオプションがあります:

  • マージリクエストのパイプラインからrules:を使っているそれぞれのジョブを個別に除外します。
    以下の例では、マージリクエストのパイプラインでは、ジョブを実行しないようにします。
    しかし、新しいタグやブランチrefsで動いているパイプラインでは実行されます:

    job:
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: never
    - when: manual
  script:
    - echo hello

  • workflow: rulesを全体設定に追加すると、特定の状況でのみパイプラインを
    実行するようになります。以下の例では、マージリクエスト、新規タグ、masterでの変更の時にのみ、
    パイプラインを実行します。master以外のどのブランチでも、パイプラインは実行されません。
    しかし、どのブランチをターゲットにしたマージリクエストでも、デタッチされたマージリクエストパイプラインでは実行されます:

    workflow:
  rules:
    - if: $CI_MERGE_REQUEST_ID
    - if: $CI_COMMIT_TAG
    - if: $CI_COMMIT_BRANCH == "master"

複合的ルール句

if、changesとexistsを ANDでつないで、同じルールのなかで
利用する。

次のような例をあげます:

  • Dockerfileファイルや、docker/scripts/配下のファイルが変更されるか、または
    $VAR == "string value"である場合にジョブを手動実行します。
  • その為、このジョブはパイプライン内には組み込まれません。
docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: '$VAR == "string value"'
      changes: # 変更されたファイルがこの句の下のパスにマッチすれば、ジョブに登録し、when:manualをセットします。
      - Dockerfile
      - docker/scripts/*
      when: manual
  # - when: never と書くのは重複した表現で、neverは暗黙的にいつもルールに入っています。

現在、使える句は以下のものしかありません:

  • if
  • changes
  • exists

現時点で、branchesやrefsといったキーボードが使えるのは、only/exceptのみで
rulesでは利用できません。どういったシチューエーションでこれらが利用されるか、
どういった挙動をさせるかを個別に検討している段階です。

適用可能な属性

現在、rulesに適用可能なジョブの属性は、以下のものです:

  • when.
  • start_in, if when is set to delayed.
  • start_in、whenが設定されいている場合はdelayed
  • allow_failure.

whenがnever以外であれば、どのような値で評価されていても、ジョブはパイプラインに
組み込まれます。

遅延ジョブには、start_inと値が必要なので、ルール指定も同様になります。例えば、
いかようになります:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - changes: # を付けると3時間遅らせるジョブにDockerfileが変更された時の条件を追加します
      - Dockerfile
      when: delayed
      start_in: '3 hours'
    - when: on_success # それ以外の場合は、ジョブを組み込んで通常通り実行します。

将来的にこれら以外のジョブ設定が追加される可能性があります。便利で有用だと考えられるが、
使えないケースがある場合には、issueを投稿.
してください。

workflow:rules

GitLab 12.5で導入されました。

最上位レベルのworkflow:キーは、パイプライン全体に適用され、パイプライン自体が
実行されるかどうかを決めます。現状では、rules: defined within jobs
と同じ動きをする単一のrules:キーのみを受け付け、パイプラインを動的に設定することが
できるようになっています。

現在 workflow:rules で利用可能な設定オプションは以下の通りです:

  • if: ルールを定義する。
  • when: 取り得る値はalwaysかneverのみ。指定しない場合のデフォルト値は always。

ifルールのリストは、1つがマッチするまで評価されます。一致するものがなければ、
最後の when が使われます:

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

tags

tagsを指定すると、そのプロジェクトで利用できる全てのRunnerのなかから、そのタグを
つけられている特定のRunnerでジョブを実行させることができます。

RunnerにはGitLabに登録するときに、rubyとか postgres、developmentといった
タグを事前に付けておくことができます。

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

job:
  tags:
    - ruby
    - postgres

上記の指定では、rubyとpostgresタグの両方が設定された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 ツールの残り部分で影響を与えなければ、
そのジョブがエラーになっても終了しません。
The default value is false, except for manual jobs using the
when: manual syntax, unless using rules: syntax, where all jobs
default to false, including when: manual jobs.

これを有効にしていてジョブがエラーになったら、UI上でオレンジの警告メッセージが表示されます。
しかし、パイプラインの論理的なフロー上ではジョブは 成功/合格とされてブロックされることは
ありません。

それ以外のジョブが成功したとすると、そのジョブとパイプラインには同じオレンジ色のメッセージが
表示されます。ただし、関連するコミットは警告なしに"合格"とマークされます。

以下の例では、job1とjob2が並列に実行され、job1が失敗しても、
allow_failure: trueがついているため、止まることなく次のステージに移行します:

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

job2:
  stage: test
  script:
  - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
  - deploy_to_staging

when

whenは、ジョブの失敗や失敗した場合のジョブの挙動を制御するために使用します。

whenでは次の値のどれかを指定できます:

  1. on_success - 直前のジョブが全て成功した場合にのみジョブが実行されます。
    (または、allow_failureが指定されているために成功と見なしている場合)
    これはデフォルトの挙動です。
  2. on_failure - 直前のステージで一つでもジョブが失敗したときにのみジョブを実行します。
  3. always - 直前のステージでジョブの状態がどうであるかにかかわらずジョブを実行します。
  4. manual - ジョブを手動で実行します(GitLab 8.10で追加されました)。以下のmanual actionsを参照してください。
  5. delayed - execute job after a certain period (added in GitLab 11.14).
    Read about delayed actions below.

例:

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を参照してください。

手動実行はオプションまたはブロックのどちらかを取ります。ブロッキングの場合は、
手動アクションはこれがで定義されている部分でパイプラインの実行をブロックします。
ブロックされている手動アクションは、誰かが play ボタンを押したらパイプラインの
実行が継続されます。

パイプラインがブロックされたら、パイプラインが成功したときにのみマージされると
していた場合、マージされません。ブロックされたパイプラインはステータスが manual
という特殊なものになります。デフォルトでは手動実行がブロックされることはありません。
手動実行で(失敗時に)ブロックしたい場合には、allow_failure: falseを.gitlab-ci.yml
のジョブ定義に追加してください。

When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds
is set. Blocked pipelines also do have a special status, called manual.
When the when:manual syntax is used, manual actions are non-blocking by
default. If you want to make manual action blocking, it is necessary to add
allow_failure: false to the job's definition in .gitlab-ci.yml.

手動実行のオプションは、デフォルトでallow_failure: trueとなっているので、全体の
パイプラインステータスには影響しません。手動実行が失敗した場合でも、パイプライン自体は
成功というステータスになります。

NOTE: Note:
When using rules:, allow_failure defaults to false, including for manual jobs.

手動実行で書込み操作にあたるため、ユーザーがそのトリガーを実行したときには、
protected branchesのパーミッションが
必要になります。つまり、手動実行をパイプライン内で実行するためには、このブランチに
対するマージ権限を持っている必要があります。

Manual actions are considered to be write actions, so permissions for
protected branches are used when
a user wants to trigger an action. In other words, in order to trigger a manual
action assigned to a branch that the pipeline is running for, the user needs to
have the ability to merge to this branch. It is possible to use protected environments
to more strictly protect manual deployments from being
run by unauthorized users.

NOTE: Note:
Using when:manual and trigger together results in the error jobs:#{job-name} when should be on_success, on_failure or always, because when:manual prevents triggers
being used.

Protecting manual jobs (PREMIUM)

It's possible to use protected environments
to define a precise list of users authorized to run a manual job. By allowing only
users associated with a protected environment to trigger manual jobs, it is possible
to implement some special use cases, such as:

  • More precisely limiting who can deploy to an environment.
  • Enabling a pipeline to be blocked until an approved user "approves" it.

To do this, you must:

  1. Add an environment to the job. For example:

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

  2. In the protected environments settings,
    select the environment (production in the example above) and add the users, roles or groups
    that are authorized to trigger the manual job to the Allowed to Deploy list. Only those in
    this list will be able to trigger this manual job, as well as GitLab administrators
    who are always able to use protected environments.

Additionally, if a manual job is defined as blocking by adding allow_failure: false,
the next stages of the pipeline will not run until the manual job is triggered. This
can be used as a way to have a defined list of users allowed to "approve" later pipeline
stages by triggering the blocking manual job.

when:delayed

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

遅延ジョブを使うとスクリプトが実行されて一定時間後に起動するジョブを作ることができます。
すぐにジョブが実行待ちステータスになってしまうのを避けたい場合に役に立ちます。

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

  • 10 seconds
  • 30 minutes
  • 1 hour
  • 1 day
  • 1 week

ステージに遅延ジョブがあった場合、遅延ジョブが終了するまでパイプラインは進みません。
つまり、別々のステージ間で遅延を追加するのに使えると言うことです。

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

次の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: 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(空白)
  • -
  • _
  • /
  • $
  • {
  • }

一般的な名前は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'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

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

環境を閉じる(停止する)には、environmentでon_stopキーワードを使用します。
環境を閉じるために必要な別のジョブを定義することができます。

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

environment:action

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

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

例:

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

stop_review_app:
  stage: deploy
  variables:
  GIT_STRATEGY: none
  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 で動かすことが必要です。

Also in the example, GIT_STRATEGY is set to none so that GitLab Runner won’t
try to check out the code after the branch is deleted when the stop_review_app
job is automatically triggered.

NOTE: Note:
The above example overwrites global variables. If your stop environment job depends
on global variables, you can use anchor variables when setting the GIT_STRATEGY
to change it without overriding the global variables.

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

  • when - reference
  • environment:name
  • environment:action
  • stageをreview_appと同じ場所にして、ブランチが削除されたときに自動的に
    停止する環境にする必要があります。

environment:auto_stop_in

Introduced in GitLab 12.8.

The auto_stop_in keyword is for specifying life period of the environment,
that when expired, GitLab automatically stops them.

For example,

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

When review_app job is executed and a review app is created, a life period of
the environment is set to 1 day.

For more information, see
the environments auto-stop documentation

environment:kubernetes

Introduced in GitLab 12.6.

The kubernetes block is used to configure deployments to a
Kubernetes cluster that is associated with your project.

For example:

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

This will set up the deploy job to deploy to the production
environment, using the production
Kubernetes namespace.

For more information, see
Available settings for kubernetes.

NOTE: Note:
Kubernetes configuration is not supported for Kubernetes clusters
that are managed by GitLab.
To follow progress on support for GitLab-managed clusters, see the
relevant issue.

動的環境

  • GitLab 8.12 と GitLab Runner 1.6のIntroducedで導入されました。
  • The $CI_ENVIRONMENT_SLUG はGitLab 8.15のintroducedで導入されました。
  • nameとurlパラメーターは、定義済みの任意のCI変数を何でも利用でき、定義済みの変数、
    .gitlab-ci.ymlの変数、シークレット変数などのvariables を使用することが
    できます。しかし、 script 配下の変数だけは利用できません。

例:

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

deploy as review app(レビュー用にデプロイ) ジョブでは、 review/$CI_COMMIT_REF_NAME
という名前の環境を動的に作成するという指定になっています。ここでは、$CI_COMMIT_REF_NAMEは
Runner が指定した[environment variable][variables]です。
$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ディレクティブを使用して、どのファイルまたはディレクトリをキャッシュするかを
選択します。ワイルドカードも使用できます。

Use the paths directive to choose which files or directories will be cached. Paths
are relative to the project directory ($CI_PROJECT_DIR) and cannot directly link outside it.
Wildcards can be used that follow the glob
patterns and filepath.Match.

以下の設定では、.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:key:files

Introduced in GitLab v12.5.

The cache:key:files keyword extends the cache:key functionality by making it easier
to reuse some caches, and rebuild them less often, which will speed up subsequent pipeline
runs.

When you include cache:key:files, you must also list the project files that will be used to generate the key, up to a maximum of two files.
The cache key will be a SHA checksum computed from the most recent commits (up to two, if two files are listed)
that changed the given files. If neither file was changed in any commits,
the fallback key will be default.

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

In this example we are creating a cache for Ruby and Node.js dependencies that
is tied to current versions of the Gemfile.lock and package.json files. Whenever one of
these files changes, a new cache key is computed and a new cache is created. Any future
job runs using the same Gemfile.lock and package.json with cache:key:files will
use the new cache, instead of rebuilding the dependencies.

cache:key:prefix

Introduced in GitLab v12.5.

The prefix parameter adds extra functionality to key:files by allowing the key to
be composed of the given prefix combined with the SHA computed for cache:key:files.
For example, adding a prefix of test, will cause keys to look like: test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5.
If neither file was changed in any commits, the prefix is added to default, so the
key in the example would be test-default.

Like cache:key, prefix can use any of the predefined variables,
but the following are not allowed:

  • the / character (or the equivalent URI-encoded %2F)
  • a value made only of . (or the equivalent URI-encoded %2E)
cache:
  key:
    files:
      - Gemfile.lock
    prefix: ${CI_JOB_NAME}
  paths:
    - vendor/ruby

rspec:
  script:
    - bundle exec rspec

For example, adding a prefix of $CI_JOB_NAME will
cause the key to look like: rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5 and
the job cache is shared across different branches. If a branch changes
Gemfile.lock, that branch will have a new SHA checksum for cache:key:files. A new cache key
will be generated, and a new cache will be created for that key.
If Gemfile.lock is not found, the prefix is added to
default, so the key in the example would be rspec-default.

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を見てください。

Paths are relative to the project directory ($CI_PROJECT_DIR) and cannot directly
link outside it. Wildcards can be used that follow the glob
patterns and filepath.Match.

To restrict which jobs a specific job will fetch artifacts from, see 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

You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with xyz:

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

artifacts:expose_as

Introduced in GitLab 12.5.

The expose_as keyword can be used to expose job artifacts
in the merge request UI.

For example, to match a single file:

test:
  script: [ 'echo 1' ]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['path/to/file.txt']

With this configuration, GitLab will add a link artifact 1 to the relevant merge request
that points to file1.txt.

An example that will match an entire directory:

test:
  script: [ 'echo 1' ]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['path/to/directory/']

Note the following:

  • A maximum of 10 job artifacts per merge request can be exposed.
  • Glob patterns are unsupported.
  • If a directory is specified, the link will be to the job artifacts browser if there is more than
    one file in the directory.
  • For exposed single file artifacts with .html, .htm, .txt, .json, .xml,
    and .log extensions, if GitLab Pages is:
    • Enabled, GitLab will automatically render the artifact.
    • Not enabled, you will see the file in the artifacts browser.

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にアップロードされ保存されてから、
削除されるまでにどれぐらいの期間、保存しておくか有効期限を指定できます。
有効期限が設定されていない場合は、デフォルトでは
インスタンスレベルで設定されます。
(通常は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(マージリクエストやパイプラインビュー、セキュリティーダッシュボード)からそれらのレポートを見られるようにします。

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:dotenv

Introduced in GitLab 12.9. Requires GitLab Runner 11.5 and later.

The dotenv report collects a set of environment variables as artifacts.

The collected variables are registered as runtime-created variables of the job,
which is useful to set dynamic environment URLs after a job finishes.
It is not available for download through the web interface.

There are a couple of limitations on top of the original dotenv rules.

  • The variable key can contain only letters, digits and underscore ('_').
  • The size of dotenv file must be smaller than 5 kilobytes.
  • The number of variables must be less than 10.
  • It doesn't support variable substitution in the dotenv file itself.
  • It doesn't support empty lines and comments (#) in dotenv file.
  • It doesn't support quote escape, spaces in a quote, a new line expansion in a quote, in dotenv file.
artifacts:reports:cobertura

Introduced in GitLab 12.9. Requires GitLab Runner 11.5 and above.

The cobertura report collects Cobertura coverage XML files.
The collected Cobertura coverage reports will be uploaded to GitLab as an artifact
and will be automatically shown in merge requests.

Cobertura was originally developed for Java, but there are many
third party ports for other languages like JavaScript, Python, Ruby, etc.

artifacts:reports:codequality (STARTER)

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

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

収集されたCode Qualityレポートは、成果物としてGitLabにアップロードされ、
マージリクエスト内にリストアップされます。Web画面からはダウンロードできません。

artifacts:reports:sast (ULTIMATE)

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

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

収集されたSASTレポートは、成果物としてGitLabにアップロードされ、
マージリクエストとパイプラインビュー内にリストアップされます。また、セキュリティー
ダッシュボードにデータを提供します。Web画面からはダウンロードできません。

artifacts:reports:dependency_scanning (ULTIMATE)

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

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

収集されたDependency Scanningレポートは、成果物としてGitLabにアップロードされ、
マージリクエストとパイプラインビュー内にリストアップされます。また、セキュリティー
ダッシュボードにデータを提供します。Web画面からはダウンロードできません。

artifacts:reports:container_scanning (ULTIMATE)

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

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

収集されたContainer Scanningレポートは、成果物としてGitLabにアップロードされ、
マージリクエストとパイプラインビュー内にリストアップされます。また、セキュリティー
ダッシュボードにデータを提供します。Web画面からはダウンロードできません。

artifacts:reports:dast (ULTIMATE)

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

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

収集されたDASTレポートは、成果物としてGitLabにアップロードされ、
マージリクエストとパイプラインビュー内にリストアップされます。また、セキュリティー
ダッシュボードにデータを提供します。Web画面からはダウンロードできません。

artifacts:reports:license_management (ULTIMATE)

CAUTION: Warning:
This artifact is still valid but was deprecated in favor of the
artifacts:reports:license_scanning
introduced in GitLab 12.8.

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

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

収集されたLicense Managementレポートは、成果物としてGitLabにアップロードされ、
マージリクエストとパイプラインビュー内にリストアップされます。また、セキュリティー
ダッシュボードにデータを提供します。Web画面からはダウンロードできません。

artifacts:reports:license_scanning (ULTIMATE)

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

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

収集されたLicense Complianceレポートは、成果物としてGitLabにアップロードされ、
マージリクエストとパイプラインビュー内にリストアップされます。また、セキュリティー
ダッシュボードにデータを提供します。Web画面からはダウンロードできません。

artifacts:reports:performance (PREMIUM)

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

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

収集されたPerformanceレポートは、成果物としてGitLabにアップロードされ、
マージリクエストとパイプラインビュー内にリストアップされます。また、セキュリティー
ダッシュボードにデータを提供します。Web画面からはダウンロードできません。

artifacts:reports:metrics (PREMIUM)

GitLab 11.10で導入されました。

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

収集されたMetricsレポートは、成果物としてGitLabにアップロードされ、
マージリクエスト内に自動的に表示されます。Web画面からはダウンロードできません。

dependencies

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

この機能は、 artifactsと組み合わせて使い、別のジョブで使うために
受け渡しする成果物を定義することができます。
デフォルトではその前の全てのステージのartifactsが転送されるのに注意してください。

By default, all artifacts from all previous stages
are passed, but you can use the dependencies parameter to define a limited
list of jobs (or no jobs) to fetch artifacts from.

この機能を使うには、ジョブの中でdependenciesを定義して、その一つ前のジョブ内では
どの成果物をダウンロードするべきかのリストを定義します。
現在のステージの一つ前で実行されたステージからのみジョブを定義できます。
現在のステージまたは次のステージからジョブに定義すると、エラーになります。
ジョブ上で空の配列を定義すると、成果物を何もダウンロードしません。
dependenciesを使うと直前のジョブの状態が考慮されないので、
ジョブが失敗したり、手動ジョブが実行されなかった場合にエラーは発生しません。

次の例では、build:osxとbuild: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
を依頼してください。

needs

  • Introduced in GitLab 12.2.
  • In GitLab 12.3, maximum number of jobs in needs array raised from five to 50.
  • Introduced in GitLab 12.8, needs: [] lets jobs start immediately.

The needs: keyword enables executing jobs out-of-order, allowing you to implement
a directed acyclic graph in your .gitlab-ci.yml.

This lets you run some jobs without waiting for other ones, disregarding stage ordering
so you can have multiple stages running concurrently.

Let's consider the following example:

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

This example creates four paths of execution:

  • Linter: the lint job will run immediately without waiting for the build stage to complete because it has no needs (needs: []).

  • Linux path: the linux:rspec and linux:rubocop jobs will be run as soon
    as the linux:build job finishes without waiting for mac:build to finish.

  • macOS path: the mac:rspec and mac:rubocop jobs will be run as soon
    as the mac:build job finishes, without waiting for linux:build to finish.

  • The production job will be executed as soon as all previous jobs
    finish; in this case: linux:build, linux:rspec, linux:rubocop,
    mac:build, mac:rspec, mac:rubocop.

Requirements and limitations

  • If needs: is set to point to a job that is not instantiated
    because of only/except rules or otherwise does not exist, the
    pipeline will be created with YAML error.
  • We are temporarily limiting the maximum number of jobs that a single job can
    need in the needs: array:
    • For GitLab.com, the limit is ten. For more information, see our
      infrastructure issue.
    • For self-managed instances, the limit is:
      • 10, if the ci_dag_limit_needs feature flag is enabled (default).
      • 50, if the ci_dag_limit_needs feature flag is disabled.
  • If needs: refers to a job that is marked as parallel:.
    the current job will depend on all parallel jobs created.
  • needs: is similar to dependencies: in that it needs to use jobs from prior stages,
    meaning it is impossible to create circular dependencies. Depending on jobs in the
    current stage is not possible either, but support is planned.
  • Related to the above, stages must be explicitly defined for all jobs
    that have the keyword needs: or are referred to by one.
Changing the needs: job limit

The maximum number of jobs that can be defined within needs: defaults to 10, but
can be changed to 50 via a feature flag. To change the limit to 50,
start a Rails console session
and run:

Feature::disable(:ci_dag_limit_needs)

To set it back to 10, run the opposite command:

Feature::enable(:ci_dag_limit_needs)

Artifact downloads with needs

Introduced in GitLab v12.6.

When using needs, artifact downloads are controlled with artifacts: true or artifacts: false.
The dependencies keyword should not be used with needs, as this is deprecated since GitLab 12.6.

In the example below, the rspec job will download the build_job artifacts, while the
rubocop job will not:

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

Additionally, in the three syntax examples below, the rspec job will download the artifacts
from all three build_jobs, as artifacts is true for build_job_1, and will
default to true for both build_job_2 and build_job_3.

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

Cross project artifact downloads with needs (PREMIUM)

Introduced in GitLab v12.7.

needs can be used to download artifacts from up to five jobs in pipelines on
other refs in the same project,
or pipelines in different projects:

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

build_job will download the artifacts from the latest successful build-1 job
on the master branch in the group/project-name project.

Artifact downloads between pipelines in the same project

needs can be used to download artifacts from different pipelines in the current project
by setting the project keyword as the current project's name, and specifying a ref.
In the example below, build_job will download the artifacts for the latest successful
build-1 job with the other-ref ref:

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

NOTE: Note:
Downloading artifacts from jobs that are run in parallel: is not supported.

coverage

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

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

ここで指定できるのは正規表現のみです。そのために正規表現の文字列であると明示的に
表現するために、 /で括る必要があります。特殊文字を文字としてマッチしたい場合は、
エスケープする必要があります。

簡単な例:

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

retry

GitLab 9.5のIntroducedで導入されました
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がサポート外の時に再試行
  • stale_schedule: Retry if a delayed job could not be executed.
  • job_execution_timeout: Retry if the script exceeded the maximum execution time set for the job.
  • archived_failure: Retry if the job is archived and cannot be run.
  • unmet_prerequisites: Retry if the job failed to complete prerequisite tasks.
  • scheduler_failure: Retry if the scheduler failed to assign the job to a runner.
  • data_integrity_failure: Retry if there was a structural integrity problem detected.

timeout

Introduced in GitLab 12.3.

timeout allows you to configure a timeout for a specific job. For example:

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

test:
  script: rspec
  timeout: 3h 30m

The job-level timeout can exceed the
project-level timeout but can not
exceed the Runner-specific timeout.

parallel

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

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

並列にジョブを動かす為にN個のインスタンスが起動されます。
順にjob_name 1/Nからjob_name N/Nまでの名前が付きます。

全てのジョブに対して、CI_NODE_INDEXとCI_NODE_TOTAL environment variablesが設定されます。例:

test:
  script: rspec
  parallel: 5

TIP: Tip:
Parallelize tests suites across parallel jobs.
Different languages have different tools to facilitate this.

A simple example using Semaphore Test Boosters and RSpec to run some Ruby tests:

# 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

CAUTION: Caution:
Please be aware that semaphore_test_boosters reports usages statistics to the author.

You can then navigate to the Jobs tab of a new pipeline build and see your RSpec
job split into three separate jobs.

trigger [PREMIUM]

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

  • Moved to GitLab Core in 12.8.

triggerは、下流のパイプラインを起動するトリガーを定義します。
trigger定義によりジョブが起動されたジョブがGitLabにより開始されると、
下流のパイプラインが作成されます。

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

This keyword allows the creation of two different types of downstream pipelines:

NOTE: Note:
Using a trigger with when:manual together results in the error jobs:#{job-name} when should be on_success, on_failure or always, because when: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

It is possible to mirror the status from a triggered pipeline:

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

It is possible to mirror the status from an upstream pipeline:

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

trigger syntax for child pipeline

Introduced in GitLab 12.7.

To create a child pipeline, specify the path to the
YAML file containing the CI config of the child pipeline:

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

Similar to multi-project pipelines,
it is possible to mirror the status from a triggered pipeline:

trigger_job:
  trigger:
    include:
      - local: path/to/child-pipeline.yml
    strategy: depend
Trigger child pipeline with generated configuration file

Introduced in GitLab 12.9.

You can also trigger a child pipeline from a dynamically generated configuration file:

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

The generated-config.yml is extracted from the artifacts and used as the configuration
for triggering the child pipeline.

Linking pipelines with trigger:strategy

By default, the trigger job completes with the success status
as soon as the downstream pipeline is created.

To force the trigger job to wait for the downstream (multi-project or child) pipeline to complete, use
strategy: depend. This will make the trigger job wait with a "running" status until the triggered
pipeline completes. At that point, the trigger job will complete and display the same status as
the downstream job.

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

This can help keep your pipeline execution linear. In the example above, jobs from
subsequent stages will wait for the triggered pipeline to successfully complete before
starting, at the cost of reduced parallelization.

interruptible

Introduced in GitLab 12.3.

interruptible is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to false.
This value will only be used if the automatic cancellation of redundant pipelines feature
is enabled.

When enabled, a pipeline on the same branch will be canceled when:

  • It is made redundant by a newer pipeline run.
  • Either all jobs are set as interruptible, or any uninterruptible jobs have not started.

Pending jobs are always considered interruptible.

TIP: Tip:
Set jobs as interruptible that can be safely canceled once started (for instance, a build job).

Here is a simple example:

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

In the example above, a new pipeline run will cause an existing running pipeline to be:

  • Canceled, if only step-1 is running or pending.
  • Not canceled, once step-2 starts running.

NOTE: Note:
Once an uninterruptible job is running, the pipeline will never be canceled, regardless of the final job's state.

resource_group

Introduced in GitLab 12.7.

Sometimes running multiples jobs or pipelines at the same time in an environment
can lead to errors during the deployment.

To avoid these errors, the resource_group attribute can be used to ensure that
the Runner will not run certain jobs simultaneously.

When the resource_group key is defined for a job in .gitlab-ci.yml,
job executions are mutually exclusive across different pipelines for the same project.
If multiple jobs belonging to the same resource group are enqueued simultaneously,
only one of the jobs will be picked by the Runner, and the other jobs will wait until the
resource_group is free.

Here is a simple example:

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

In this case, if a deploy-to-production job is running in a pipeline, and a new
deploy-to-production job is created in a different pipeline, it will not run until
the currently running/pending deploy-to-production job is finished. As a result,
you can ensure that concurrent deployments will never happen to the production environment.

There can be multiple resource_groups defined per environment. A good use case for this
is when deploying to physical devices. You may have more than one physical device, and each
one can be deployed to, but there can be only one deployment per device at any given time.

NOTE: Note:
This key can only contain letters, digits, -, _, /, $, {, }, ., and spaces, but it cannot start or end with /.

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

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

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

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

例:

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

Multiple include:template files:

include:
  - template: Android-Fastlane.gitlab-ci.yml
  - 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を全部で100回まで利用できます。
インクルードが重複していると構成エラーになります。

Introduced in GitLab 12.4.

A hard limit of 30 seconds was set for resolving all files.

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_USERとPOSTGRES_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.ymlでinstall_dependenciesとdeployが
改めて記述されていない場合、結合された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.ymlはgroup/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 testはscript: 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

また、GitLab 12.0以降で導入された複数の親を利用した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

extendsとincludeを一緒に使う

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 は、cp が public/ 自身をコピーして無限ループに陥るのを回避しています。

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で設定できるいわゆる秘密の変数もあります。

YAMLのスクリプト用のアンカーも利用できます。

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

Git strategy

  • GitLab 8.9で実験的機能として導入されました。
  • GIT_STRATEGY=none を指定するためには、 GitLab Runner v1.7以上が必要です。

CAUTION: Caution:
May change or be removed completely in future releases.

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のプレクローンスクリプトがあったとしても)スキップします。成果物に対してのみ動作
するジョブ(例えば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つの値をとることができます:none、normalとrecursive:

  • 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_STRATEGYでcloneかfetchに指定していて、
git checkoutを実施するかどうかを指定します。指定しない場合は、trueです。
variablesセクションで全体設定もしくは、ジョブ毎に設定できます。

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

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

trueに設定されていると、cloneとfetchでのストラテジーはどちらも、Runnerが
CIパイプラインに関連したリビジョンをワーキングコピーとしてチェックアウトするように
なります:

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

Git clean flags

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

GIT_CLEAN_FLAGS変数設定はソースコードをチェックアウトした後にgit cleanする
デフォルトの挙動を制御します。
variablesセクションで全体設定もしくは、ジョブ毎に設定できます。

GIT_CLEAN_FLAGSとしては、git clean
コマンドで利用できるオプションを全て受け付けられます。

GIT_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 実行しているジョブでキャッシュのリストア試行回数
EXECUTOR_JOB_SECTION_ATTEMPTS Since GitLab 12.10, the number of attempts to run a section in a job after a No Such Container error (Docker executor only).

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

例:

variables:
  GET_SOURCES_ATTEMPTS: 3

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

Shallow cloning

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

CAUTION: 注意:
将来のバージョンで完全に変更削除される可能性があります。

GIT_DEPTH を指定すると、Git の fetch と Clone の深さを指定することができます。
これを使うとリポジトリの深さを浅くクローニングができます。そうすることで多数のコミットや
古い、大きなバイナリを持つリポジトリのクローニングを大幅にスピードアップできます。
この値は、git fetch や git 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を使って下さい。

Globally-defined image, services, cache, before_script, after_script

Defining image, services, cache, before_script, and
after_script globally is deprecated. Support could be removed
from a future release.

Use default: instead. For example:

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

Custom build directories

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

NOTE: 注意:
この設定は、custom_build_dirがRunner's configuration
設定で有効になっている場合にのみ利用することができます。
dockerとkubernetesの実行環境ではデフォルトの設定です。

デフォルトでは、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/CDでは実行されなくなります。
次の例では、.hidden_jobというジョブは無視されます

.hidden_job:
  script:
    - run test

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

アンカー

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

YAMLには、ドキュメントにまたがって重複した内容をまとめて扱う'anchors'という
機能があります。Anchors を使うと、重複した内容や、継承するプロパティーに
使うことができます。ジョブの中でhidden keysを
テンプレートとして扱う完璧な例です。

次のサンプルでは、アンカーとマップのマージの両方があります。test1とtest2という
2つのジョブを作り、.job_templateのパラメータを継承して、それを保持したカスタム
script を定義しています:

.job_template: &job_definition  # 隠しキーに'job_definition'というアンカー名を定義
  image: ruby:2.6
  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.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が共有され、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.を
参照して下さい。

NOTE: Note:
You can't use YAML anchors across multiple files when leveraging the include
feature. Anchors are only valid within the file they were defined in.

YAML anchors for before_script and after_script

Introduced in GitLab 12.5.

You can use YAML anchors with before_script and after_script,
which makes it possible to include a predefined list of commands in multiple
jobs.

Example:

.something_before: &something_before
- echo 'something before'

.something_after: &something_after
- echo 'something after'


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

YAML anchors for script

Introduced in GitLab 12.5.

You can use YAML anchors with scripts, which makes it possible to
include a predefined list of commands in multiple jobs.

For example:

.something: &something
- echo 'something'

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

YAML anchors for variables

YAML anchors can be used with variables, to easily repeat assignment
of variables across multiple jobs. It can also enable more flexibility when a job
requires a specific variables block that would otherwise override the global variables.

In the example below, we will override the GIT_STRATEGY variable without affecting
the use of the SAMPLE_VARIABLE variable:

# global variables
variables: &global-variables
  SAMPLE_VARIABLE: 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

Triggers

Triggers can be used to force a rebuild of a specific branch, tag or commit,
with an API call when a pipeline gets created using a trigger token.

Not to be confused with 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を
渡すこともできます。

本翻訳のライセンス：
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/LICENSE

GitLab実践ガイド - インプレスブックス
https://book.impress.co.jp/books/1116101163

689
643
5

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
689
643