.gitlab-ci.yml によるジョブの設定方法(日本語訳)

  • 18
    Like
  • 0
    Comment

doc/ci/yaml/README.md · master · GitLab.org / GitLab Community Edition · GitLab
https://docs.gitlab.com/ce/ci/yaml/

.gitlab-ci.yml で ジョブを設定

.gitlab-ci.yml の使い方を解説したドキュメントです。このファイルは、プロジェクトでGitLab Runner を管理する為のファイルです。

GitLab CI の導入ガイドが必要ならば、quick start guideを見てください。

.gitlab-ci.yml

バージョン 7.12から GitLab CIは、プロジェクトの設定に YAMLfile (.gitlab-ci.yml)を使うようになりました。リポジトリのルートフォルダーに設置します。また、このファイルはどういう風にビルドするかが、書かれています。

YAMLファイルは、実行する時にどのように動作するかという制約付きジョブのセットを定義します。ジョブは、名前をトップレベルの要素として、最低限 script 句を含んでいます。

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

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

上の例は、CI 設定としては2つのジョブを含む最もシンプルなもので、それぞれ別のジョブを別のコマンドで実行します。

もちろん、リポジトリ内で (./configure;make;make install) といったコマンドを直接実行することもできますし、 (test.sh)といったスクリプトを実行することもできます。

ジョブは、Runners により選び出されて、Runner の環境で実行されます。重要なことは、それぞれのジョブは各々独立していると言うことです。

YAML の文法では、上の例よりももっと複雑なジョブの定義が可能です。

image: ruby:2.1
services:
  - postgres

before_script:
  - bundle install

after_script:
  - rm secrets

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - execute-script-for-job1
  only:
    - master
  tags:
    - docker

ジョブ名として 利用できない 予約済み キーワード がいくつかあります:

キーワード 必須 詳細
image いいえ Dockerイメージを利用する、Use Dockerを参照
services いいえ docker サービスを使用する、Use Dockerを参照
stages いいえ ビルドステージを定義
types いいえ stages (廃止予定) のエイリアス
before_script いいえ それぞれのジョブスクリプトの実行前に走らせるコマンドを定義
after_script いいえ ジョブスクリプトの実行に走らせるコマンドを定義
variables いいえ ビルド変数を定義
cache いいえ サブシークエント間でキャッシュするファイルのリストを定義

イメージとサービス

ここでは、カスタム Docker イメージを指定したり、ジョブの実行中に利用するサービスのリストを指定します。この機能に関する設定は、a separate document を参照してください

before_script

before_script では、成果物の修復の後で、遅延ジョブを含めた全てのジョブの前に実行するコマンドを定義するために使います。ここでは、配列または複数行を定義できます。

after_script

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

after_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 が定義されておらず、 buildtestdeploy がデフォルトでジョブのステージとして許可されている場合。
  2. ジョブに stage が定義されておらず、ジョブが test ステージに割り当てられている場合。

types

廃止予定、将来のリリースで削除されます。代わりに stages を使ってください。

stages のエイリアス(別名)

variables

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

GitLab CI では .gitlab-ci.yml に変数を追加することができます。これによりジョブの環境に変数を設定することができます。この変数は Git リポジトリに保存される、あまり機密性をもとめられないプロジェクト設定を格納するためのものです。たとえば次のようになります。

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

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

これらの変数は、これ以降の実行される全てのコマンドやスクリプトで利用できます。
YAML で定義された変数は、同じように作成されたすべてのサービスコンテナにも適用できるため、微調整用として利用できます。 変数は、job level 単位でも定義することができます。

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

Learn more about variables.

cache

注意:
- GitLab Runner v0.7.0 で導入されました。
- GitLab 9.2 以前は キャッシュは成果物の生成の後に戻っていました。
- GitLab 9.2 から、キャッシュは成果物の生成の前に戻ります。

cache は、ジョブ間でキャッシュされるべきファイルとディレクトリを指定するために利用されます。プロジェクトワークスペース内のパスのみ利用することができます。

GitLab 9.0からデフォルトでキャッシュは有効になっていて、パイプラインやジョブの間で共有されます

cache が ジョブのスコープ外で定義されていた場合、全てのジョブでその定義を利用するグローバル設定となります。

binaries.config の全てのファイルがキャッシュされます:

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

Git の未追跡ファイルが全てキャッシュされます:

rspec:
  script: test
  cache:
    untracked: true

Git の未追跡ファイル と binaries のファイルが全てキャッシュされます:

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

ローカル定義されたキャッシュ設定は、グローバル設定を上書きします。次の rspec ジョブは、 binaries/ のみキャッシュします:

cache:
  paths:
  - my/files

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

キャッシュはジョブ間で共有されるため、違うジョブ毎に違うパスを使っている場合、それぞれに違った cache:key を設定してキャッシュする内容を上書できるようにします。

キャッシュは基本的にベストエフォートで提供されます。つまり、キャッシュがいつでもあると考えることはできません。実装の詳細は、GitLab Runner を確認してください。

cache:key

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

key ディレクティブ はジョブ間でキャッシュされる融通性を定義し、全てのジョブで1つのキャッシュを定義するか、ジョブ毎で定義するか、ブランチ毎でキャッシュするなど、あなたの適切だと思う方法を指定することができます。

キャッシュの微調整をして、違うジョブ間や違うブランチ間などでキャッシュするように定義することができます。

cache:key変数で predefined variables のどれでも利用できます。

プロジェクト間ではkeyは default がデフォルトです。その為、GitLab 9.0からはデフォルトでパイプライン間やジョブ間で全てのものが共有されます。


サンプル設定例

ジョブ毎にキャッシュを共有する設定:

cache:
  key: "$CI_JOB_NAME"
  untracked: true

ブランチ毎にキャッシュする設定:

cache:
  key: "$CI_COMMIT_REF_NAME"
  untracked: true

ジョブ毎でブランチ毎にキャッシュする設定:

cache:
  key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME"
  untracked: true

ブランチ毎でステージ毎にキャッシュする設定:

cache:
  key: "$CI_JOB_STAGE/$CI_COMMIT_REF_NAME"
  untracked: true

Windows Batch を利用する場合、 $% に変換する必要があります:

cache:
  key: "%CI_JOB_STAGE%/%CI_COMMIT_REF_NAME%"
  untracked: true

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

cache:
  key: "$env:CI_JOB_STAGE/$env:CI_COMMIT_REF_NAME"
  untracked: true

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 を使用してダウンロード手順をスキップできます。

Jobs

.gitlab-ci.yml では無限にジョブを定義できます。各ジョブには、上述のキーワードに一致しない一意な名前が必要です。ジョブは、挙動を定義づけるパラメータのリストによって定義されます。

job_name:
  script:
    - rake spec
    - coverage
  stage: test
  only:
    - master
  except:
    - develop
  tags:
    - ruby
    - postgres
  allow_failure: true
キーワード 必須 詳細
script はい Runnerで実行されるシェルスクリプトを定義
image いいえ docker イメージを使う、Using Docker Imagesを参照
services いいえ docker servicesを使う、Using Docker Imagesを参照
stage いいえ ジョブのステージを定義(デフォルト: test)
type いいえ stageの別名
variables いいえ ジョブレベルのジョブ変数を定義
only いいえ どのgit refでジョブを作るかどうかのリストを定義
except いいえ どのgit refでジョブを作らないかどうかのリストを定義
tags いいえ どのタグでRunnerを使うかどうかのリストを定義
allow_failure いいえ ジョブの失敗を許容 失敗したジョブはコミットの状態に寄与しません
when いいえ どういう時にジョブを実行するかどうかを定義。on_success(成功) 、 on_failure(失敗)、 always(常時) または manual(手動)
dependencies いいえ 依存しているその他のジョブを定義、そのジョブ間で成果物を受け渡すことが可能
artifacts いいえ job artifactsのリストを定義
cache いいえ サブ実行の間にキャッシュされるファイルのリストを定義
before_script いいえ ジョブの実行前に実行する一連のコマンドを上書き
after_script no Override a set of commands that are executed after job
environment いいえ ジョブによりデプロイする先の環境名を定義
coverage いいえ 与えられたジョブのコードカバレッジ設定を定義
retry いいえ 実行失敗時に自動的に何回再実行するかの回数を定義

script

script は Runner で実行されるシェルスクリプトです。例えば:

job:
  script: "bundle exec rspec"

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

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

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

stage

stage を定義することによりジョブを別々のステージにグループ化する。同じ stage のジョブは 並列 に実行されます。stage の使い方についての詳細は、stages を確認してください。

only and except (simplified)

onlyexcept は、ジョブを実行するタイミングを規定する2つのパラメーターです:

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

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

  • onlyexcept は同時に適用されます。ジョブ定義で onlyexcept の両方が定義されている場合は、onlyexcept の両方で ref がフィルターされます。
  • only and except で正規表現が利用できます。
  • onlyexcept で フォークのジョブをフィルターするリポジトリパスを指定することができます。

さらに、onlyexcept では以下の特殊キーワードを使えます:

詳細
branches ブランチがプッシュされたとき
tags タグがプッシュされたとき
api 次のパイプラインAPI(トリガーAPIじゃなく) がパイプラインに呼び出されたとき
external GitLab以外のCI サービスが使われたとき
pipelines マルチプロジェクト用トリガー、CI_JOB_TOKEN付きでAPIを使って作成されたとき
pushes ユーザーが git push でパイプラインを呼び出したとき
schedules スケジュールscheduled pipelinesによるとき
triggers トリガーToken を使ってパイプラインが作成されたとき
web GitLab UI (under your project's Pipelines) の Run pipeline ボタンを押して、パイプラインが作成されたとき

以下の例は、 issue- という refs が付いているときにのみ job が実行されて、全てのブランチはスキップされます。

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

この例は、refs にタグ付けされたとき、またはAPI トリガー経由でビルドが呼び出されたり、 Pipeline Schedule でスケジュールされたときにジョブが実行されます:

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

リポジトリーパスでは、フォークされたものではなく親リポジトリに対してのみジョブを実行することができます:

job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce

上のサンプルでは、master ではなく gitlab-org/gitlab-ce の全てのブランチで job が実行されます

only and except (complex)

GitLab 10.0 で導入されました

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

GitLab 10.0から、より複雑な only/except ジョブポリシーを設定することができるようになります。

GitLabではシンプルともっと複雑な設定をサポートするようになりました。配列だったり、ハッシュ設定スキームを利用することが可能です。

今は2つのキーが利用できます:refskubernetesです。Refs 設定方法は、シンプルな
only/except 設定と同じですが、kubernetes では、active キーワードだけとります。

以下の例を見てください。ジョブは、パイプラインがスケジュールで実行されたとき、またはmasterブランチで動いたときで、kubernetes サービスがプロジェクトでアクティブの時ににもジョブが生成されます。

job:
  only:
    refs:
      - master
      - schedules
    kubernetes: active

Job variables

variables を使ってジョブのレベルでジョブ変数を定義することができます。基本的にglobal-level equivalent と同じ挙動をしますが、特定のジョブでのみ利用される変数になります。

ジョブレベルの variables キーワードは、グローバル YAML ジョブ変数や予約済み変数を上書きします。グローバル定義変数をオフにしたい場合は、空のハッシュを定義する:

job_name:
  variables: {}

ジョブ変数の優先度については、 variables documentation で定義されています。

tags

tag では、このプロジェクトで実行する全ての Runner から特定の Runner を選択します。

Runner を登録するときに、その Runner 毎に ruby とか postgresdevelopment といったタグを付けることができます。

tags により Runner がジョブを実行するか指定のタグを使って割りあてることができます:

job:
  tags:
    - ruby
    - postgres

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

allow_failure

allow_failure が設定されている場合、CI ツールの残り部分で影響を与えない時には失敗しても継続することを許可します。ジョブ実行が失敗していてもコミット状態には影響しません。

allow_failure を有効にした状態でジョブが失敗すると、どの状態や目的でもパイプラインは正常/緑色になりますが、マージ要求またはコミットまたはジョブページには「CIビルドが警告付きで渡されました」というメッセージが表示されます。ジョブの失敗を許可するために利用されますが、失敗した事に対する手動での対応は、どこかの時点で実施しなければなりません。

以下の例では、 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 - 直前のステージが全て成功した場合にのみジョブが実行されます。これはデフォルトの挙動です。
  2. on_failure - 直前のステージが失敗したときにのみジョブを実行します。
  3. always - 直前のステージが失敗したかどうかにかかわらずジョブを実行します。
  4. manual - ジョブを手動で実行します(GitLab 8.10で追加されました)。以下の manual actions を参照してください。

For example:

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. cleanup_build_jobbuild_job が失敗したときにのみ実行。
  2. cleanup_job を パイプラインの最後のステップとして、失敗したかどうかにかかわらず常に実行します。
  3. deploy_job を GitLab's UI から手動実行することができるようにします。

Manual actions

GitLab 8.10 で導入されました
手動操作の禁止は、GitLab 9.0 で導入されました。
実行の保護は、GitLab 9.2 で導入されました

手動アクションはジョブの特殊な形なので自動的には実行されません:このアクションは、ユーザーが明示的に動かす必要があります。手動アクションは、パイプライン、ビルド、エンバイロンメント、およびデプロイビューから動かすことができます。

手動アクションの使い方の例としてプロダクトへのデプロイがあります。

詳しくは、environments documentation を参照してください。

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

パイプラインがブロックされていて、パイプラインが成功したときにのみマージされる設定の場合、マージはされません。ブロックされているパイプラインは、manual という特殊な状態になっています。

手動アクションはブロックされないのが既定の動作です。手動アクションをブロックしたい場合は、.gitlab-ci.yml のジョブ定義で allow_failure: false を追加する必要があります。

手動アクションのオプション指定は、 allow_failure: true がデフォルトです。

オプション指定の手動アクションのステータスは、パイプライン通してステータスに影響しません

**手動アクションでは書き込み動作とされるため、ユーザーがアクションの操作をしたときに保護ブランチのパーミッションが利用されます。言い換えると、手動アクションが割り当てられるパイプラインは、ユーザーがマージできるブランチで動かす必要があります。

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 keyword を使って、次のようにも書けます。

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 を指し示す、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 環境へ review_app のジョブでデプロイし、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 と同じにする必要があります。

dynamic environments

注意:
- Introduced GitLab 8.12 と GitLab Runner 1.6 で導入されました。
- The $CI_ENVIRONMENT_SLUGintroduced GitLab 8.15 で導入されました。
- nameurl パラメーターは、定義されているCI 変数を何でも利用できるので、.gitlab-ci.ymlの既定のものや、秘密変数などのvariables をとることができます。しかし、script 配下の変数だけは利用できません。

For example:

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 を見られます。

artifacts

注意:
- GitLab Runner v0.7.0 からWindowsプラットフォーム以外で導入。
- GitLab Runner v.1.0.0 からWindowsをサポートしました。
- GitLab 9.2 以前は キャッシュは成果物の生成の後に戻っていました。
- GitLab 9.2 から、キャッシュは成果物の生成の前に戻ります。
- 今の全てのRunnerでサポートしている訳ではありません。
- artifacts ジョブは、デフォルトで正常なジョブに対してのみ収集されます。

artifacts というのは、ジョブが成功した後に成果物やディレクトリをその後のジョブ上で利用する為に使います。プロジェクトのワークスペース内のパスを指定することができます。全く違うジョブで生成ファイルをやりとりする場合は、 dependencies を見てください。次に幾つかサンプルを例示します。

binaries.config の全てのファイルを送信:

artifacts:
  paths:
  - binaries/
  - .config

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

artifacts:
  untracked: true

binaries にあるファイルと Git の未追跡ファイルを送信:

artifacts:
  untracked: true
  paths:
  - binaries/

artifact を通るのを無効にするには、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

成果物はジョブが成功して生成されたあと GitLabに送られて、GitLab UI のダウンロードから利用できるようになります。

artifacts:name

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

name は、成果物のアーカイブ名を指定するディレクティブです。その為、一意名前を設定するようにしておくとGitLabからダウンロードするときに便利です。artifacts:name に取り得る変数は、predefined variables のどれでも利用できます。
artifacts は、ダウンロード時にデフォルトでは artifacts.zipになります。


サンプル設定例

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

job:
  artifacts:
    name: "$CI_JOB_NAME"

Gitで追跡されていないファイルだけが含まれた、今のブランチやタグ名をアーカイブ名として作成:

job:
   artifacts:
     name: "$CI_COMMIT_REF_NAME"
     untracked: true

Gitで追跡されていないファイルだけ含まれた、今のジョブ名とブランチやタグ名をアーカイブ名として作成:

job:
  artifacts:
    name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}"
    untracked: true

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

job:
  artifacts:
    name: "${CI_JOB_STAGE}_${CI_COMMIT_REF_NAME}"
    untracked: true

Windows Batch を利用する場合、 $% に変換する必要があります:

job:
  artifacts:
    name: "%CI_JOB_STAGE%_%CI_COMMIT_REF_NAME%"
    untracked: true

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

job:
  artifacts:
    name: "$env:CI_JOB_STAGE_$env:CI_COMMIT_REF_NAME"
    untracked: true

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

artifacts:expire_in を使って、指定の時間を経過したらアップロードした成果物を削除することができます。通常は、GitLabに残り続けます。expire_in を使ってアップロード後、GitLabに保存し始めてから削除されるまでにどれぐらいの期間生成ファイルを保存しておくか指定することができます。

ジョブのページで 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

dependencies

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

この機能は、 artifacts と組み合わせます。成果物を別のジョブに渡すために定義します。

通常、一つ前のステージ stagesartifacts を受け取れます。

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


次の例では、build:osxbuild:linux の成果物をジョブで定義しています。test:osx を実行するときに build:osx のビルドで成果物をダウンロード、展開します。

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

before_script and after_script

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

coverage

注意:
- Introduced GitLab 8.17 で導入されました。

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

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

シンプルな例

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

retry

注意:
- Introduced GitLab 9.5 で導入されました。

retry は、失敗時にジョブを何回再試行するかを決めるものです。

ジョブが失敗して、retry が設定されていたら、retry キーワードで指定した回数だけ再度実行します。

retry が2回に設定されていた状態で、ジョブが2回目(1回目の再試行)で成功でしたときには、それ以上の再試行はされません。retry 回数は正の整数で0よりも大きい必要がありますが、2かそれ以下の値である必要があります(2の場合は全部で最大3回の試行になります)

シンプルな例

test:
  script: rspec
  retry: 2

Git Strategy

GitLab 8.9 で実験的機能として導入されました。将来のバージョンで変更削除される可能性があります。GIT_STRATEGY=none を指定するためには、 GitLab Runner v1.7以上が必要です。

GIT_STRATEGY により最新のアプリケーションコードを取得する振る舞いを指定することができます。これは variables セクションのグローバル指定や個別のジョブ上の variables セクションで指定することができます。未指定の場合、プロジェクト設定のデフォルトが利用されます。

clonefetchnone の3種類の値をとります。

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

variables:
  GIT_STRATEGY: clone

fetch が プロジェクトのワークスペースを再利用するので(ない場合は clone を実行)一番早くなります。git cleanを使って最近のジョブでの変更をリセットし、git fetch が最新のジョブでのコミットを取得するために使われます。

variables:
  GIT_STRATEGY: fetch

none もプロジェクトのワークスペースを再利用しますが、Git の操作を全て(GitLab Runnerのプレクローンスクリプトがあったとしても)スキップします。成果物上(例えばdeploy)でのみ動作するジョブに最適です。Gitリポジトリーがあったとしても、古くなっていることは間違いないのでプロジェクトのキャッシュや成果物からファイルを持ってくることが一番信頼できます。

variables:
  GIT_STRATEGY: none

Git Checkout

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

GIT_CHECKOUT 設定は、GIT_STRATEGYclonefetch に指定していて、git checkout を指定するかどうかを決めるために使います。指定しない場合は、true です。GIT_STRATEGY のようにグローバル variables セクションや個別のジョブの variables セクションで設定できます。

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

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

true に設定されていると、clonefetch での挙動は、RunnerがCI パイプラインに関連したリビジョンをワーキングコピーとしてチェックアウトします。

variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: false
script:
  - git checkout master
  - git merge $CI_BUILD_REF_NAME

Git Submodule Strategy

GitLab Runner v1.10 以上が必要。

GIT_SUBMODULE_STRATEGY 変数は、 Git Submodule も含めてビルド前にソースコードをとってくる挙動を指定するものです。GIT_STRATEGY のようにグローバル variables セクションや個別のジョブの variables セクションで設定できます。

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

  • none を指定すると、プロジェクトのソースコード内の サブモジュールは含みません。pre-v.10 までの挙動と同じで、デフォルトです。

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

    git submodule sync
    git submodule update --init
    
  • recursive にすると、submodule の全て(Submodule の Submodule)を含みます。以下の操作と同じです:

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

このオプションを正しく動かすために注意することがあります。Submoduleは、 (.gitmodules) で次のどちらかの設定されている必要があります:

  • 公開アクセスできるリポジトリが HTTP(S) のURLで公開されている
  • 同じ GitLab サーバー上にある他のリポジトリの連携パスである 。詳細は、Git submodules のドキュメントを確認

Job stages attempts

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

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

変数名 詳細
GET_SOURCES_ATTEMPTS 実行しているジョブでソースコードを取得する試行回数
ARTIFACT_DOWNLOAD_ATTEMPTS 実行しているジョブで成果物をダウンロードする試行回数
RESTORE_CACHE_ATTEMPTS 実行しているジョブでキャッシュのリストア試行回数

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

例:

variables:
  GET_SOURCES_ATTEMPTS: 3

グローバル variables セクションや個別のジョブの variables セクションで設定できます。

Shallow cloning

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

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

注意:
深さを 1 にして、ジョブのリトライが発生すると、ジョブが失敗する可能性があります。

といういうのも、ブランチ名などの ref をベースにfetch や clone を行います。Runner は特定のコミットSHA を特定して clone することはできません。キュー内に複数のジョブがある場合や古いジョブがリトライした場合、テストが必要な対象のコミットは複製されたGit履歴内にある必要があります。GIT_DEPTH で値を小さすぎると、これらの古いコミットを実行することができなくなります。この場合、ジョブのログに unresolved reference と表示されます。GIT_DEPTHをより高い値に変更し直すべきです。

GIT_DEPTH を設定すると Gitのヒストリーの一部だけが閲覧されるため、git describe のジョブがうまく動かない可能性があります。

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

variables:
  GIT_DEPTH: "3"

Hidden keys (jobs)

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を使って、テンプレートとして隠しキーに変換することができます。

Special YAML features

アンカー (&)、エイリアス (*) とマップのマージ (<<) といった YAML の特殊機能を使うこともできます。これを使うと、.gitlab-ci.yml の複雑な記述を大幅に減らすることができます。

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

Anchors

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           # Merge the contents of the 'job_definition' alias
  script:
    - test1 project

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

& で (job_definition) という名前のアンカーを設定し、<< で示したハッシュをここに結合します。* は、アンカー名(再度 job_definition) を指定しています。展開されると以下のようになります:

.job_template:
  image: ruby:2.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コールで呼び出されます。

詳しくは、Read more in the triggers documentation. を参照してください。

pages

pages は、GitLab でウェブサイトの静的コンテンツを生成アップロードするための特殊なジョブです。文法も特別なので以下の2つの要件を満たす必要があります。

  1. すべての静的コンテンツは、public/ ディレクトリーの下に配置する必要があります。
  2. 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 を見てください。

Validate the .gitlab-ci.yml

GitLab CI インスタンス毎に組み込みデバッグツールとして Lint を使っています。
GitLab インスタンスの配下に /ci/lint のリンクがあります。

Skipping jobs

コミットメッセージに [ci skip][skip ci] (大文字小文字)が入っていると、そのコミットではジョブの実行をスキップします。

Examples

様々なプログラム言語でのGitLab CIのサンプルは、以下の examples README を見てください。

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