今回はGitLabCIの環境変数について整理します。

環境変数とは何か

実行中のジョブに渡すことができる変数です。
環境変数を使うと、ymlファイルに値をベタ書きせずに済むので便利です。

事前定義された環境変数

GitLabCIにはデフォルトで定義されている環境変数があります。
ブランチやタグ名・コミットSHA等を準備なしで参照することができます。

数があまりにも多いため(110個あります)、よく使いそうなものだけピックアップして整理します。

CI_COMMIT_REF_NAME
- ジョブが実行されているブランチまたはタグ名を参照する。
CI_COMMIT_REF_SLUG
- CI_COMMIT_REF_NAMEを小文字化して63byteに圧縮したもの。
CI_COMMIT_SHA
- コミットのリビジョン番号を参照する。
CI_COMMIT_BRANCH
- コミットされたブランチ名を指す。
CI_COMMIT_TAG
- コミットされたタグ名を指す。
CI_DEFAULT_BRANCH
- デフォルトブランチ名を指す。
CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
- マージリクエストのソースブランチ名を指す。
CI_MERGE_REQUEST_TARGET_BRANCH_NAME
- マージリクエストのターゲットブランチ名を指す。
CI_PIPELINE_SOURCE
- パイプラインがどのように起動するかを示す。

このうち、CI_PIPELINE_SOURCE は他の変数と比較して複雑なので詳しく見ていきましょう。

CI_PIPELINE_SOURCEの使い方

以下のようにrules句のifで $CI_PIPELINE_SOURCE == "設定値" のようにしてジョブやパイプラインが起動する条件を規定します。


# マージリクエストを作成した時に起動する
job:
 script: echo "にゃーん"
 rules:
   - if:  $CI_PIPELINE_SOURCE == "merge_request_event"

設定値	概要
api	pipelines APIでトリガーする
chat	GitLab ChatOpsコマンドで起動する
external	GitLab以外のCIツールから実行される
external_pull_request_event	GitHubのプルリクエストが作成・更新された時に実行する
merge_request_event	マージリクエストが作成・更新された時に実行する。
parent_pipeline	親パイプラインから実行される。
pipeline	triggerキーワードまたはCI_JOB_TOKENありのAPIから実行される
push	pushしたときに実行される
schedule	定期実行する
trigger	トリガートークンによって起動される
web	GitLabの画面から実行する
webide	WebIDEにより実行する

カスタム環境変数

定義済み環境変数に加えてカスタム環境変数(独自の環境変数)を指定することもできます。

.gitlab-ci.ymlで定義する

variables 句で独自の変数を定義します。
グローバルに変数を定義すると全てのジョブから参照する事が出来ます。


variables:
  API_SERVER: https://hogehoge.com/api/v1/users/

job1:
  script: curl $API_SERVER

job2:
  script: curl -X POST -H "Content-Type: application/json" -d "{"name": "ちいかわ"}" $API_SERVER

ジョブレベルで変数を定義するとそのジョブ内でのみ参照することができます。


job1:
  variables:
    TMP_DIR: ./tmp
  script: ls $TMP_DIR  
    
# 参照不可能
job2:
  script: cat $TMP_DIR/hoge.txt

また、変数から別の変数を展開することも可能です。


job:
  variables:
    HOGE: "aaaa"
    FUGA: $HOGE.txt
  # ルートディレクトリにaaa.txtというファイルが作成される。
  script: touch $FUGA

設定画面で定義する

リポジトリのSetting > CI/CDで変数定義用のセクションを開きます。

Add Variableボタンを押して変数を入力します。

Key: 変数名を入力します。文字・数字・_ のみ利用可能です。
Value: 変数の値を入力します。
Type: FileまたはVariableです。後者を使うことが多いでしょう。
Environment scope: 変数の有効範囲を指定します。基本的にはデフォルトのままで良いです。
Flags
- Protect variable: 保護されたブランチやタグからしか変数を参照できないようにします。
- Mask variable: ログに変数の値がマスクされて出力されるようにします。APIトークン等機密性の高い情報についてはONにしましょう。

画面で定義した環境変数は全てのジョブから参照することができます。

環境変数の優先順位

変数は定義される場所によって優先順位が変わります。
しかし、名前が重複しないように変数を定義すればこの順序を気にしなくても済みます。

トリガー変数・スケジュールされたパイプライン変数・手動パイプライン実行変数
リポジトリ単位の変数またはプロテクトされた変数
グループ単位の変数またはプロテクトされた変数
継承された環境変数
.gitlab-ci.ymlで定義されたジョブ単位の変数
.gitlab-ci.ymlで定義されたグローバルな変数
事前定義された環境変数

環境変数の評価式

パイプラインで実行されるジョブを制御するために評価式を利用することができます。

文字列による等式マッチング

以下の例ではmainブランチにコミットされた時のみjobがパイプラインに追加されます。

# シングルクォート・ダブルクォートのどちらでも可
job:
  script: echo "にゃーん"
  rules:
    if: $CI_COMMIT_BRANCH == "main"

逆に、以下の例ではmain以外のブランチにコミットされた時にjobがパイプラインに追加されます。
(mainブランチにコミットされた時は追加されません。)

# シングルクォート・ダブルクォートのどちらでも可
job:
  script: echo "にゃーん"
  rules:
    if: $CI_COMMIT_BRANCH != "main"

未定義チェック

null と比較すると変数が定義されているかを調べる事が出来ます。
使用頻度はあまり高くないでしょう。

空文字列との比較

$VARIABLE == "" や $VARIABLE == '' のように定義済み変数が空文字列かどうかを
調べることもできます。

2つの変数の比較

$VAR1 == $VAR2 や $VAR3 != $VAR4 で2つの変数の値を比較することができます。
この時、参照先ではなく値が比較されます。

パターンマッチ

正規表現によるパターンマッチを利用可能です。

=~：パターンにマッチした場合に真になる。
!~：パターンにマッチしない場合に真になる。

参考情報

GitLab日本語ドキュメント