dotenv変数を特定のジョブに渡す

環境変数を他のジョブに渡すには、dotenvファイルを使用します。dotenvファイルは、.env拡張子を持つファイルで、環境変数のキーと値のリストを格納します。たとえば、sample.envファイルの場合:

REVIEW_URL=review.example.com/123456
BUILD_VERSION=v1.0.0

dotenvファイルをdotenvレポートアーティファクトとして保存します。これは、同じパイプライン内の他のジョブ、ダウンストリームパイプラインに渡したり、動的な環境変数URLを設定したりできます。

dotenv変数は以下の方法で使用できます:

• 1つのジョブで値を生成し、後続のジョブで使用します。
• パイプラインステージ間で計算された値を渡します。
• デプロイの出力に基づいて動的な環境変数URLを設定します。
• 複数プロジェクトのパイプライン間で変数を共有します。

dotenv変数はジョブスクリプトでのみ使用でき、パイプラインの設定には使用できません。それらはジョブ変数や.gitlab-ci.ymlで定義されたデフォルト変数よりも優先されますが、プロジェクト、グループ、インスタンス、またはパイプライン変数よりも優先されることはありません。

同じ変数名がdotenvレポートに複数回出現する場合、最後の値が使用されます。

変数を以降のジョブに渡す

デフォルトでは、dotenv変数は以降のすべてのステージのジョブで利用可能です。ジョブ間で変数を渡すには:

1. ジョブで、VARIABLE_NAME=valueの形式で変数を含むファイル（たとえば、build.env）を、1行に1つの変数ずつ作成します。
2. ファイルをdotenvレポートアーティファクトとして出力します。
3. 以降のジョブで、スクリプト内の変数を使用します。

たとえば、build-jobはBUILD_VERSION=v1.0.0を含むbuild.envを作成し、test-jobはそれを環境変数として自動的に受け取ります:

build-job:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

test-job:
  stage: test
  script:
    - echo "Testing version $BUILD_VERSION"  # Output: 'Testing version v1.0.0'

どのジョブがdotenv変数を受け取るかを制御する

どのジョブがdotenv変数を受け取るかを制御するには、dependenciesまたはneedsキーワードを使用します。

特定のジョブから継承する

特定のジョブのみに継承を制限するには、dependenciesを使用します:

build-job1:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

build-job2:
  stage: build
  script:
    - echo "This job has no dotenv artifacts"

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: 'v1.0.0'
  dependencies:
    - build-job1
    # build-job2 is not listed, so its artifacts are not inherited

dotenv変数を除外する

名前付きジョブからジョブがdotenv変数を受け取るのを防ぐには、needsとartifacts: falseを使用します。これにより、そのジョブからのすべてのアーティファクトのダウンロードがdotenv変数だけでなくブロックされます:

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: '' (empty)
  needs:
    - job: build-job1
      artifacts: false

この例のneedsは、build-job1が完了するとすぐにジョブを開始させます。

または、空のdependencies配列を使用して、すべてのアップストリームジョブからのアーティファクトのダウンロードをブロックします:

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: '' (empty)
  dependencies: []

ダウンストリームパイプラインに変数を渡す

dotenv変数の継承によって、dotenv変数をダウンストリームパイプラインに渡すことができます。マルチプロジェクトパイプラインで、アップストリームジョブにdotenvアーティファクトを作成し、ダウンストリームジョブでneedsを使用して継承します:

1. .envファイルに変数を保存します。
2. .envファイルをdotenvレポートアーティファクトとして保存します。
3. ダウンストリームパイプラインをトリガーします。

build_vars:
  stage: build
  script:
    - echo "BUILD_VERSION=hello" >> build.env
  artifacts:
    reports:
      dotenv: build.env

deploy:
  stage: deploy
  trigger: my/downstream_project

ダウンストリームパイプラインで、needsを使用してアップストリームジョブからアーティファクトを継承するようにジョブを設定します。そのジョブはdotenv変数を受け取り、スクリプトでBUILD_VERSIONにアクセスできます:

test:
  stage: test
  script:
    - echo $BUILD_VERSION
  needs:
    - project: my/upstream_project
      job: build_vars
      ref: master
      artifacts: true

動的な環境URLを設定する

デプロイメントジョブの完了後に、dotenv変数を使用して動的な環境変数URLを設定できます。これは、外部のホスティングプラットフォームがデプロイごとに動的にURLを生成する場合に便利です。

詳細については、動的環境変数URLの設定を参照してください。

複雑な値を格納する

dotenvファイルには、複数行の値やエスケープが必要な特殊文字に対する制限など、特定のフォーマット上の制限があります。値にJSONが含まれている場合、複数行にわたる場合、またはエスケープが必要な文字が含まれている場合は、dotenv変数の使用を避けてください。代わりに、別のファイルアーティファクトを使用してください。値の制約の完全なリストについては、フォーマット要件を参照してください。

使用しない:

# Not supported
- echo 'CONFIG={"key": "value"}' >> build.env

別個のアーティファクトを使用します:

build-job:
  stage: build
  script:
    - echo '{"key": "value"}' > config.json
  artifacts:
    paths:
      - config.json

Dotenvファイルの要件

dotenvファイルは、以下のフォーマット、サイズ、および変数の要件を満たす必要があります。

GitLabは、dotenv gemを使用してdotenvファイルを処理しますが、元のdotenvルールとgemの実装を超えた追加の制限を適用します。

フォーマット要件

• UTF-8エンコードのみがサポートされています。
• ファイルには空行やコメント（#で始まる行）を含めることはできません。
• 変数名には、ASCII文字（A-Za-z）、数字（0-9）、およびアンダースコア（_）のみを含めることができます。
• dotenvファイルはクォーティングをサポートしていません。シングルクォーテーションまたはダブルクォーテーションはそのまま保持され、エスケープには使用できません。
• 値には改行やその他のエスケープが必要な特殊文字を含めることはできません。
• 複数行の値はサポートされていません。GitLabはアップロード時にファイルを拒否します。
• 先頭および末尾のスペースまたは改行文字（\n）は削除されます。

サイズと変数の制限

GitLab.comのティア制限については、GitLab.com CI/CD設定を参照してください。

GitLab Self-Managedでこれらの制限を変更するには、CI/CD制限を参照してください。