CI/CDパイプラインのデバッグ

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GitLabには、CI/CD設定のデバッグを容易にするためのツールがいくつか用意されています。

パイプラインの問題を解決できない場合は、以下からヘルプを得られます:

特定のCI/CD機能で問題が発生している場合は、その機能に関するトラブルシューティングのセクションを参照してください:

デバッグ手法

構文を検証する

問題の初期段階の原因は、不適切な構文である可能性があります。構文またはフォーマットの問題が見つかった場合、パイプラインにはyaml invalidバッジが表示され、実行が開始されません。

`.gitlab-ci.yml`をパイプラインエディタで編集

パイプラインエディタは、（シングルファイルエディタやWeb IDEではなく）推奨される編集エクスペリエンスです。これには以下が含まれます:

受け入れられたキーワードのみを使用するためのコード補完の提案。
自動構文ハイライトと検証。
CI/CD設定の可視化、.gitlab-ci.ymlファイルのグラフィカルな表現。

`.gitlab-ci.yml`をローカルで編集する

パイプライン設定をローカルで編集する場合は、エディタでGitLab CI/CDスキーマを使用して構文の基本的な問題を検証できます。SchemaStoreをサポートするエディタでは、デフォルトでGitLab CI/CDスキーマが使用されます。

スキーマに直接リンクする必要がある場合は、次のURLを使用します:

https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/editor/schema/ci.json

CI/CDスキーマでカバーされるカスタムタグの完全なリストを表示するには、スキーマの最新バージョンを確認してください。

CI Lintツールで構文を検証する

CI Lintツールを使用すると、CI/CD設定スニペットの構文が正しいことを検証できます。基本的な構文を検証するために、完全な.gitlab-ci.ymlファイルまたは個々のジョブ設定を貼り付けます。

プロジェクトに.gitlab-ci.ymlファイルが存在する場合は、CI Lintツールを使用して完全なパイプラインの作成をシミュレートすることもできます。これにより、設定構文をより深く検証できます。

パイプライン名を使用する

workflow:nameを使用してすべてのパイプラインタイプに名前を付けると、パイプラインリストでパイプラインを簡単に識別できます。次に例を示します:

variables:
  PIPELINE_NAME: "Default pipeline name"

workflow:
  name: '$PIPELINE_NAME'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PIPELINE_NAME: "Merge request pipeline"
    - if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPELINE_SCHEDULE_TYPE == "hourly_deploy"'
      variables:
        PIPELINE_NAME: "Hourly deployment pipeline"
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      variables:
        PIPELINE_NAME: "Other scheduled pipeline"
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      variables:
        PIPELINE_NAME: "Default branch pipeline"
    - if: '$CI_COMMIT_BRANCH =~ /^\d{1,2}\.\d{1,2}-stable$/'
      variables:
        PIPELINE_NAME: "Stable branch pipeline"

CI/CD変数

変数を検証する

CI/CDのトラブルシューティングの重要な部分は、どの変数がパイプラインに存在していて、どのような値を持っているか検証することです。パイプライン設定の多くは変数に依存しており、それらを検証することは、問題の原因を特定するための最も迅速な方法の1つです。

問題のある各ジョブで利用可能な変数の完全なリストをエクスポートします。予期される変数が存在するかどうかを確認し、それらの値が予想どおりであるかどうかを確認します。

変数を使用してCLIコマンドにフラグを追加する

標準のパイプライン実行では使用されないが、オンデマンドでデバッグに使用できるCI/CD変数を定義できます。次の例のように変数を追加すると、パイプラインまたは個々のジョブの手動実行中に変数を追加して、コマンドの動作を変更できます。次に例を示します:

my-flaky-job:
  variables:
    DEBUG_VARS: ""
  script:
    - my-test-command $DEBUG_VARS /test-dirs

この例では、DEBUG_VARSは標準のパイプラインではデフォルトで空白です。ジョブの動作をデバッグする必要がある場合は、パイプラインを手動で実行し、追加の出力のためにDEBUG_VARSを--verboseに設定します。

依存関係

依存関係に関連する問題は、パイプラインで予期しない問題が発生するもう1つの一般的な根本原因です。

依存関係のバージョンを検証する

ジョブで正しいバージョンの依存関係が使用されていることを検証するには、メインスクリプトコマンドを実行する前に依存関係を出力します。次に例を示します:

job:
  before_script:
    - node --version
    - yarn --version
  script:
    - my-javascript-tests.sh

バージョンを固定する

依存関係やイメージの最新バージョンを常に使用したいと思うかもしれませんが、アップデートには予期しない破壊的な変更が含まれる可能性があります。予期しない変更を避けるために、主要な依存関係とイメージを固定することを検討してください。次に例を示します:

variables:
  ALPINE_VERSION: '3.18.6'

job1:
  image: alpine:$ALPINE_VERSION  # This will never change unexpectedly
  script:
    - my-test-script.sh

job2:
  image: alpine:latest  # This might suddenly change
  script:
    - my-test-script.sh

重要なセキュリティアップデートが含まれている可能性があるため、依存関係とイメージのアップデートを定期的に確認する必要があります。その後、アップデートされたイメージや依存関係がパイプラインで引き続き動作することを検証するプロセスの一環として、バージョンを手動でアップデートできます。

ジョブ出力を検証する

出力を冗長にする

--silentを使用してジョブログの出力量を減らすと、ジョブで何が問題になったのかを特定することが難しくなる可能性があります。また、可能な場合は--verboseを使用して、詳細を追加することを検討してください。

job1:
  script:
    - my-test-tool --silent         # If this fails, it might be impossible to identify the issue.
    - my-other-test-tool --verbose  # This command will likely be easier to debug.

出力とレポートをアーティファクトとして保存する

一部のツールは、ジョブの実行中にのみ必要となるファイルを生成しますが、これらのファイルの内容をデバッグに使用できる場合があります。artifactsを使って後で分析するために、それらのファイルを保存することができます:

job1:
  script:
    - my-tool --json-output my-output.json
  artifacts:
    paths:
      - my-output.json

artifacts:reportsで設定されたレポートは、デフォルトではダウンロードできませんが、デバッグに役立つ情報を含んでいる可能性もあります。これらのレポートを検査可能にするには、同じ手法を使用します:

job1:
  script:
    - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml
    paths:
      - rspec.xmp

トークン、パスワード、その他の機密情報は、アーティファクトに保存しないでください。パイプラインへのアクセス権を持つすべてのユーザーが閲覧できる可能性があります。

ジョブのコマンドをローカルで実行する

Rancher Desktopなどのツールまたは類似の代替手段を使用して、ジョブのコンテナイメージをローカルマシンで実行できます。その後、コンテナでジョブのscriptコマンドを実行し、動作を検証します。

根本原因分析を通じて失敗したジョブの問題を解決する

GitLab Duo ChatのGitLab Duo根本原因分析を使用すれば、失敗したCI/CDジョブの問題を解決することができます。

ジョブ設定の問題

ジョブをパイプラインに追加するタイミングを制御するために使用されるrulesまたはonly/exceptの設定の動作を分析することで、パイプラインの一般的な問題の多くを修正できます。これらの2つの設定は動作が異なるため、同じパイプラインで使用しないでください。この混合動作でパイプラインがどのように実行されるかを予測することは困難です。onlyとexceptは積極的に開発されなくなったため、ジョブを制御するには、rulesが望ましい選択肢になります。

rulesまたはonly/exceptの設定で定義済み変数（CI_PIPELINE_SOURCEやCI_MERGE_REQUEST_IDなど）を使用する場合は、トラブルシューティングの最初の手順としてそれらを検証する必要があります。

ジョブまたはパイプラインが予期したときに実行されない

rulesまたはonly/exceptキーワードにより、ジョブをパイプラインに追加するかどうかが決定されます。パイプラインは実行されるのに、ジョブがパイプラインに追加されない場合、通常はrulesまたはonly/exceptの設定問題が原因です。

エラーメッセージが表示されず、パイプラインがまったく実行されないように見える場合も、rulesまたはonly/exceptの設定、またはworkflow: rulesキーワードが原因である可能性があります。

only/exceptからrulesキーワードに変換している場合は、rulesの設定の詳細を注意深く確認する必要があります。only/exceptとrulesの動作は異なり、これらの2つの間で移行すると、予期しない動作が発生する可能性があります。

rulesの一般的なif句は、期待どおりに動作するルールを記述する方法の例として非常に有用です。

パイプラインに.preステージまたは.postステージのジョブのみが含まれている場合、パイプラインは実行されません。別のステージに少なくとも1つのジョブが必要です。

`.gitlab-ci.yml`ファイルにバイトオーダーマーク（BOM）が含まれている場合の予期しない動作

.gitlab-ci.ymlファイルまたはその他のインクルードされた設定ファイルにあるUTF-8バイトオーダーマーク（BOM）は、パイプラインの誤った動作の原因となる可能性があります。バイトオーダーマークはファイルの解析に影響を与え、設定の一部が無視される原因となります。ジョブが欠落したり、変数が誤った値を持ったりする可能性があります。一部のテキストエディタがBOM文字を挿入する（そのように設定されている場合）可能性があります。

パイプラインの動作がわかりにくい場合は、BOM文字を表示できるツールを使用して、BOM文字の存在を確認できます。パイプラインエディタは文字を表示できないため、外部ツールを使用する必要があります。詳細については、イシュー354026を参照してください。

`changes`キーワードを持つジョブが予期せずに実行される

ジョブがパイプラインに予期せずに追加される一般的な理由の1つは、特定の場合にchangesキーワードが常にtrueと評価されるためです。たとえば、changesは、スケジュールされたパイプラインやタグのパイプラインなど、特定のパイプラインタイプでは常にtrueです。

changesキーワードは、only/exceptまたはrulesと組み合わせて使用されます。changesは、ジョブがブランチパイプラインまたはマージリクエストパイプラインにのみ追加されるようにするrulesまたはonly/exceptの設定のifセクションでのみ使用することをお勧めします。

2つのパイプラインが同時に実行される

関連付けられているオープンマージリクエストを持つブランチにコミットをプッシュすると、2つのパイプラインが実行される可能性があります。通常、一方のパイプラインはマージリクエストパイプラインであり、もう一方のパイプラインはブランチパイプラインです。

この状況は通常、rules設定が原因であり、重複したパイプラインを防ぐ方法がいくつかあります。

パイプラインが実行されないか、間違ったタイプのパイプラインが実行される

パイプラインが実行できるようになる前に、GitLabは設定内のすべてのジョブを評価し、使用可能なすべてのパイプラインタイプにジョブを追加することを試みます。評価が終わったときにジョブが追加されない場合、パイプラインは実行されません。

パイプラインが実行されなかった場合は、すべてのジョブにrulesまたはonly/exceptがあり、そのためにパイプラインに追加されなかった可能性があります。

間違ったパイプラインタイプが実行された場合は、rulesまたはonly/exceptの設定を確認して、ジョブが正しいパイプラインタイプに追加されるようにする必要があります。たとえば、マージリクエストパイプラインが実行されなかった場合は、ジョブがブランチパイプラインに追加された可能性があります。

workflow: rulesの設定がパイプラインをブロックしたか、間違ったパイプラインタイプを許可した可能性もあります。

プルミラーリングを使用している場合は、プルミラーリングパイプラインのトラブルシューティングエントリを確認してください。

ジョブ数の多いパイプラインが開始に失敗する

インスタンスで定義されたCI/CDの制限を超えるジョブを持つパイプラインは、開始に失敗します。

単一のパイプラインのジョブ数を減らすには、.gitlab-ci.ymlの設定を、より独立した親子パイプラインに分割できます。

パイプラインの警告

パイプライン設定の警告は、以下を行った場合に表示されます:

`Job may allow multiple pipelines to run for a single action`警告

if句のないwhen句でrulesを使用すると、複数のパイプラインが実行される可能性があります。通常、これは、関連付けられているオープンマージリクエストを持つブランチにコミットをプッシュすると発生します。

重複したパイプラインを防ぐには、workflow: rulesを使用するか、ルールを書き換えて、実行できるパイプラインを制御します。

パイプラインのエラー

`A CI/CD pipeline must run and be successful before merge`メッセージ

プロジェクトでパイプラインが完了している設定が有効になっており、パイプラインがまだ正常に実行されていない場合、このメッセージが表示されます。これは、パイプラインがまだ作成されていない場合、または外部CIサービスを待機している場合にも当てはまります。

プロジェクトでパイプラインを使用しない場合は、パイプラインが完了しているを無効にして、マージリクエストを受け入れることができるようにする必要があります。

`Checking ability to merge automatically`メッセージ

マージリクエストがChecking ability to merge automaticallyメッセージで停止し、メッセージが数分後に消えない場合は、次の回避策のいずれかを試すことができます:

マージリクエストページを更新します。
マージリクエストを閉じて再度開きます。
/rebaseクイックアクションを使用して、マージリクエストをリベースします。
マージリクエストをマージする準備ができていることをすでに確認している場合は、/mergeクイックアクションを使用してマージできます。

この問題は、GitLab 15.5で解決されました。

`Checking pipeline status`メッセージ

マージリクエストが、最新のコミットに関連付けられたパイプラインをまだ持っていない場合、このメッセージは回転状態アイコン（）とともに表示されます。これには次の原因が考えられます:

GitLabがまだパイプラインの作成を完了していない。
外部CIサービスが使用されていて、GitLabはそのサービスからの返信をまだ受け取っていない。
プロジェクトでCI/CDパイプラインを使用していない。
プロジェクトでCI/CDパイプラインを使用しているが、設定によってマージリクエストのソースブランチでパイプラインが実行されなくなっている。
最新のパイプラインが削除されている（既知の問題）。
マージリクエストのソースブランチがプライベートフォーク上にある。

パイプラインが作成されると、パイプラインステータスでメッセージが更新されます。

これらのケースの一部では、パイプラインが完了している設定が有効になっている場合、アイコンが延々と回転したままメッセージが動かなくなることがあります。詳細については、イシュー334281を参照してください。

`Project <group/project> not found or access denied`メッセージ

このメッセージは、includeで設定が追加されており、次のいずれかの条件に当てはまる場合に表示されます:

設定が、見つからないプロジェクトを参照している。
パイプラインを実行しているユーザーが、含まれているプロジェクトにアクセスできない。

これを解決するには、以下を確認してください:

プロジェクトのパスがmy-group/my-project形式であり、リポジトリにフォルダーが含まれていない。
パイプラインを実行しているユーザーが、含まれているファイルを含むプロジェクトのメンバーである。ユーザーは、同じプロジェクトでCI/CDジョブを実行するための権限も必要です。

`The parsed YAML is too big`メッセージ

このメッセージは、YAML設定が大きすぎるか、ネストが深すぎる場合に表示されます。多数のインクルードを含むYAMLファイル、および全体で数千行のYAMLファイルは、このメモリ制限に達する可能性が高くなります。たとえば、200 KBのYAMLファイルは、デフォルトのメモリ制限に達する可能性があります。

設定サイズを縮小するには、次の操作を実行します:

パイプラインエディタの完全な設定タブで、展開されたCI/CD設定の長さを確認します。削除または簡略化できる重複した設定を探します。
長い、または繰り返されるscriptセクションを、プロジェクトのスタンドアロンスクリプトに移動します。
親子パイプラインを使用して、一部の作業を独立した子パイプラインのジョブに移動します。

GitLab Self-Managedでは、サイズ制限を増やすことができます。

`.gitlab-ci.yml`ファイルの編集中に`500`エラーが発生する

インクルードされた設定ファイルのループは、Webエディタで.gitlab-ci.ymlファイルを編集するときに500エラーを引き起こす可能性があります。

インクルードされた設定ファイルが、相互の参照のループを作成しないようにしてください。

`Failed to pull image`メッセージ

Runnerは、CI/CDジョブでコンテナイメージをプルしようとして、Failed to pull imageメッセージを返すことがあります。

Runnerは、別のプロジェクトのコンテナレジストリからimageで定義されたコンテナイメージをフェッチする際、CI/CDジョブトークンで認証します。

ジョブトークンの設定で、別のプロジェクトのコンテナレジストリへのアクセスが拒否されている場合、Runnerはエラーメッセージを返します。

次に例を示します:

WARNING: Failed to pull image with policy "always": Error response from daemon: pull access denied for registry.example.com/path/to/project, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

WARNING: Failed to pull image with policy "": image pull failed: rpc error: code = Unknown desc = failed to pull and unpack image "registry.example.com/path/to/project/image:v1.2.3": failed to resolve reference "registry.example.com/path/to/project/image:v1.2.3": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

これらのエラーは、次の両方が当てはまる場合に発生する可能性があります:

イメージをホスティングしているプライベートプロジェクトで、Limit access to this project（このプロジェクトへのアクセスを制限）オプションが有効になっている。
イメージのフェッチを試みるジョブが、プライベートプロジェクトの許可リストにリストされていないプロジェクトで実行されている。

この問題を解決するには、コンテナレジストリからイメージをフェッチするCI/CDジョブを持つプロジェクトを、ターゲットプロジェクトのジョブトークン許可リストに追加します。

これらのエラーは、別のプロジェクトのイメージにアクセスするためにプロジェクトアクセストークンを使用しようとした場合にも発生する可能性があります。プロジェクトアクセストークンは、1つのプロジェクトにスコープが設定されているため、他のプロジェクトのイメージにアクセスできません。より広いスコープで別のトークンタイプを使用する必要があります。

ランダムまたは断続的な`Failed to pull image`エラー

CI/CDジョブで断続的なFailed to pull imageエラーが発生することがあります。

この問題は、イメージにアクセスするユーザーの権限が異なっていることに加えて、Runnerがそれらのイメージをキャッシュする方法が原因で発生する可能性があります。ボットユーザーは他のプロジェクトメンバーとは異なる権限を持っていることが多いため、一般的にボットユーザーが影響を受けます。

たとえば、パイプラインイメージは、別のプロジェクトのコンテナレジストリでホスティングされている可能性があります。すべてのユーザーが両方のプロジェクトにアクセスできる場合、これは問題ではありません。しかし、ユーザー（ボットユーザーなど）が、イメージをホスティングしているプロジェクトにアクセスできない場合、Failed to pull imageエラーが発生する可能性があります。

イメージにアクセスする権限を持つユーザーのためにRunnerがイメージを正常にフェッチしてキャッシュすると、このエラーは断続的になります。このRunnerはイメージを利用できるようになり、別のプロジェクトにアクセスしてイメージをフェッチする必要はなくなりました。他のプロジェクトへのアクセス権限を持たないユーザーを含め、すべてのユーザーがこのイメージでCI/CDジョブを実行できます。ただし、Runnerがイメージをフェッチしてキャッシュしたことがない場合、イメージプロジェクトにアクセスする権限がないユーザーは、Failed to pull imageエラーを受け取ります。

この問題を解決するには、パイプラインを実行するすべてのユーザー（ボットユーザーを含む）が、プルされたイメージをホスティングするプロジェクトにアクセスできるようにする必要があります。

パイプライン実行時の`Something went wrong on our end`メッセージまたは`500`エラー

次のパイプラインエラーが発生する可能性があります:

マージリクエストをプッシュまたは作成すると、Something went wrong on our endメッセージが表示される。
APIを使用してパイプラインをトリガーすると、500エラーが発生する。

これらのエラーは、プロジェクトのインポート後に内部IDのレコードの同期が外れた場合に発生する可能性があります。

これを解決するには、イシュー352382の回避策を参照してください。

`config should be an array of hashes`エラーメッセージ

parallel:matrixキーワードで!referenceタグを使用すると、次のようなエラーが表示される場合があります:

This GitLab CI configuration is invalid: jobs:my_job_name:parallel:matrix config should be an array of hashes.

parallel:matrixキーワードでは、同時に複数の!referenceタグを使用することはサポートされていません。代わりにYAMLアンカーを使用してみてください。

イシュー439828で、parallel:matrixでの!referenceタグのサポートの改善が提案されています。