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

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リファレンスに加えてクイックスタートガイドも収蔵しております。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/15176/97a9ee4b-0fbd-d02e-ed4b-8aa1aa45b9db.png" width=30%>
＜宣伝終了＞

----

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

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

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

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

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

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

- [GitLab Runner](https://docs.gitlab.com/runner/)で何を動かすか。
- 特定の条件になったときにどうするかを指定します。例えば、プロセスが成功または失敗した場合です。

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

- [GitLab CI/CD 変数](../variables/README.md)、パイプラインが実行される環境の変数について。
- [GitLab Runner 詳細設定](https://docs.gitlab.com/runner/configuration/advanced-configuration.html), GitLab Runnerの設定について。

パイプラインの設定方法についての様々なサンプルについては以下を参照してください:
- GitLab CI/CDの簡単な紹介については、[quick start guide](../quick_start/README.md)
- サンプル集については、 [GitLab CI/CD Examples](../examples/README.md)
- 企業での大規模な `.gitlab-ci.yml` 利用の場合には、[`.gitlab-ci.yml` file for `gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab-ci.yml)

NOTE: *注意:*
[ミラーリングリポジトリでGitLabの外から取得](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter)の場合にはそのプロジェクト内でパイプライントリガーを有効にする必要がある場合があります。
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**

# イントロダクション

パイプライン設定はジョブから始まります。ジョブは、`.gitlab-ci.yml`ファイルの最も基本的な要素です。

ジョブでは以下のような事を定義します:

- どのような状態の時に実行するか条件を定義します。
- 任意の名前を指定できる最上位の要素で、最低限[`script`](#script)が含まれている。
- 定義できる数に制限はありません。

例:

```yaml
job1:
  script: "execute-script-for-job1"

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

この例は、2つのジョブを実行し、それぞれ別のコマンドを別のジョブで実行している最も簡単なのCI/CD設定です。
当然ですが、レポジトリ内で直接(`./configure;make;make install`)といったコマンドを実行すること
もできますし、 (`test.sh`)といったスクリプトを実行することもできます。

ジョブ定義は、[Runners](../runners/README.md) に渡されて、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`](#script)                                | Runnerで実行されるシェルスクリプト                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [`image`](#image)                                  | 利用するDockerコンテナイメージ。次の指定も可能: `image:name` と `image:entrypoint`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [`services`](#services)                            | サービスで利用するDockerコンテナイメージ。次の指定も可能:: `services:name`, `services:alias`, `services:entrypoint` と `services:command`.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [`before_script`](#before_script-and-after_script) | ジョブを実行する前に動かすコマンドを設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [`after_script`](#before_script-and-after_script)  | ジョブを実行した後に動かすコマンドを設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [`stages`](#stages)                                | パイプラインのステージリストを定義。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [`stage`](#stage)                                  | ジョブのステージ名を定義 (デフォルト: `test`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`only`](#onlyexcept-basic)                        | ジョブが実行される条件を設定。次の指定も可能: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced).                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [`except`](#onlyexcept-basic)                      | ジョブが実行されない条件を設定。次の指定も可能: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced).                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [`rules`](#rules)                                  | ジョブの指定された属性を評価、決定して、ジョブを作成するかどうかを決めるための条件リスト。`only`/`except`と同時には利用できません。                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [`tags`](#tags)                                    | Runnerに設定されているタグを元に特定のRunnerで実行。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [`allow_failure`](#allow_failure)                  | ジョブの失敗を許容する。失敗したジョブでは、コミットステータスが変更されない。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [`when`](#when)                                    | ジョブを実行するタイミング。次の指定も可能: `when:manual`と`when:delayed`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [`environment`](#environment)                      | ジョブをデプロイする環境名。次の指定も可能: `environment:name`, `environment:url`, `environment:on_stop`と`environment:action`.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [`cache`](#cache)                                  | ジョブ間で共有するキャッシュのファイルリスト。次の指定も可能: `cache:paths`, `cache:key`, `cache:untracked`と`cache:policy`.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`artifacts`](#artifacts)                          | ジョブが成功したときに、ジョブに紐付ける成果物のファイルリストとディレクトリ。次の指定も可能: `artifacts:paths`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, `artifacts:reports`, and `artifacts:reports:junit`.<br><br>In GitLab [Enterprise Edition](https://about.gitlab.com/pricing/), 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`](#dependencies)                    | 複数のジョブの依存関係を設定する。そのジョブ間で成果物を渡すことができる。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`coverage`](#coverage)                            | ジョブのテストのカバレッジ抽出設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [`retry`](#retry)                                  | 失敗時に、ジョブを自動的にいつ、何回、リトライするかどうかを設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [`timeout`](#timeout)                              | プロジェクト全体の設定をよりも優先度の高い、ジョブ毎の個別タイムアウト設定を定義                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [`parallel`](#parallel)                            | ジョブを実行するインスタンスを並列で実行する数を設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [`trigger`](#trigger)                              | 連携した下位のパイプラインの呼び出し先を設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [`include`](#include)                              | 外部のYAMLファイルを読み込んでジョブに追加する設定。次の指定も可能: `include:local`, `include:file`, `include:template`と `include:remote`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [`extends`](#extends)                              | 他の場所に記述したジョブの内容を読み込んで拡張する設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`pages`](#pages)                                  | GitLabページを使ってジョブの結果をアップロードする設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [`variables`](#variables)                          | ジョブレベル毎にジョブの変数を設定。                                                                                                                                                                                                                                                  ｜
| [`interruptible`](#interruptible)                  | 後から新しいパイプラインが実行されたときにジョブをキャンセルできるかどうかを設定。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`resource_group`](#resource_group)                | ジョブの同時実行制限                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

NOTE: **注意:**
`types`と`type`パラメーターは、[deprecated](#deprecated-parameters)となっています。

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

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

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

- [`image`](#image)
- [`services`](#services)
- [`before_script`](#before_script-and-after_script)
- [`after_script`](#before_script-and-after_script)
- [`tags`](#tags)
- [`cache`](#cache)
- [`artifacts`](#artifacts)
- [`retry`](#retry)
- [`timeout`](#timeout)
- [`interruptible`](#interruptible)

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

```yaml
default:
  image: ruby:2.5

rspec:
  script: bundle exec rspec

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

### `継承`

> GitLab 12.9.で[導入](https://gitlab.com/gitlab-org/gitlab/issues/207484)されました。

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

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

- `default: true` or `default: false`
- `variables: true` or `variables: false`

`default:`パラメータや`variables:`のサブセットのみを継承するには、継承したいもののみ
指定して、継承したくないものはリストアップ**しない**でください。
次のいずれかの形式を使用します。

```yaml
inherit:
  default: [parameter1, parameter2]
  variables: [VARIABLE1, VARIABLE2]
```

または:

```yaml
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`変数

```yaml
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で実行されます。例えば：

```yaml
job:
  script: "bundle exec rspec"
```

[YAMLのスクリプト用のアンカー](#yaml-anchors-for-script)も利用できます。

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

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

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

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

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

### `image`

ジョブを実行するベースとなる[Docker image](../docker/using_docker_images.md#what-is-an-image)を指定します。

詳細:

- 簡単な定義サンプルは、[Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) をみてください。
- 詳細は、[Docker integration](../docker/README.md) のドキュメントを参照してください。

#### `image:name`

[dockerコンテナを起動する時の拡張オプション](../docker/using_docker_images.md#extended-docker-configuration-options) 。

詳細な説明については、[Available settings for `image`](../docker/using_docker_images.md#available-settings-for-image)を参照

#### `image:entrypoint`

[dockerコンテナを起動する時の拡張オプション](../docker/using_docker_images.md#extended-docker-configuration-options) 。

詳細な説明については、[Available settings for `image`](../docker/using_docker_images.md#available-settings-for-image)を参照

### `services`

[サービス用のDocker image](../docker/using_docker_images.md#what-is-a-service)を指定するには、[`image`](#image)で事前にベースイメージ
と関連付けておきます。

詳細:

- 簡単な設定サンプルについては、[Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml)を見てください。
- 詳細については、[Docker integration](../docker/README.md) を参照してください。
- サービスのサンプルについては、[GitLab CI/CD Services](../services/README.md)を見てください。

#### `services:name`

[dockerコンテナを起動する時の拡張オプション](../docker/using_docker_images.md#extended-docker-configuration-options) 。

詳細な情報については、[`services`に追加できる設定](../docker/using_docker_images.md#available-settings-for-services)をみてください。

#### `services:alias`

[dockerコンテナを起動する時の拡張オプション](../docker/using_docker_images.md#extended-docker-configuration-options) 。

詳細な情報については、[`services`に追加できる設定](../docker/using_docker_images.md#available-settings-for-services)をみてください。

#### `services:entrypoint`

[dockerコンテナを起動する時の拡張オプション](../docker/using_docker_images.md#extended-docker-configuration-options) 。

詳細な情報については、[`services`に追加できる設定](../docker/using_docker_images.md#available-settings-for-services)をみてください。

#### `services:command`

[dockerコンテナを起動する時の拡張オプション](../docker/using_docker_images.md#extended-docker-configuration-options) 。

詳細な情報については、[`services`に追加できる設定](../docker/using_docker_images.md#available-settings-for-services)をみてください。

### `before_script`と`after_script`

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

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

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

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

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

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

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

```yaml
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のスクリプト用のアンカー](#yaml-anchors-for-script)も利用できます。

### `stages`

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

`stages`には複数のパイプラインステージを定義します。`stages`に指定した要素の順番で
ジョブは順番に実行されます:

1. 同じステージのジョブは、並列に実行されます。
1. 前のステージのジョブが完全に実行に成功してから次のステージのジョブが実行されます。

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

```yaml
stages:
  - build
  - test
  - deploy
```

1. 最初に`build`の全てのジョブが並列に実行されます。
1. `build`のジョブが全て成功したら、`test`ジョブが並列に実行されます。
1. `test`のジョブが全て成功したら、`deploy`ジョブが並列に実行されます。
1. `deploy`のジョブが全て成功したら、このコミットは`success`とマークされます。
1. その前のジョブのいずれが失敗しても、コミットコマンドは、`failed`とマークされて、
   次のどのステージのジョブも実行されません。

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

1. `.gitlab-ci.yml`に`stages`が定義されていない場合、`build`と`test`、
  `deploy`がデフォルトのジョブのステージです。
2. ジョブが`stage`が定義されてない場合、ジョブは`test`ステージに割り当てられます。

#### `.pre`と`.post`

> GitLab 12.4で[導入](https://gitlab.com/gitlab-org/gitlab/issues/31441)されました。

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

- `.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`の位置関係は変えることはできません。
例えば、以下の例は同じ設定になります:

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

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

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

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

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

  ```yml
  stages:
    - a
    - b
  ```

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

### `stage`

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

```yaml
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](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section)を見てください)

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

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

### `only`/`except` (基本)

NOTE: **注意:**
現在、[`rules`](#rules)構文を使ってジョブの実行ポリシーを設定する方法をお勧めしています。
`only`と`except`は、 [非推奨の候補](https://gitlab.com/gitlab-org/gitlab/issues/27449)
となっているので、今後削除される可能性があります。

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

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

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

- `only`と`except`は包含的に使えます。`only`と`except`がジョブ内で両方定義
   されていた場合、`only`と`except`の両方で絞り込めます。
- `only`と`except`には正規表現 ([supported regexp syntax](#supported-onlyexcept-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](../pipelines/schedules.md)用. |
| `triggers`       | パイプラインがトリガートークンを使って呼び出された場合 |
| `web`            | GitLab UIの**Run pipeline**ボタン(プロジェクトの**パイプライン**)を使ってパイプラインが呼び出された場合 |
| `merge_requests` | マージリクエストが作成、更新されたとき ([pipelines for merge requests](../merge_request_pipelines/index.md)参照) |
| `external_pull_requests`| GitHub上で外部プルリクエストが作成または更新された場合 ([Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)を参照) |
| `chat`          | [GitLab ChatOps](../chatops/README.md) コマンドでジョブが作成されたとき |

以下の例では、`job`は、`issue-`がリファレンスついている場合にのみ実行され、
ブランチでは全てスキップされます:

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

デフォルトでは、大文字小文字を区別してマッチします。`i`フラグをつかって、
`/pattern/i`のようにすれば、大文字小文字の区別はありません:

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

この例では、`job`はタグのリファレンスがついている時にのみ実行され、また、
APIトリガーか[Pipeline Schedule](../pipelines/schedules.md)で呼び出された時にのみ実行されます:

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

リポジトリパスも使うことができ、親リポジトリでのみ実行し、フォークされた
パスの場合には実行しません:

```yaml
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`がない場合のデフォルトルールはありません。

以下の例は、

```yaml
job:
  script: echo 'test'
```

以下と同じです:

```yaml
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](https://github.com/google/re2/wiki/Syntax)に置き換え始めました。

つまり、[Ruby Regexp](https://ruby-doc.org/core/Regexp.html)で利用できる機能の全てが利用できるわけで
はなくなります。[RE2](https://github.com/google/re2/wiki/Syntax)は演算の負荷を下げるために限定した
機能しか提供していません。その為、GitLab 11.9.4では、いくつかの機能が使えなくなります。
例えば、否定先読みです。

GitLabのバージョン11.9.7から、12.0までは、安全ではない正規表現をユーザーが利用できるように管理者が
オンオフできるフラグを提供します。この機能は、新しい記述方法を後方互換のために用意し、ユーザーが
新しい記述方法に徐々に移行することができるようにします。

```ruby
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](../../user/project/pipelines/schedules.md) **または**`master`で実行されている.
- `variables`キーワードがマッチしている。
- プロジェクトで`kubernetes`サービスが有効になっている。

```yaml
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`に変更があった。

```yaml
test:
  script: npm run test
  except:
    refs:
      - master
    changes:
      - "README.md"
```

#### `only:refs`/`except:refs`

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

`refs`では、[simplified only/except configuration](#onlyexcept-basic)と同じような値を
設定できます。

以下の例では、`deploy`ジョブは、パイプラインが[scheduled](../pipelines/schedules.md)に定義されているか、または
`master`の時にしか実行されません。

```yaml
deploy:
  only:
    refs:
      - master
      - schedules
```

#### `only:kubernetes`/`except:kubernetes`

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

`kubernetes`パラメーターは、`active`の値しかとりません。

以下の例では、Kubernetesサービスが有効な時にのみ `deploy`ジョブが動きます:

```yaml
deploy:
  only:
    kubernetes: active
```

#### `only:variables`/`except:variables`

> `variables`ポリシーは、GitLab 10.7で導入されました。

`variables`キーワードを使うと変数で定義された値を使うことができます。つまり、
予め定義されている変数 / プロジェクト / グループ / 環境内ので変数をGitLabが評価して、
ジョブを実行するか否かを決定することができます。

変数の評価を使う例は以下の通りです:

```yaml
deploy:
  script: cap staging deploy
  only:
    refs:
      - branches
    variables:
      - $RELEASE == "staging"
      - $STAGING
```

その他の利用方法としては、コミットに特定のメッセージが入っている場合にジョブ実行を
避けるといったことができます。

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

変数の評価について詳しく知りたい場合は、[variables expressions](../variables/README.md#environment-variables-expressions)を参照してください。

#### `only:changes`/`except:changes`

> `changes`ポリシーは、GitLab 11.4の[introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/19232)で導入されました。

`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イベントがない場合、例えば
[上の三つ以外のソース](../variables/predefined_variables.md#variables-reference)
において、`changes`では、与えられたファイルが新しいのか古いのか見分けがつかないので、
常にtrueを返します。

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

```yaml
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`を [パイプラインが成功したときにのみマージリクエストを許可する](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds)と一緒に使った場合、
[`only:merge_requests`も同時に利用](#using-onlychanges-with-pipelines-for-merge-requests)しないと、
望まない挙動をする可能性があります。

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

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

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

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

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

CAUTION: **警告:**
[マージリクエストのためのパイプラインを*持たない*新しいブランチやタグでこの機能を使用する際](#using-onlychanges-without-pipelines-for-merge-requests)に注意すべき点がいくつかあります。

CAUTION: **警告:**
[スケジュールされたパイプラインでこの機能を使用する際](#using-onlychanges-with-scheduled-pipelines)
に注意すべき点がいくつかあります。

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

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

ソースブランチの正しいベースSHAを推測するには、このキーワードを`only: [merge_requests]`と
組み合わせることを推奨します。この方法だとファイルの差分がそれ以降のコミットから
正しく計算され、その為にマージ要求のすべての変更がパイプラインで適切にテストされる
ようになります。

例:

```yaml
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`ジョブを起動します。

[マージリクエストのパイプライン](../merge_request_pipelines/index.md)が、`only: [change]`
とのみ組み合わせられ、`only: [merge_requests]`が省略された場合、望ましくない
動作をする可能性があります。

例:

```yaml
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`を使う

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

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

##### Using `only:changes` with scheduled pipelines

`only:changes` always evaluates as "true" in [Scheduled pipelines](../pipelines/schedules.md).
All files are considered to have "changed" when a scheduled pipeline
runs.

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

### `rules`

> GitLab 12.3で[導入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29011)されました。

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

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

- [`if`](#rulesif) ([`only:variables`](#onlyvariablesexceptvariables)に近いものです)
- [`changes`](#ruleschanges) ([`only:changes`](#onlychangesexceptchanges)と同じです)
- [`exists`](#rulesexists)

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

```yaml
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`とは少し違っていて、評価式が配列ではなくて単一の文字列の
式のみを受け付けるようになっています。評価される式のセットは、
[変数のマッチング構文](./variables/README.md#supported-syntax)と`&&`や`||`を使って
1つの式に結合して使用する必要があります。

例:

```yaml
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`](#onlychangesexceptchanges)で詳細を確認してください。

例:

```yaml
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で[導入](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16574)されました。

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

例:

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

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

例:

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

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

#### `rules:allow_failure`

> GitLab 12.8で[導入](https://gitlab.com/gitlab-org/gitlab/issues/30235)されました。

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

```yaml
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つのパイプラインが生成される可能性があります:

- ブランチにコミットがプッシュされたことによるパイプラインが一つ
- [マージリクエストでパイプラインから"分離"](../merge_request_pipelines/index.md)されたものがもう一つ

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

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

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

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

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

  ```yaml
  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"`である場合にジョブを手動実行します。
- その為、このジョブはパイプライン内には組み込まれません。

```yaml
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`と値が必要なので、ルール指定も同様になります。例えば、
いかようになります:

```yaml
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を投稿](https://gitlab.com/gitlab-org/gitlab/issues).
してください。

### `workflow:rules`

> GitLab 12.5で[導入](https://gitlab.com/gitlab-org/gitlab/issues/29654)されました。

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

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

- [`if`](#rulesif): ルールを定義する。
- [`when`](#when): 取り得る値は`always`か`never`のみ。指定しない場合のデフォルト値は `always`。

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

```yaml
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に対してジョブを指定して実行することが
できるようになります:

```yaml
job:
  tags:
    - ruby
    - postgres
```

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

タグを指定するのは、異なったプラットフォームで違うジョブを実行するのに非常に適しています。
例えば、OS XのRunnerには、`osx`というタグをつけておき、WindowsのRunnerには、`windows`
というタグをつけてきます。次の例では、ジョブがそれぞれ別のプラットフォームで実行されます:

```yaml
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](#whenmanual) jobs using the
`when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs
default to false, *including* `when: manual` jobs.

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

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

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

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

例:

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

#### `when:manual`

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

手動実行は自動的には実行されない特別なタイプのジョブです。
このアクションは、ユーザーが明示的に開始する必要があります。手動実行の使い方の
一つは、本番環境へのデプロイでしょう。パイプラインやジョブ、環境、デプロイ画面から
手動実行することができます。詳しくは、[environments documentation](../environments.md#configuring-manual-deployments)を参照してください。

手動実行はオプションまたはブロックのどちらかを取ります。ブロッキングの場合は、
手動アクションはこれがで定義されている部分でパイプラインの実行をブロックします。
ブロックされている手動アクションは、誰かが _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:`](#rules), `allow_failure` defaults to `false`, including for manual jobs.

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

Manual actions are considered to be write actions, so permissions for
[protected branches](../../user/project/protected_branches.md) 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](#protecting-manual-jobs-premium) 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](../environments/protected_environments.md)
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:

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

1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
   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](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/21767)で導入されました。

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

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

- `10 seconds`
- `30 minutes`
- `1 hour`
- `1 day`
- `1 week`

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

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

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

```yaml
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](../environments.md) を見てください。

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

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

```yaml
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`](#variables) を
>   使用することができます。
>   しかし、`script`配下の変数だけは利用できません。

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

- letters(アルファベット文字)
- digits(数字)
- spaces(空白)
- `-`
- `_`
- `/`
- `$`
- `{`
- `}`

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

`environment`のキーワードの後の右側に直接名前を定義する以外にも、分割して値を設定することも可能です。
例えば、`environment`の下に `name` キーワードを使って、次のようにも書けます:

```yaml
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`](#variables) を使用することができます。
>   しかし、`script`配下の変数だけは利用できません。

これはオプションの値で、セット時にはGitLabの様々なところでボタンが表示され、
そのボタンを押すと、設定したURLに移動することができます。

次の例では、ジョブが成功したらマージリクエストボタンと`https://prod.example.com`のURLが
表示された、the environments/deploymentsページへのボタンが作成されます。

```yaml
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](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6669)で導入されました。
> - GitLab 8.14から、environment にストップアクションが定義されている場合、
>   関連したブランチが削除されるとGitLab が自動的に停止アクションを呼び出します。

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

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

#### `environment:action`

> GitLab 8.13の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6669)で導入されました。

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

例:

```yaml
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](#manual-actions) で動かすことが必要です。

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](../environments.md#automatically-stopping-an-environment).

NOTE: **Note:**
The above example overwrites global variables. If your stop environment job depends
on global variables, you can use [anchor variables](#yaml-anchors-for-variables) when setting the `GIT_STRATEGY`
to change it without overriding the global variables.

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

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

#### `environment:auto_stop_in`

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/20956) 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,

```yaml
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](../environments.md#environments-auto-stop)

#### `environment:kubernetes`

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27630) in GitLab 12.6.

The `kubernetes` block is used to configure deployments to a
[Kubernetes cluster](../../user/project/clusters/index.md) that is associated with your project.

For example:

```yaml
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](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).

For more information, see
[Available settings for `kubernetes`](../environments.md#configuring-kubernetes-deployments).

NOTE: **Note:**
Kubernetes configuration is not supported for Kubernetes clusters
that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters).
To follow progress on support for GitLab-managed clusters, see the
[relevant issue](https://gitlab.com/gitlab-org/gitlab/issues/38054).

#### 動的環境

> - GitLab 8.12 と GitLab Runner 1.6の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6323)で導入されました。
> - The `$CI_ENVIRONMENT_SLUG` はGitLab 8.15の[introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7983)で導入されました。
> - `name`と`url`パラメーターは、定義済みの任意のCI変数を何でも利用でき、定義済みの変数、
>   `.gitlab-ci.yml`の変数、シークレット変数などの[`variables`](../variables/README.md) を使用することが
>   できます。しかし、 `script` 配下の変数だけは利用できません。

例:

```yaml
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 から、キャッシュは[成果物](#artifacts)がリストアされる前にリストアされます。

TIP: **詳細に知りたい場合:**
キャッシュの動作について知りたい場合、オススメの設定方法を知りたい場合は、
[caching dependencies documentation](../caching/index.md)を見てください。

`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](https://en.wikipedia.org/wiki/Glob_(programming))
patterns and [`filepath.Match`](https://golang.org/pkg/path/filepath/#Match).

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

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

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

```yaml
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](../variables/README.md)のどれでも
利用でき、設定されていない場合は、GitLab 9.0から`default`が設定され、それによりデフォルト
で、全てのジョブとパイプライン間で全てのものが共有されます。

NOTE: **注意:**

`cache:key`の変数には`/`文字または、URIエンコードされた同等の`%2F`を使うことが
できません;同様に(`.`, `%2E`)のみの値も利用できません。

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

```yaml
cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - binaries/
```

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

```yaml
cache:
  key: "%CI_COMMIT_REF_SLUG%"
  paths:
    - binaries/
```

##### `cache:key:files`

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18986) 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`.

```yaml
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](https://gitlab.com/gitlab-org/gitlab/issues/18986) 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](../variables/README.md),
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`)

```yaml
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リポジトリ追跡対象外になっているファイルを
全てキャッシュします:

```yaml
rspec:
  script: test
  cache:
    untracked: true
```

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

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

#### `cache:policy`

> GitLab 9.4で導入されました。

ジョブのキャッシュのデフォルトの挙動は、実行開始時にファイルをダウンロードし、終了時に
アップロードします。これによりジョブによる作成されたすべての変更が将来の実行のために
保持される、`pull-push`キャッシュ・ポリシーとして知られています。

もし、ジョブがキャッシュファイルを置き換えないことが分かっている場合、ジョブの指定で、
`policy: pull`を指定するとアップロードをスキップすることができます。通常、前の段階で
随時更新されている通常のキャッシュジョブと組み合わせます:

```yaml
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で[サポート](https://docs.gitlab.com/runner/executors/#compatibility-chart)している訳ではありません。
> - artifacts ジョブは、デフォルトで正常なジョブに対してのみ収集されます。

`artifacts` というのは、ジョブが[成功、失敗、常時](#artifactswhen)の状態で終了した後に
成果物やディレクトリをその後のジョブ上で利用する為に使います。

成果物はジョブが終了した後にGitLabに送信され、GitLab UIからダウンロードできるようになります。

[成果物の詳細](../pipelines/job_artifacts.md).

#### `artifacts:paths`

プロジェクトのワークスペース内のパスを指定することができます。全く違うジョブで生成ファイルを
やりとりする場合は、[dependencies](#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](https://en.wikipedia.org/wiki/Glob_(programming))
patterns and [`filepath.Match`](https://golang.org/pkg/path/filepath/#Match).

To restrict which jobs a specific job will fetch artifacts from, see [dependencies](#dependencies).

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

```yaml
artifacts:
  paths:
  - binaries/
  - .config
```

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

```yaml
job:
  stage: build
  script: make build
  dependencies: []
```

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

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

```yaml
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`:

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

#### `artifacts:expose_as`

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/15018) in GitLab 12.5.

The `expose_as` keyword can be used to expose [job artifacts](../pipelines/job_artifacts.md)
in the [merge request](../../user/project/merge_requests/index.md) UI.

For example, to match a single file:

```yml
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:

```yml
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](../pipelines/job_artifacts.md#browsing-artifacts) 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](../../administration/pages/index.md) 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](https://docs.gitlab.com/ce/ci/variables/README.html) のどれでも利用できます。
 `artifacts`は、ダウンロード時にデフォルトでは`artifacts.zip`になります。

NOTE: **注意:**
ブランチ名にスラッシュが入っている場合(例 `feature/my-feature`)、正しくファイル名を
取り扱えるようにするために、`$CI_COMMIT_REF_NAME`ではなく`$CI_COMMIT_REF_SLUG`を
使うことをお勧めします。

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

```yaml
job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/
```

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

```yaml
job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/
```

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

```yaml
job:
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/
```

現在の[stage](#stages)の名前とブランチ名でアーカイブを作成:

```yaml
job:
  artifacts:
    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
    paths:
      - binaries/
```

---

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

```yaml
job:
  artifacts:
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
    paths:
      - binaries/
```

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

```yaml
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の未追跡ファイルを全て送信:

```yaml
artifacts:
  untracked: true
```

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

```yaml
artifacts:
  untracked: true
  paths:
  - binaries/
```

#### `artifacts:when`

> GitLab 8.9とGitLab Runner v1.3.0で導入されました

`artifacts:when`を使うと、ジョブが失敗したときや、そうでない時にもアップロード
することができます。

`artifacts:when`では、次の値のどれか一つを設定します。

1. `on_success` - ジョブが成功したときにのみアップロードします。これは通常の動作です。
1. `on_failure` - ジョブが失敗したときのみアップロードします。
1. `always` - ジョブのステータスにかかわらず、常にアップロードします。

ジョブが失敗したときにのみアップロード:

```yaml
job:
  artifacts:
    when: on_failure
```

#### `artifacts:expire_in`

> GitLab 8.9 と GitLab Runner v1.3.0で導入されました

`expire_in`を使うと、成果物がGitLabにアップロードされ保存されてから、
削除されるまでにどれぐらいの期間、保存しておくか有効期限を指定できます。
有効期限が設定されていない場合は、デフォルトでは
[インスタンスレベル](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration-core-only)で設定されます。
(通常は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週間後に期限切れ：

```yaml
job:
  artifacts:
    expire_in: 1 week
```

#### `artifacts:reports`

> GitLab 11.2の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390)で導入されました。GitLab Runner 11.2以上が必要です。

`reports`設定キーワードは、テストレポート、コードクオリティレポート、セキュリティーレポートをジョブから収集し、
GitLabのUI(マージリクエストやパイプラインビュー、セキュリティーダッシュボード)からそれらのレポートを見られるようにします。

NOTE: **注意:**
テストレポートはジョブの実行結果(成功や失敗)にかかわらず収集されます。
[`artifacts:expire_in`](#artifactsexpire_in)でこれらの成果物の有効期限を設定できます。

NOTE: **注意:**
出力されたレポートファイルも参照する場合には、[`artifacts:paths`](#artifactspaths)
設定キーワードも含めて下さい。

##### `artifacts:reports:junit`

> GitLab 11.2の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390)で導入されました。GitLab Runner 11.2以上が必要です。

`junit`レポートは、成果物として[JUnit XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html)を収集します。JUnitは、元々Javaで開発されていたものですが、JavaScriptやPython、Ruby等の
その他の言語についても[third party ports](https://en.wikipedia.org/wiki/JUnit#Ports)で
多数移植されています。

より詳細な内容やサンプルについては、[JUnit test reports](../junit_test_reports.md)で
参照できます。
以下は、Ruby's RSpecテストツールで生成されたJUnit XMLファイルを収集する例です:

```yaml
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](https://gitlab.com/gitlab-org/gitlab/issues/17066) 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](../environments.md#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](https://github.com/motdotla/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](https://gitlab.com/gitlab-org/gitlab/issues/3708) in GitLab 12.9. Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above.

The `cobertura` report collects [Cobertura coverage XML files](../../user/project/merge_requests/test_coverage_visualization.md).
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](../../user/project/merge_requests/code_quality.md)を
収集します。

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

##### `artifacts:reports:sast` **(ULTIMATE)**

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

`sast`レポートは、成果物として[SAST vulnerabilities](../../user/application_security/sast/index.md)を
収集します。

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

##### `artifacts:reports:dependency_scanning` **(ULTIMATE)**

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

`dependency_scanning`レポートは、成果物として[Dependency Scanning vulnerabilities](../../user/application_security/dependency_scanning/index.md)を
収集します。

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

##### `artifacts:reports:container_scanning` **(ULTIMATE)**

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

`container_scanning`レポートは、成果物として[Container Scanning vulnerabilities](../../user/application_security/container_scanning/index.md)
を収集します。

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

##### `artifacts:reports:dast` **(ULTIMATE)**

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

`dast`レポートは、成果物として[DAST vulnerabilities](../../user/application_security/dast/index.md)を
収集します。

収集された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](#artifactsreportslicense_scanning-ultimate)
introduced in GitLab 12.8.

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

`license_management`レポートは、成果物として[Licenses](../../user/project/merge_requests/license_management.md)を
収集します。

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

##### `artifacts:reports:license_scanning` **(ULTIMATE)**

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

`license_scanning`レポートは、成果物として[Licenses](../../user/compliance/license_compliance/index.md)を
収集します。

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

##### `artifacts:reports:performance` **(PREMIUM)**

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

`performance`レポートは、成果物として[Performance metrics](../../user/project/merge_requests/browser_performance_testing.md)を
収集します。

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

##### `artifacts:reports:metrics` **(PREMIUM)**

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

`metrics`レポートは、成果物として[Metrics](../../ci/metrics_reports.md)を
収集します。

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

### `dependencies`

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

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

By default, all [`artifacts`](#artifacts) from all previous [stages](#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](#stages) の優先度により、その前の全てのジョブの成果物が
ダウンロードされます:

```yaml
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](#artifactsexpire_in)か
[erased](../../user/project/pipelines/job_artifacts.md#erasing-artifacts)されて
いる場合、依存しているジョブは失敗します。

NOTE: **注意:**
旧来の挙動に戻す場合、管理者に
[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies)
を依頼してください。

### `needs`

> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47063) in GitLab 12.2.
> - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30631) 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](../directed_acyclic_graph/index.md) 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:

```yaml
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](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/7541).
  - 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](https://gitlab.com/gitlab-org/gitlab/issues/30632).
- 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](../../administration/troubleshooting/debug.md#starting-a-rails-console-session)
and run:

```ruby
Feature::disable(:ci_dag_limit_needs)
```

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

```ruby
Feature::enable(:ci_dag_limit_needs)
```

#### Artifact downloads with `needs`

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14311) 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:

```yaml
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`.

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

#### Cross project artifact downloads with `needs` **(PREMIUM)**

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14311) 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](#artifact-downloads-between-pipelines-in-the-same-project),
or pipelines in different projects:

```yaml
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:

```yaml
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:`](#parallel) is not supported.

### `coverage`

> GitLab 8.17の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7447)で導入されました。

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


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

簡単な例:

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

### `retry`

> GitLab 9.5の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12909)で導入されました
> [Behaviour expanded](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21758)によりGitLab 11.5からどのフェイルで再試行するかどうか制御できるようになりました。

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

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

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

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

```yaml
test:
  script: rspec
  retry: 2
```

デフォルトでは、全ての失敗のケースでジョブの再試行します。どのような失敗の場合には
どのような再試行をするのが適しているか、`retry`で次のハッシュを使って設定します:

- `max`: 再試行の最大回数.
- `when`: 再試行する失敗のケース.

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

```yaml
test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure
```

Runnerのシステムフェイル以外で、上記のその他のフェイルがあった場合、ジョブは
再試行されません:

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

```yaml
test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
```

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

<!--
  Please make sure to update `RETRY_WHEN_IN_DOCUMENTATION` array in
  `spec/lib/gitlab/ci/config/entry/retry_spec.rb` if you change any of
  the documented values below. The test there makes sure that all documented
  values are really valid as a config option and therefore should always
  stay in sync with this documentation.
 -->

- `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](https://gitlab.com/gitlab-org/gitlab/issues/14887) in GitLab 12.3.

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

```yaml
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](../pipelines/settings.md#timeout) but can not
exceed the Runner-specific timeout.

### `parallel`

> GitLab 11.5の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22631)で導入されました。

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

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

全てのジョブに対して、`CI_NODE_INDEX`と`CI_NODE_TOTAL` [environment variables](../variables/README.md#predefined-environment-variables)が設定されます。例:

```yaml
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](https://github.com/renderedtext/test-boosters) and RSpec to run some Ruby tests:

```ruby
# Gemfile
source 'https://rubygems.org'

gem 'rspec'
gem 'semaphore_test_boosters'
```

```yaml
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](https://about.gitlab.com/pricing/) 11.8の[Introduced](https://gitlab.com/gitlab-org/gitlab-org/issues/8997)で導入されました。
> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/199224) to GitLab Core in 12.8.

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

マルチプロジェクトパイプラインについては、[multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml)を参照して下さい。

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

- [Multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml)
- [Child pipelines](../parent_child_pipelines.md)

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`キーワードを使って下流のパイプラインのプロジェクトのフルパスを
指定して設定する一番簡単な方法です:

```yaml
rspec:
  stage: test
  script: bundle exec rspec

staging:
  stage: deploy
  trigger: my/deployment
```

#### マルチプロジェクトパイプラインでの複雑な`trigger`定義

下流のパイプラインをブランチ名を指定してGitLabからパイプラインを
起動することも可能です:

```yaml
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:

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

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

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

#### `trigger` syntax for child pipeline

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/16094) in GitLab 12.7.

To create a [child pipeline](../parent_child_pipelines.md), specify the path to the
YAML file containing the CI config of the child pipeline:

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

Similar to [multi-project pipelines](../multi_project_pipelines.md#mirroring-status-from-triggered-pipeline),
it is possible to mirror the status from a triggered pipeline:

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

##### Trigger child pipeline with generated configuration file

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/35632) in GitLab 12.9.

You can also trigger a child pipeline from a [dynamically generated configuration file](../parent_child_pipelines.md#dynamic-child-pipelines):

```yaml
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.

```yaml
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](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23464) 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](../pipelines/settings.md#auto-cancel-pending-pipelines)
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:

```yaml
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](https://gitlab.com/gitlab-org/gitlab/issues/15536) 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:

```yaml
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_group`s 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](https://about.gitlab.com/pricing/) 10.5で導入されました。
> - 10.6からStarter、Premium、Ultimateで利用できるようになりました。
> - GitLab 11.4からCoreに[移行](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21603)しました。

外部のYAMLファイルを`include`設定キーワードを使うと取り込むことができます。
`include`で読み込む外部のYAMLは、`.yml`か`.yaml`である必要があり、
その他のファイルは読み込まれません。

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

- `.gitlab-ci.yml`に書かれているファイルはネストしてマージします。
- `.gitlab-ci.yml`の内容は、`include`の書かれている場所にかかわらず、
  最初に評価され、マージされます。

TIP: **ヒント:**
ローカルの定義がされているCI/CD設定についても対象としてカスタマイズを
マージしたり、上書きするのに使います。

NOTE: **注意:**
`include`で読み込まれた複数のYAMLファイルにまたがったYAMLエイリアスを使う
方法はサポートされていません。参照できるのは同じファイルのエイリアスで
ある必要があります。YAMLのアンカーを使う代わりに [`extends` keyword](#extends)を使えます。

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

- [`local`](#includelocal)
- [`file`](#includefile)
- [`template`](#includetemplate)
- [`remote`](#includeremote)

[usage examples](#include-examples)を参照。

NOTE: **注意:**
どのメソッドであろうともそれらを含んだ`.gitlab-ci.yml`設定は、パイプライン作成時に
評価されます。その時のスナップショットとしてデータベースに設定は保存されます。
`.gitlab-ci.yml`を参照した設定を変更しても、次のパイプラインが実行されるまでGitLabには反映されません。

#### `include:local`

`.gitlab-ci.yml`と同じリポジトリにあるファイルを`include:local`で読み込みます。
ファイルはルートディレクトリ(`/`)からの相対パスを使って参照します。

設定ファイルがあるのと同じブランチでGitによって現在追跡されているファイルのみを使用できます。
言い換えれば、 `include：local`を使うとき、同じブランチに`.gitlab-ci.yml`とローカル
ファイルの両方があるようにしてください。

ネストした[nested includes](#nested-includes)は全て、同じプロジェクトの範囲で起動するので、
ローカル、プロジェクト、リモート、またはテンプレートのインクルードを利用できます。

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

例:

```yaml
include:
  - local: '/templates/.gitlab-ci-template.yml'
```

#### `include:file`

>  GitLab 11.7の[Introduced](https://gitlab.com/gitlab-foss/-/gitlab-ce/issues/53903)で導入されました。

同じGitLabのインスタンス配下の他のプライベートプロジェクトからファイルを読み込ませるには、
`include:file`を使います。ファイルはルートディレクトリ(`/`)からの相対パスを使って
参照します。例:

```yaml
include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'
```
同様に`ref`を指定できます。デフォルトでは、プロジェクトの`HEAD`になります:

```yaml
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](#nested-includes)は全て、目的のプロジェクトの範囲で起動するので、
ローカル(目的のプロジェクトに対して)、プロジェクト、リモート、またはテンプレートのインクルード
を利用できます。

#### `include:template`

> GitLab 11.7の[Introduced](https://gitlab.com/gitlab-foss/-/gitlab-ce/issues/53903)で導入されました。

`.gitlab-ci.yml`のテンプレート[shipped with GitLab](https://gitlab.com/gitlab-org/gitlab-foss/-/tree/master/lib/gitlab/ci/templates)を`include:template`で読み込むことができます。

例:

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

Multiple `include:template` files:

```yaml
include:
  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml
```

ネストした[nested includes](#nested-includes)は全て、ユーザーの権限で起動するので、
プロジェクト、リモート、またはテンプレートのインクルードで利用できます。

#### `include:remote`

HTTP/HTTPSを使って別の場所のファイルをフルパスのURLで`include:remote`を使って
読み込みます。リモートファイルは、GETリクエストで単純に外部からアクセスできるもので
ある必要があります。 認証付きのリモートURLはサポートしていません。例:

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

ネストしたファイルは、パブリックユーザーとして経緯なしで実行されるので、その他のリモート、
パブリックプロジェクト、テンプレートのみ利用できます。

#### ネストしたincludes

> GitLab 11.9の[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56836)で導入されました。

ネストのインクルードを使用することにより、includeのセットを作れます。
includeを全部で100回まで利用できます。
インクルードが重複していると構成エラーになります。

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/28212) in GitLab 12.4.

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

#### `include`の例

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

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

外部YAMLファイルの読み込みは、1行で記述する方法と複数行の配列形式
で記述する方法があります。次の例は全て有効です。

1行で`include:local`を記述:

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

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

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

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

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

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

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

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

```yaml
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
```

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

```yaml
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`の内容は次の通りです:

```yaml
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`の内容は次のようになっています:

```yaml
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`の内容は次の通りです:

```yaml
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`の内容は次のようになっています:

```yaml
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`の内容は次の通りです:

```yaml
production:
  stage: production
  script:
    - install_dependencies
    - deploy
```

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

```yaml
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`を読み込みます:

```yaml
include:
  - local: /.gitlab-ci/another-config.yml
```

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

```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つのファイルを読み込みます:

```yaml
include:
  - local: /templates/docker-build.yml
  - local: /templates/docker-testing.yml
```

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

```yaml
docker-build:
  script: docker build -t my-image .
```

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

```yaml
docker-test:
  script: docker run my-image /run/tests.sh
```

### `extends`

> GitLab 11.3で導入されました

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

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

```yaml
.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches

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

上の例では、`rspec`ジョブを`.tests`のテンプレートジョブから継承しています。
GitLabはキーを起点にさかのぼって読み込んで実行します。GitLabは次のことを行います:

- `rspec`の内容を再帰的に読み込んでマージします。
- キーの値はマージしません。

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

```yaml
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`](#before_script-and-after_script)を見て下さい。

この例の`.test`は、[hidden key](#hidden-keys-jobs)ですが、通常のジョブでも
同じように継承することができます。

マルチレベル継承を`extends`ではサポートしています。しかし、3レベル以上の継承は
おすすめしません。最大10のレベル(段階)のネストをサポートしています。
以下の例では継承を2レベル(段階)で行っています:

```yaml
.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`も可能です。
"直近のスコープが勝つ"というマージアルゴリズムを使っています。
最後のメンバーのキーが常に他のレベルで定義されているものを上書きします。
例:

```yaml
.only-important:
  only:
    - master
    - stable
  tags:
    - production

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

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

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

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

### `extends`と`include`を一緒に使う

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

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

```yaml
.template:
  script:
    - echo Hello!
```

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

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

```yaml
pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - master
```
詳しくは、[GitLab Pages user documentation](../../user/project/pages/index.md)を参照して下さい。

### `variables`

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

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

GitLab CI/CDでは`.gitlab-ci.yml`に変数を定義して、ジョブ環境にその変数を渡すことができます。
この変数は環境全体にもジョブ毎にも定義することができます。
ジョブレベルで`variables`を定義すると、グローバルレベルで定義した同じ名前のYAMLの変数や
定義済の変数を上書きします。

これらは、Gitリポジトリに保存されますので、あまり機密性をもとめられないプロジェクトでの設定を
格納するためのものです。たとえば次のようになります。

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

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

変数は、[job level](#job-variables)単位でも定義することができます。

ユーザが定義する変数以外にも、Runner自身が設定する変数もあります。
 [set up by the Runner itself](../variables/README.md#predefined-environment-variables)
 一つの例としては、`CI_COMMIT_REF_NAME` というプロジェクトでビルドするブランチ名やタグ名です。
 `.gitlab-ci.yml`で設定できる変数の他に、GitLabのUIで設定できるいわゆる秘密の変数もあります。

[YAMLのスクリプト用のアンカー](#yaml-anchors-for-script)も利用できます。

より詳細には、[variables and their priority](../variables/README.md)を見てください。

#### 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`](#variables)セクションで全体設定もしくは、ジョブ毎に設定できます。
未指定の場合、プロジェクト設定のデフォルトが利用されます。

`clone`、`fetch`と`none`の3種類の挙動を指定できます。

`clone`は一番遅くなるオプションです。ジョブ実行毎にリポジトリを一からクローンします。
ローカルワーキングコピーが常に最新になることを保証します。

```yaml
variables:
  GIT_STRATEGY: clone
```

`fetch`の場合は、ローカルワーキングコピーを再利用するので(存在しない場合は`clone`を
実行します)、一番早くなります。一番最後のジョブが加えた変更を`git clean`でリセットして、
`git fetch`で最後のジョブが実行した後にコミットされている変更を取得します。

```yaml
variables:
  GIT_STRATEGY: fetch
```

`none`も同様にローカルワーキングコピーを再利用しますが、Git の操作を全て(GitLab
Runnerのプレクローンスクリプトがあったとしても)スキップします。成果物に対してのみ動作
するジョブ(例えば`deploy`)に最適です。Gitリポジトリーはあると思いますが、`none`の
場合は、古くなっているはずなので、ローカルワーキングコピーのキャッシュや成果物のファイルのみを
利用するようにしてください。

```yaml
variables:
  GIT_STRATEGY: none
```

NOTE: **注意:** `GIT_STRATEGY`は、
[Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html)
ではサポートされていませんが、近い将来サポートされるかもしれません。
進捗については、[support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/issues/3847)を見て下さい。

#### Git submodule strategy

> GitLab Runner v1.10以上が必要

`GIT_SUBMODULE_STRATEGY`変数は、 ビルド前にソースコードを取ってくるときの
Git submodulesでの取得方法や取得の有無を制御する為のものです。
[`variables`](#variables)セクションで全体設定もしくは、ジョブ毎に設定できます。

次の3つの値をとることができます:`none`、`normal`と`recursive`:

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

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

  ```shell
  git submodule sync
  git submodule update --init
  ```

- `recursive`にすると、submodule の全て(Submodule の Submodule)を含みます。
- 以下の操作と同じです。この機能は、Git v1.8.1以降のバージョンが必要です。
- DockerベースではないGitLab Runnerを実行者にしている場合は、この機能に必要な
  Git のバージョンになっているかどうか確認してください。

  ```shell
  git submodule sync --recursive
  git submodule update --init --recursive
  ```

この機能を正しく動かす為の注意点は、submodulesで以下の設定を
(`.gitmodules`)内にどちらかをで正しく設定しておくことにあります:

- 公開アクセスができるリポジトリ内のHTTP(S)のURLパス または、
- 同じGitLabサーバーの他のリポジトリ関連パス

詳しくは、[Git submodules](../git_submodules.md)のドキュメントを確認してください。

#### Git checkout

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

`GIT_CHECKOUT`変数設定は、`GIT_STRATEGY`で`clone`か`fetch`に指定していて、
`git checkout`を実施するかどうかを指定します。指定しない場合は、trueです。
[`variables`](#variables)セクションで全体設定もしくは、ジョブ毎に設定できます。

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

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

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

```yaml
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`](#variables)セクションで全体設定もしくは、ジョブ毎に設定できます。

`GIT_CLEAN_FLAGS`としては、[`git clean`](https://git-scm.com/docs/git-clean)
コマンドで利用できるオプションを全て受け付けられます。

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

`GIT_CLEAN_FLAGS`が以下の場合:

- 未指定の場合、`git clean`オプションはデフォルトの`-ffdx`になります。
- `none`の場合、`git clean`は実行されません。

例:

```yaml
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](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450), the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). |

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

例:

```yaml
variables:
  GET_SOURCES_ATTEMPTS: 3
```

[`variables`](#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する:

```yaml
variables:
  GIT_DEPTH: "3"
```

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

## 非推奨パラメーター

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

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

CAUTION: **非推奨:**
`types` は非推奨です。将来のバージョンで削除される可能性があります。
代わりに[`stages`](#stages)を使って下さい。

### ジョブに定義された`type`

CAUTION: **非推奨:**
`type` は非推奨です。将来のバージョンで削除される可能性があります。
代わりに[`stage`](#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:`](#setting-default-parameters) instead. For example:

```yaml
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](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1267)で導入されました

NOTE: **注意:**
この設定は、`custom_build_dir`が[Runner's configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section)
設定で有効になっている場合にのみ利用することができます。
`docker`と`kubernetes`の実行環境ではデフォルトの設定です。

デフォルトでは、GitLab Runnerは`$CI_BUILDS_DIR`の一意なサブディレクトリに
クローンします。しかし、プロジェクトによっては特定のディレクトリにソースコードを
置く必要がある場合もあります(Goプロジェクト等)。そういった場合に、`GIT_CLONE_PATH`
変数を設定すれば、Runnerにどのディレクトリにリポジトリをコピーしてほしいか、
伝えることができます:

```yml
variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name

test:
  script:
    - pwd
```
`GIT_CLONE_PATH`は、必ず`$CI_BUILDS_DIR`内になります。`$CI_BUILDS_DIR`で設定される
ディレクトリは、実行環境と[runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section)の設定に依存します。

### 並列度の取り扱い

並列度を`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`を使うことです。例:

```yml
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`ということになります。例:

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

test:
  script:
    - pwd
```

### ネストされたパスの展開

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

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

```yml
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](https://learnxinyminutes.com/docs/yaml/)
を見てください。

### 隠しキー(ジョブ)

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

一時的に ジョブを'disable'するには、全てのジョブが設定されている行をコメントするよりも、
次のようにすることができます:

```yaml
#hidden_job:
#  script:
#    - run test
```

ジョブ名を(`.`)で始まる名前にします。そうするとGitLab CI/CDでは実行されなくなります。
次の例では、`.hidden_job`というジョブは無視されます

```yaml
.hidden_job:
  script:
    - run test
```

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

### アンカー

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

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

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

```yaml
.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`) を指定しています。
展開されると以下のようになります:

```yaml
.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`が参照されています:

```yaml
.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
```

これが展開されると以下のようになります:

```yaml
.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`](#trigger-premium)と混同しないでください。

詳しくは、[Read more in the triggers documentation.](../triggers/README.md)を
参照して下さい。

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

#### YAML anchors for `before_script` and `after_script`

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/23005) in GitLab 12.5.

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

Example:

```yaml
.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](https://gitlab.com/gitlab-org/gitlab/issues/23005) in GitLab 12.5.

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

For example:

```yaml
.something: &something
- echo 'something'

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

#### YAML anchors for variables

[YAML anchors](#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:

```yaml
# 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`](#trigger).

[Read more in the triggers documentation.](../triggers/README.md)

## Git push操作

1回の`git push`操作で複数の変更をpushするときに、GitLabでは
最大4つでブランチとタグのパイプラインの作成を行います。

この制限は、マージリクエストにおけるパイプラインリクエストのアップデート
に対しては影響しません。[pipelines for merge requests](../merge_request_pipelines/index.md)を使った場合、全てのマージリクエストの更新においてパイプラインが
作成されます。

## ジョブのスキップ

コミットメッセージに`[ci skip]`や`[skip ci]`が入っていると大文字小文字のどちらで
あっても、そのコミットは作成されますが、ジョブ実行はスキップされます

他にも、Git 2.10以降であれば、`ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd)を
渡すこともできます。

<!-- ## Troubleshooting

Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.

Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->

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


--------------------------------------------------------
GitLab実践ガイド - インプレスブックス
[https://book.impress.co.jp/books/1116101163](https://book.impress.co.jp/books/1116101163)
<img src="https://qiita-image-store.s3.amazonaws.com/0/15176/8a0bec7a-dee2-1934-68cd-877d9d5fa179.png" width=30%>
--------------------------------------------------------