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

GitLab Advent Calendar 2018 - Qiita
https://qiita.com/advent-calendar/2018/gitlab
20日目です。

間違い、わかりにくい等ありましたらご連絡いただければ幸いです。

GitLab.org / GitLab Community Edition · GitLab  doc/ci/variables/README.md
https://gitlab.com/gitlab-org/gitlab-ce/blob/0087396036b265879771380e60787e2072318fd1/doc/ci/variables/README.md
を翻訳したものです。全てではありませんが、普通に利用する分には問題ないでしょう。

# 変数

GitLab CI がジョブを受け取ったときに [Runner] が ビルド環境として用意します。
まず **定義済み変数** (環境変数) のリストアップから初めて、その後に **ユーザ定義** 変数をリストアップします。

## 変数の優先度

これらの変数は上書きできますが、以下のルールによって優先順位が決まっています  
優先順位:

1. [トリガー変数][triggers] または [スケジューリングされたパイプラインの変数](../../user/project/pipelines/schedules.md#making-use-of-scheduled-pipeline-variables) (全てにおいて優先します)
1. プロジェクトレベル [シークレット変数](#secret-variables) または [保護されたシークレット変数](#protected-secret-variables)
1. グループレベル [シークレット変数](#secret-variables) or [保護されたシークレット変数](#protected-secret-variables)
1. YAMLで定義 [ジョブレベル変数](../yaml/README.md#job-variables)
1. YAMLで定義 [グローバルレベル](../yaml/README.md#variables)
1. [デプロイ変数](#deployment-variables)
1. [定義済み変数](#predefined-variables-environment-variables) (これらの中で優先度が最も低い)

例えば、`.gitlab-ci.yml` に `API_TOKEN=secure` をシークレット変数として、 そして、
`API_TOKEN=yaml` 変数を定義します。その場合、`API_TOKEN` は、優先順位でより高い
シークレット変数 `secret` の値になります。

## 未サポート変数

`.gitlab-ci.yml` のコンテクストとして利用できない変数が存在する場合があります(例えば、`script` 配下など)。どの変数がサポートされていないかについては、[not supported](where_variables_can_be_used.md) を参照してください。

## 定義済み変数 (環境変数)

いくつかの定義済み変数は、最低利用可能バージョンの [GitLab Runner][runner] を使う必要があります。
どのバージョンの ランナーが必要かについては、下記のテーブルを参照してください。

NOTE: **注意:**
GitLab 9.0 からいくつかの変数が非推奨になりました。変更点については、
[9.0 Renaming](#9-0-renaming) セクションを参照してください。**将来のGitLabリリースで
削除される予定ですので新しい変数を利用することを強く推奨します。**

| 変数                                      | GitLab | ランナー | 詳細       |
|-------------------------------------------|--------|--------|-------------|
| **ARTIFACT_DOWNLOAD_ATTEMPTS**  | 8.15   | 1.9    | 実行ジョブのアーティファクトのダウンロード試行回数 |
| **CI**                          | all    | 0.4    | CI環境で実行されていることを示します |
| **CI_COMMIT_REF_NAME**          | 9.0    | all    | そのプロジェクトがビルドされているブランチ名かタグ名 |
| **CI_COMMIT_REF_SLUG**          | 9.0    | all    | `$CI_COMMIT_REF_NAME` を小文字化して 63バイトに短縮化 `0-9` と `a-z` 以外は `-` に置換されます。先頭と末尾には `-` を使いません。URL、ホスト名、ドメイン名で使用できます。 |
| **CI_COMMIT_SHA**               | 9.0    | all    | ビルド中のプロジェクトのコミットリビジョン |
| **CI_COMMIT_BEFORE_SHA**        | 11.2   | all    | プッシュリクエスト直前の最新コミットID |
| **CI_COMMIT_TAG**               | 9.0    | 0.5    | コミットタグ名。ビルド中のタグのみ表示されます。|
| **CI_COMMIT_MESSAGE**           | 10.8   | all    | コミットメッセージ全文 |
| **CI_COMMIT_TITLE**             | 10.8   | all    | コミットタイトル - コミットメッセージの最初の一行 |
| **CI_COMMIT_DESCRIPTION**       | 10.8   | all    | コミット詳細: タイトル行が100文字よりも短い場合の最初の一行を除いたメッセージです；それ以外の場合は全文です。|
| **CI_CONFIG_PATH**              | 9.4    | 0.5    | CI設定ファイルのパス。デフォルトは `.gitlab-ci.yml` |
| **CI_DEBUG_TRACE**              | all    | 1.7    | [debug tracing](#debug-tracing) が有効かどうか |
| **CI_DEPLOY_USER**              | 10.8   | all    | [GitLab Deploy Token][gitlab-deploy-token] の認証ユーザー名、プロジェクトが1つだけ関連付けられている場合にのみ出力|
| **CI_DEPLOY_PASSWORD**          | 10.8   | all    | [GitLab Deploy Token][gitlab-deploy-token]の認証パスワード、プロジェクトが一つだけ関連付けられている場合にのみ出力|
| **CI_DISPOSABLE_ENVIRONMENT**   | all    | 10.1   | このジョブが使い捨てな環境で実行される場合にのみフラグを示します。 (この環境は、このジョブでのみ生成されるもので、実行後に削除もしくは破壊されるものです - `shell` と `ssh` を除く全てです ). この環境が使い捨ての場合、trueにセットされます。それ以外の場合は未定義です。 |
| **CI_ENVIRONMENT_NAME**         | 8.15   | all    | このジョブの環境名 |
| **CI_ENVIRONMENT_SLUG**         | 8.15   | all    | 環境名の簡易バージョン、DNS名やURL、Kubernetesのラベルなどに適しています。|
| **CI_ENVIRONMENT_URL**          | 9.3    | all    | このジョブ環境のURL |
| **CI_JOB_ID**                   | 9.0    | all    | GitLab CI が内部的に利用する現在のジョブのユニークID |
| **CI_JOB_MANUAL**               | 8.12   | all    | ジョブが手動実行されているかどうかを示すフラグ |
| **CI_JOB_NAME**                 | 9.0    | 0.5    | `.gitlab-ci.yml` で定義されているジョブ名 |
| **CI_JOB_STAGE**                | 9.0    | 0.5    | `.gitlab-ci.yml` で定義されているステージ名|
| **CI_JOB_TOKEN**                | 9.0    | 1.2    | GitLab コンテナーレジストリで使える認証用トークン |
| **CI_MERGE_REQUEST_ID**                   | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのID |
| **CI_MERGE_REQUEST_IID**                  | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのIID |
| **CI_MERGE_REQUEST_REF_PATH**             | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのrefパス. (e.g. `refs/merge-requests/1/head`) |
| **CI_MERGE_REQUEST_PROJECT_ID**           | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのプロジェクトID |
| **CI_MERGE_REQUEST_PROJECT_PATH**         | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのプロジェクトパス (e.g. `namespace/awesome-project`) |
| **CI_MERGE_REQUEST_PROJECT_URL**          | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのプロジェクトのURL (e.g. `http://192.168.10.15:3000/namespace/awesome-project`) |
| **CI_MERGE_REQUEST_TARGET_BRANCH_NAME**   | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのターゲットブランチ名 |
| **CI_MERGE_REQUEST_SOURCE_PROJECT_ID**    | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストの元プロジェクトのID |
| **CI_MERGE_REQUEST_SOURCE_PROJECT_PATH**  | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストの元プロジェクトのパス |
| **CI_MERGE_REQUEST_SOURCE_PROJECT_URL**   | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストの元プロジェクトのURL |
| **CI_MERGE_REQUEST_SOURCE_BRANCH_NAME**   | 11.6   | all    | [pipelines for merge requests](../merge_request_pipelines/index.md) の場合のマージリクエストのソースブランチ名 |
| **CI_NODE_INDEX**                         | 11.5   | all    | ジョブセット内のジョブのインデックス。ジョブが並列になっていない場合は、この変数はセットされません。|
| **CI_NODE_TOTAL**                         | 11.5   | all    | ジョブが並列実行のトータルインスタンス数。ジョブが並列になっていない場合は、この変数は1にセットされます。 |
| **CI_JOB_URL**                            | 11.1   | 0.5    | 実行ジョブ詳細のURL |
| **CI_REPOSITORY_URL**           | 9.0    | all    | クローンするGitリポジトリのURL |
| **CI_RUNNER_DESCRIPTION**       | 8.10   | 0.5    | GitLabに保存されているRunnerの説明 |
| **CI_RUNNER_ID**                | 8.10   | 0.5    | 使われているランナーのユニークID |
| **CI_RUNNER_TAGS**              | 8.10   | 0.5    | 定義済みランナータグ |
| **CI_RUNNER_VERSION**                     | all    | 10.6   | 実行中のジョブのGitLab ランナーのバージョン |
| **CI_RUNNER_REVISION**                    | all    | 10.6   | 実行中のジョブのGitLab ランナーのリビジョン |
| **CI_RUNNER_EXECUTABLE_ARCH**             | all    | 10.6   | GitLab ランナーの実行ファイルのOS/アーキテクチャ (これは実行環境と同じではないことに注意) |
| **CI_PIPELINE_ID**              | 8.10   | 0.5    | GitLab CIが内部的に使用する現在のパイプラインのユニークID |
| **CI_PIPELINE_TRIGGERED**       | all    | all    | ジョブが[triggered]であるかを示しているフラグ |
| **CI_PIPELINE_SOURCE**          | 10.0   | all    | このパイプラインのソース: push, web, trigger, schedule, api, external のどれか。9.5より前に作成されたパイプラインは不明です。 |
| **CI_PROJECT_DIR**              | all    | all    | ジョブが実行されるリポジトリーがクローンされたフルパス |
| **CI_PROJECT_ID**               | all    | all    | GitLab CIが内部的に利用する現在のプロジェクトのユニークID |
| **CI_PROJECT_NAME**             | 8.10   | 0.5    | 現在ビルド中のプロジェクト名 (実際にはプロジェクトフォルダー名) |
| **CI_PROJECT_NAMESPACE**        | 8.10   | 0.5    | 現在ビルド中のプロジェクトネームスペース名 (ユーザー名かグループ名) |
| **CI_PROJECT_PATH**             | 8.10   | 0.5    | ネームスペース付きのプロジェクト名 |
| **CI_PROJECT_PATH_SLUG**        | 9.3    | all    | `$CI_PROJECT_PATH` の `0-9` and `a-z` 以外を `-` に変換して、小文字にした。ドメイン名やURLからに利用できる。 |
| **CI_PROJECT_URL**              | 8.10   | 0.5    | プロジェクトにアクセスするHTTPアドレス |
| **CI_REGISTRY**                 | 8.10   | 0.5    | コンテナーレジストリが有効な場合、GitLab's Container Registry のURLを返す |
| **CI_REGISTRY_IMAGE**           | 8.10   | 0.5    | このプロジェクトでコンテナーレジストリが有効な場合、プロジェクトに紐付けられたレジストリのアドレスを返す |
| **CI_REGISTRY_PASSWORD**        | 9.0    | all    | GitLab Container Registry にコンテナーをプッシュするときに使うパスワード |
| **CI_REGISTRY_USER**            | 9.0    | all    | GitLab Container Registry にコンテナーをプッシュするときに使うユーザー名 |
| **CI_SERVER**                   | all    | all    | ジョブがCI環境で実行されていることを示す |
| **CI_SERVER_NAME**              | all    | all    | ジョブを調整するCIサーバー名 |
| **CI_SERVER_REVISION**          | all    | all    | ジョブをスケジューリングする GitLab revision |
| **CI_SERVER_VERSION**           | all    | all    | ジョブをスケジューリングする GitLab version |
| **CI_SERVER_VERSION_MAJOR**               | 11.4   | all    | GitLab コンポーネントのメジャーバージョン |
| **CI_SERVER_VERSION_MINOR**               | 11.4   | all    | GitLab コンポーネントのマイナーバージョン |
| **CI_SERVER_VERSION_PATCH**               | 11.4   | all    | GitLab コンポーネントのパッチバージョン |
| **CI_SHARED_ENVIRONMENT**                 | all    | 10.1   | ジョブが共有環境(`shell` や `ssh` のようなCI実行をまたいでいる)で実行されていることを示す。環境が共有されている場合は、trueに設定、そうでない場合設定されません。|
| **GET_SOURCES_ATTEMPTS**        | 8.15   | 1.9    | このジョブ実行中のソース取得試行回数 |
| **GITLAB_CI**                   | all    | all    | GitLab CI環境で実行されていることを示す |
| **GITLAB_USER_ID**              | 8.12   | all    | ジョブを開始した人のID |
| **GITLAB_USER_EMAIL**           | 8.12   | all    | ジョブを開始した人のメールアドレス |
| **GITLAB_USER_LOGIN**           | 10.0   | all    | ジョブを開始した人のログインユーザー名 |
| **GITLAB_USER_NAME**            | 10.0   | all    | ジョブを開始した人の実名 |
| **RESTORE_CACHE_ATTEMPTS**      | 8.15   | 1.9    | ジョブ実行中のキャッシュのリストア試行回数 |

## GitLab 9.0 での名前の変更

GitLab の命名規則に従い、`build` 用語から `job` へより近づける為に、リリース9.0でCI変数名を
変更しました。

>NOTE: **注意:**
Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **新しい変数を利用することを
強くお勧めします。将来のGitLabリリースで古い変数は削除される予定です**

| 8.x name              | 9.0+ name               |
| --------------------- |------------------------ |
| `CI_BUILD_ID`         | `CI_JOB_ID`             |
| `CI_BUILD_REF`        | `CI_COMMIT_SHA`         |
| `CI_BUILD_TAG`        | `CI_COMMIT_TAG`         |
| `CI_BUILD_REF_NAME`   | `CI_COMMIT_REF_NAME`    |
| `CI_BUILD_REF_SLUG`   | `CI_COMMIT_REF_SLUG`    |
| `CI_BUILD_NAME`       | `CI_JOB_NAME`           |
| `CI_BUILD_STAGE`      | `CI_JOB_STAGE`          |
| `CI_BUILD_REPO`       | `CI_REPOSITORY_URL`     |
| `CI_BUILD_TRIGGERED`  | `CI_PIPELINE_TRIGGERED` |
| `CI_BUILD_MANUAL`     | `CI_JOB_MANUAL`         |
| `CI_BUILD_TOKEN`      | `CI_JOB_TOKEN`          |

## `.gitlab-ci.yml` defined variables

>NOTE:**注意:**
以下の機能は、GitLab Runner 0.5.0 かそれ以上のバージョン もしくは GitLab CI 7.14 かそれ以上のバージョンが必要です。

GitLab CIでは、 `.gitlab-ci.yml` に変数を定義し、ビルド環境に適用できます。そのため、
変数はリポジトリーに保存でき、`RAILS_ENV` や `DATABASE_URL` などのセキュリティーの
必要のないプロジェクトの設定に利用することができます。

For example, if you set the variable below globally (not inside a job), it will
be used in all executed commands and scripts:

例えば、以下のような変数をグローバル(ジョブ内ではなく)に定義すると、全てのコマンドと
スクリプトで利用できます:

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

YAMLで定義された変数は、同様に作成される [service containers](../docker/using_docker_images.md) 
にも適用されます。以下のような方法でそれらを修正することもできます。

変数は、グローバルレベルで定義する事もできますが、ジョブレベルで定義することもできます。
グローバルで定義した変数をジョブ内で無効にしたい場合は、空のハッシュを定義します:

```yaml
job_name:
  variables: {}
```

変数定義の設定内に他の定義を読み込んで利用することもできます。(または、`$$` でエスケープします):

```yaml
variables:
  LS_CMD: 'ls $FLAGS $$TMP_DIR'
  FLAGS: '-al'
script:
  - 'eval $LS_CMD'  # will execute 'ls -al $TMP_DIR'
```

## 変数

> グループレベル変数が GitLab 9.4 から導入されました。

CAUTION: **重要:**
注意が必要なこととして、変数は秘匿されることはありません。明示的に指定すれば、
ジョブ内ではそれらの値はログに出力することができます。プロジェクトがパブリックまたは、
インターナルの場合、[project's Pipelines settings](../../user/project/pipelines/settings.md#visibility-of-pipelines)
でパイプラインをプライベートに設定できます。
変数の秘匿についての議論は、[#13784][ce-13784] を読んでください。

GitLab CI ではプロジェクト単位やグループ単位の変数をパイプライン環境に
設定できます。それらの変数は、リポジトリーの外(`.gitlab-ci.yml` ではなく) に
保存され、GitLab Runnerに安全に渡されてパイプラインの実行時に利用されます。
この方法を使って、パスワードやSSH鍵や認証情報などを保存することを推奨します。

プロジェクトレベルの変数は、プロジェクト内の **Settings > CI/CD** で設定します。
**Variables** セクションで確認してください。

同じように、グループレベルの変数は、グループの **Settings > CI/CD** で設定します。
**Variables** セクションで確認してください。
全ての変数は、 [subgroups] に再帰的に継承されます。

<img width="810" alt="variables.png" src="https://qiita-image-store.s3.amazonaws.com/0/160547/68893f1c-7c97-cc8c-b2b8-a39fc0d64eda.png">

一度セットされると、全ての後続のパイプラインで使用できるようになります。[protect your variables](#protected-variables) も同様です

### プロテクト変数

> GitLab 9.3 から導入されました。

変数はプロテクトに設定できます。変数をプロテクトに設定すると、
[protected branches] や [protected tags] で実行されているパイプラインにのみ安全に
渡されます。その他のパイプラインでは、プロテクト変数は取得できません。

プロテクト変数は、プロジェクトの **Settings > CI/CD** で追加できます。
**Variables** セクションで確認して、"Protected" にチェックしてください。


### 手動起動時の指定変数

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/44059) in GitLab 10.8 で導入されました。

[manual pipeline](../pipelines.md#manually-executing-pipelines) で一つのパイプラインが作成されたときにのみ適用される変数です。

## デプロイ変数

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

デプロイ構成を担当する [Project services](../../user/project/integrations/project_services.md) では、ビルド環境に独自に変数を定義する必要があるかもしれません。
これらの変数は、[deployment jobs](../environments.md) でのみ定義されます。
定義されている変数については、利用しているプロジェクトサービスのドキュメントを確認してください。

デプロイ用変数を定義しているサンプルのプロジェクトは、[Kubernetes Service](../../user/project/integrations/kubernetes.md) があります。

## デバッグ トレース

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

CAUTION: **警告:**
デバッグトレースを有効にするとセキュリティに対する深刻な影響がある可能性があります。
出力には、変数の全てとシークレットの内容が**全て含まれ**ます！出力は、GitLabサーバーに
アップロードされて、ジョブのトレースで**見える**ようになります。

デフォルトでは、GitLabランナーはジョブ実行中の実行詳細のほとんどを表示することはありません。
この挙動によりジョブのトレースは短縮されて、明示的にそれらを画面に出力するようにスクリプトを
記載しない限り、トレース上にシークレット情報が漏れないようにしています。

もし、ジョブが想定の挙動をしていない場合、この設定は問題を発見するのを非常に難しくしています；
このような時には、`.gitlab-ci.yml` でデバッグトレースを有効にする事ができます。
この機能はGitLab Runner v1.7 以降では、シェル実行のトレースで利用でき、実行中の
全てのコマンドを詳細なジョブトレースとして、変数に何が入っているかも含めて見ることができます。

この機能を有効にする前に、ジョブを [team members only](../../user/permissions.md#project-features) でしか見えないようにしてください。
再度見られるする場合は、その前に過去のジョブのデバッグトレースを全て削除するべきです。

デバッグトレースを有効にするには、 `CI_DEBUG_TRACE` 変数を `true` に変更してください:

```yaml
job_name:
  variables:
    CI_DEBUG_TRACE: "true"
```

デバッグトレースをtrue にした場合のサンプル出力の一部です:

```bash
...

export CI_SERVER_TLS_CA_FILE="/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE"
if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then
  echo $'\''\x1b[32;1mFetching changes...\x1b[0;m'\''
  $'\''cd'\'' "/builds/gitlab-examples/ci-debug-trace"
  $'\''git'\'' "config" "fetch.recurseSubmodules" "false"
  $'\''rm'\'' "-f" ".git/index.lock"
  $'\''git'\'' "clean" "-ffdx"
  $'\''git'\'' "reset" "--hard"
  $'\''git'\'' "remote" "set-url" "origin" "https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git"
  $'\''git'\'' "fetch" "origin" "--prune" "+refs/heads/*:refs/remotes/origin/*" "+refs/tags/*:refs/tags/*"
else
  $'\''mkdir'\'' "-p" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template"
  $'\''rm'\'' "-r" "-f" "/builds/gitlab-examples/ci-debug-trace"
  $'\''git'\'' "config" "-f" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template/config" "fetch.recurseSubmodules" "false"
  echo $'\''\x1b[32;1mCloning repository...\x1b[0;m'\''
  $'\''git'\'' "clone" "--no-checkout" "https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git" "/builds/gitlab-examples/ci-debug-trace" "--template" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template"
  $'\''cd'\'' "/builds/gitlab-examples/ci-debug-trace"
fi
echo $'\''\x1b[32;1mChecking out dd648b2e as master...\x1b[0;m'\''
$'\''git'\'' "checkout" "-f" "-q" "dd648b2e48ce6518303b0bb580b2ee32fadaf045"
'
+++ hostname
++ echo 'Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-machine-1480971377-317a7d0f-digital-ocean-4gb...'
Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-machine-1480971377-317a7d0f-digital-ocean-4gb...
++ export CI=true
++ CI=true
++ export CI_DEBUG_TRACE=false
++ CI_DEBUG_TRACE=false
++ export CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ export CI_COMMIT_REF_NAME=master
++ CI_COMMIT_REF_NAME=master
++ export CI_JOB_ID=7046507
++ CI_JOB_ID=7046507
++ export CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git
++ CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git
++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
++ export CI_PROJECT_ID=1796893
++ CI_PROJECT_ID=1796893
++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ export CI_SERVER=yes
++ CI_SERVER=yes
++ export 'CI_SERVER_NAME=GitLab CI'
++ CI_SERVER_NAME='GitLab CI'
++ export CI_SERVER_VERSION=
++ CI_SERVER_VERSION=
++ export CI_SERVER_REVISION=
++ CI_SERVER_REVISION=
++ export GITLAB_CI=true
++ GITLAB_CI=true
++ export CI=true
++ CI=true
++ export GITLAB_CI=true
++ GITLAB_CI=true
++ export CI_JOB_ID=7046507
++ CI_JOB_ID=7046507
++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx
++ export CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045
++ export CI_COMMIT_REF_NAME=master
++ CI_COMMIT_REF_NAME=master
++ export CI_COMMIT_NAME=debug_trace
++ CI_JOB_NAME=debug_trace
++ export CI_JOB_STAGE=test
++ CI_JOB_STAGE=test
++ export CI_SERVER_NAME=GitLab
++ CI_SERVER_NAME=GitLab
++ export CI_SERVER_VERSION=8.14.3-ee
++ CI_SERVER_VERSION=8.14.3-ee
++ export CI_SERVER_REVISION=82823
++ CI_SERVER_REVISION=82823
++ export CI_PROJECT_ID=17893
++ CI_PROJECT_ID=17893
++ export CI_PROJECT_NAME=ci-debug-trace
++ CI_PROJECT_NAME=ci-debug-trace
++ export CI_PROJECT_PATH=gitlab-examples/ci-debug-trace
++ CI_PROJECT_PATH=gitlab-examples/ci-debug-trace
++ export CI_PROJECT_NAMESPACE=gitlab-examples
++ CI_PROJECT_NAMESPACE=gitlab-examples
++ export CI_PROJECT_URL=https://example.com/gitlab-examples/ci-debug-trace
++ CI_PROJECT_URL=https://example.com/gitlab-examples/ci-debug-trace
++ export CI_PIPELINE_ID=52666
++ CI_PIPELINE_ID=52666
++ export CI_RUNNER_ID=1337
++ CI_RUNNER_ID=1337
++ export CI_RUNNER_DESCRIPTION=shared-runners-manager-1.example.com
++ CI_RUNNER_DESCRIPTION=shared-runners-manager-1.example.com
++ export 'CI_RUNNER_TAGS=shared, docker, linux, ruby, mysql, postgres, mongo'
++ CI_RUNNER_TAGS='shared, docker, linux, ruby, mysql, postgres, mongo'
++ export CI_REGISTRY=registry.example.com
++ CI_REGISTRY=registry.example.com
++ export CI_DEBUG_TRACE=true
++ CI_DEBUG_TRACE=true
++ export GITLAB_USER_ID=42
++ GITLAB_USER_ID=42
++ export GITLAB_USER_EMAIL=user@example.com
++ GITLAB_USER_EMAIL=user@example.com
++ export VERY_SECURE_VARIABLE=imaverysecurevariable
++ VERY_SECURE_VARIABLE=imaverysecurevariable
++ mkdir -p /builds/gitlab-examples/ci-debug-trace.tmp
++ echo -n '-----BEGIN CERTIFICATE-----
MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw'

...
```

## ジョブスクリプト内での CI変数の利用方法

変数は全て、ビルド環境で環境変数として定義され、それらの変数を利用する方法は通常の変数として使用できます。ジョブスクリプトとして利用されるのは、`bash` または `sh` がほとんどです。

環境変数を利用するには、ランナーの [shell][shellexecutors] それぞれの文法で利用します。

| Shell                | 利用           |
|----------------------|-----------------|
| bash/sh              | `$variable`     |
| windows batch        | `%variable%`    |
| PowerShell           | `$env:variable` |

bash で環境変数を利用するには、変数名の前に(`$`)を付けます:

```yaml
job_name:
  script:
    - echo $CI_JOB_ID
```

**Windows Batch** で環境変数を利用するには、変数の前後を (`%`) で挟みます:

```yaml
job_name:
  script:
    - echo %CI_JOB_ID%
```

**Windows PowerShell** 環境で環境変数を利用するには、変数名の前に(`$env:`)を付けます:

```yaml
job_name:
  script:
    - echo $env:CI_JOB_ID
```

全ての環境変数をリストアップするには、 `export` コマンドを使います。
しかし、シークレット変数の値もジョブのログ中に出力されてしまうので気をつけてください:

```yaml
job_name:
  script:
    - export
```

サンプル値:

```bash
export CI_JOB_ID="50"
export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"
export CI_COMMIT_REF_NAME="master"
export CI_REPOSITORY_URL="https://gitlab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.git"
export CI_COMMIT_TAG="1.0.0"
export CI_JOB_NAME="spec:other"
export CI_JOB_STAGE="test"
export CI_JOB_MANUAL="true"
export CI_JOB_TRIGGERED="true"
export CI_JOB_TOKEN="abcde-1234ABCD5678ef"
export CI_PIPELINE_ID="1000"
export CI_PIPELINE_IID="10"
export CI_PROJECT_ID="34"
export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-ce"
export CI_PROJECT_NAME="gitlab-ce"
export CI_PROJECT_NAMESPACE="gitlab-org"
export CI_PROJECT_PATH="gitlab-org/gitlab-ce"
export CI_PROJECT_URL="https://example.com/gitlab-org/gitlab-ce"
export CI_REGISTRY="registry.example.com"
export CI_REGISTRY_IMAGE="registry.example.com/gitlab-org/gitlab-ce"
export CI_RUNNER_ID="10"
export CI_RUNNER_DESCRIPTION="my runner"
export CI_RUNNER_TAGS="docker, linux"
export CI_SERVER="yes"
export CI_SERVER_NAME="GitLab"
export CI_SERVER_REVISION="70606bf"
export CI_SERVER_VERSION="8.9.0"
export CI_SERVER_VERSION_MAJOR="8"
export CI_SERVER_VERSION_MINOR="9"
export CI_SERVER_VERSION_PATCH="0"
export GITLAB_USER_ID="42"
export GITLAB_USER_EMAIL="user@example.com"
export CI_REGISTRY_USER="gitlab-ci-token"
export CI_REGISTRY_PASSWORD="longalfanumstring"
```

## Variables expressions

> GitLab 10.7 で導入されました

`.gitlab-ci.yml` 内で、only / except という表現による変数の利用制限が可能になりました。
この方法を使うことにより、GitLabへコードをPushした後にパイプラインを作るかどうか
制限することができるようになりました。

これは特に変数をパイプラインのトリガー変数と一緒に使うと便利に使えます。

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

Each expression provided is going to be evaluated before creating a pipeline.

If any of the conditions in `variables` evaluates to truth when using `only`,
a new job is going to be created. If any of the expressions evaluates to truth
when `except` is being used, a job is not going to be created.

This follows usual rules for [`only` / `except` policies][builds-policies].

### Supported syntax

Below you can find supported syntax reference:

1. Equality matching using a string

    > Example: `$VARIABLE == "some value"`

    You can use equality operator `==` to compare a variable content to a
    string. We support both, double quotes and single quotes to define a string
    value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'`
    are supported. `"some value" == $VARIABLE` is correct too.

1. Checking for an undefined value

    > Example: `$VARIABLE == null`

    It sometimes happens that you want to check whether a variable is defined
    or not. To do that, you can compare a variable to `null` keyword, like
    `$VARIABLE == null`. This expression is going to evaluate to truth if
    variable is not defined.

1. Checking for an empty variable

    > Example: `$VARIABLE == ""`

    If you want to check whether a variable is defined, but is empty, you can
    simply compare it against an empty string, like `$VAR == ''`.

1. Comparing two variables

    > Example: `$VARIABLE_1 == $VARIABLE_2`

    It is possible to compare two variables. This is going to compare values
    of these variables.

1. Variable presence check

    > Example: `$STAGING`

    If you only want to create a job when there is some variable present,
    which means that it is defined and non-empty, you can simply use
    variable name as an expression, like `$STAGING`. If `$STAGING` variable
    is defined, and is non empty, expression will evaluate to truth.
    `$STAGING` value needs to a string, with length higher than zero.
    Variable that contains only whitespace characters is not an empty variable.

1. Pattern matching  _(added in 11.0)_

    > Example: `$VARIABLE =~ /^content.*/`

    It is possible perform pattern matching against a variable and regular
    expression. Expression like this evaluates to truth if matches are found.

    Pattern matching is case-sensitive by default. Use `i` flag modifier, like
    `/pattern/i` to make a pattern case-insensitive.

[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI variables"
[eep]: https://about.gitlab.com/pricing/ "Available only in GitLab Premium"
[envs]: ../environments.md
[protected branches]: ../../user/project/protected_branches.md
[protected tags]: ../../user/project/protected_tags.md
[runner]: https://docs.gitlab.com/runner/
[shellexecutors]: https://docs.gitlab.com/runner/executors/
[triggered]: ../triggers/README.md
[triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger
[subgroups]: ../../user/group/subgroups/index.md
[builds-policies]: ../yaml/README.md#only-and-except-complex
[gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token
[registry]: ../../user/project/container_registry.md
[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories