ドキュメントに関する現在のご利用体験についてお聞かせください。アンケートにご協力ください。

GitLab Duo Agent Platformのトラブルシューティング

GitLab Duo Agent Platformを使用している場合、次の問題が発生する可能性があります。

ログを表示する

フローが作成された後、AI > セッションに移動してフローのセッションを表示できます。

詳細タブには、CI/CDジョブログへのリンクが表示されます。これらのログには、トラブルシューティング情報が含まれている場合があります。

UIにフローが表示されない

フローを実行しようとしてもGitLab UIに表示されない場合、次のことを確認してください:

プロジェクトのデベロッパーロール以上を持っている。
GitLab Duoがオンになっており、フローの実行が許可されている。
あなたがいるグループがフローを使用する許可を与えられていることを確認してください。
トップレベルグループが正しく設定されているにもかかわらず、個々のプロジェクトでフローが表示されない場合:
1. プロジェクトに移動します。
2. AI > フローを選択します。
3. 右上隅で、グループからのフローを有効にするを選択します。
4. フローを選択し、有効を選択します。
それでも動作しない場合は、次の手順を試してください:
1. トップレベルグループで該当するフローを無効にし、設定を保存します。
2. トップレベルグループで該当するフローを有効にし、設定を保存します。
3. 設定がグループ全体に反映されるまで、数分待ちます。

インポートされたプロジェクト用の新しいパイプラインを作成する権限が不十分です

インポートされたプロジェクトまたはテンプレートから作成されたプロジェクトで基本フローを実行しようとすると、次のエラーが表示されることがあります: Error in creating workload: Insufficient permissions to create a new pipeline

この問題を解決するには:

トップレベルグループに移動します。
設定 > 一般を選択します。
GitLab Duoの機能を展開します。
フローの実行で、有効にしたい基本フローを特定します。
トップレベルグループでフローを無効にし、設定を保存します。
トップレベルグループで同じフローを有効にし、設定を保存します。
グループ内のプロジェクト全体に設定が反映されるまで数分待ちます。

エラー: `Your request was valid but Workflow failed to complete it`

フローには、プロジェクトリポジトリに少なくとも1つのコミットが必要です。コミットがないプロジェクトでフローを実行すると、次のエラーが表示されます: Your request was valid but Workflow failed to complete it. Please try again.

このエラーは、フローがコミットのないリポジトリでデフォルトブランチを見つけられないために発生します。

この問題を修正するには、フローを実行する前に初期コミットをプロジェクトにプッシュする必要があります。たとえば、README.mdファイルを追加します。

セッションが作成済みステータスで停止している

フローのセッションが開始されない場合、次のことを確認してください:

プッシュルールが設定されていること。

サービスアカウントを許可するようにプッシュルールを設定する

GitLab UIでは、基本フローは次の操作を行うサービスアカウントを使用します:

独自のメールアドレスでコミットを作成します。
ワークロードパイプラインを作成します。

前提条件:

管理者アクセス権。

プロジェクトのプッシュルールを設定するには:

サービスアカウントに関連付けられたメールアドレスを見つけます:
1. 右上隅で、管理者を選択します。
2. 概要 > ユーザーを選択し、フローに関連付けられたアカウントを検索します。アカウントはduo-[flow-name]-[top-level-group-name]のパターンに従います。
3. サービスアカウントのユーザーを見つけ、メールアドレスをコピーします。
メールアドレスによるプロジェクトへのプッシュを許可します:
1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > リポジトリを選択します。
3. プッシュルールを展開します。
4. コミットの作成者のメールで、先ほどコピーしたメールアドレスを許可する正規表現を追加します。
5. プッシュルールを保存を選択します。
duo/feature/ブランチプレフィックスを許可します:
1. プッシュルールセクションで、ブランチ名を見つけます。
2. ^duo/(fix|feature|refactor|docs/).* で始まるブランチを許可する正規表現を追加します。例: ^(duo/feature)/.*$
3. プッシュルールを保存を選択します。

インスタンスのプッシュルールを作成するには:

右上隅で、管理者を選択します。
左サイドバーで、プッシュルールを選択します。
前の手順に従って、コミットの作成者のメールとブランチ名を許可します。
プッシュルールを保存を選択します。

フローのジョブが開始しない、または`Starting job`でスタックしている

フローのジョブが開始しない、またはStarting jobでスタックしている場合、ジョブをピックアップできるRunnerがありません。フローは、次の要件を満たすRunnerで実行されます:

Runnerにはgitlab--duoタグがあります。
Runnerは、docker、docker-autoscaler、またはkubernetesのようなDockerイメージをサポートするexecutorを使用します。shell executorはサポートされていません。
Runnerは、インスタンスRunnerまたはトップレベルグループに割り当てられたグループRunnerです。サブグループまたはプロジェクトにスコープ設定されたRunnerは、duo_runner_restrictions機能フラグが無効になっていない限り、フローのジョブをピックアップしません。

この問題を解決するには、次の手順に従います:

GitLab.comで、hosted runnersがプロジェクトで有効になっていることを確認します。ホストされたRunnerは、デフォルトですべての要件を満たします。
独自のRunnerを使用する場合は、少なくとも1つのRunnerが要件を満たしていることを確認します:
1. トップバーで、検索または移動先を選択し、プロジェクトまたはトップレベルグループを見つけます。
2. 左サイドバーで、ビルド > Runnersを選択します。
3. gitlab--duoタグを持つRunnerがオンラインであることを確認します。
要件を満たすRunnerがない場合は、configure a runner to execute flows。

エラー: `Something went wrong while requesting a review from GitLab Duo`

GitLab 18.8以前では、このエラーメッセージはコードレビューフローの失敗に対して表示されます。一般的な根本原因は次のとおりです:

基本フローのサービスアカウントが作成されていませんでした。
グループメンバーシップロックにより、サービスアカウントがプロジェクトに追加されません。
複数のGitLab Duoネームスペースに属しており、デフォルトのネームスペースが設定されていません。

GitLab 18.9以降では、より具体的なエラーメッセージが表示されます。詳細については、troubleshooting Code Review Flowを参照してください。

基本フローのサービスアカウントが作成されていません

基本フローが有効になっているのに機能しない場合、トップレベルグループのサービスアカウントが正常に作成されていない可能性があります。

サービスアカウントが存在するかどうかを確認するには:

上部のバーで検索または移動先を選択して、トップレベルグループを見つけます。
左サイドバーで、設定 > Service Accountsを選択します。
duo-[flow-name]-[top-level-group-name]という名前のアカウントを探します。

アカウントが見つからない場合、CascadeSyncFoundationalFlowsWorkerはそれを作成することに失敗した可能性があります。アカウントが見つからないことを確認するには、Sidekiqログで次のエラーを確認します:

{
  "severity": "ERROR",
  "meta.caller_id": "Ai::Catalog::Flows::CascadeSyncFoundationalFlowsWorker",
  "message": "Cannot obtain an exclusive lease. There must be another instance already in execution.",
  "lease_key": "sidekiq:concurrency_limit:{ai/catalog/flows/cascade_sync_foundational_flows_worker}",
  "lease_timeout": 600
}

この問題を解決するには、turn off foundational flowsしてから10分後に再度有効にします。

グループメンバーシップがロックされました

トップレベルグループのmembership is lockedされている場合、サービスアカウントが必要なプロジェクトに追加できないため、基本フローはサイレントに失敗します。

この問題を解決するには、次の手順に従います:

上部のバーで検索または移動先を選択して、トップレベルグループを見つけます。
左側のサイドバーで、設定 > 一般を選択します。
権限とグループ機能を展開します。
このグループのプロジェクトにユーザーを追加することはできませんチェックボックスをオフにしてから、変更を保存を選択します。
Turn off foundational flowsを選択し、次に変更を保存を選択します。
基本フローを再度有効にしてから、変更を保存を選択します。
このグループのプロジェクトにユーザーを追加することはできませんチェックボックスを選択し、次に変更を保存を選択します。

デフォルトのGitLab Duoネームスペースが設定されていません

GitLab 18.3以降では、複数のGitLab Duoネームスペースに属しており、デフォルトのネームスペースが設定されていない場合、GitLab Duo Agent Platformは無効になります。

GitLab 18.8以前では、次のエラーメッセージが表示される場合があります:

Something went wrong while requesting a review from GitLab Duo.

GitLab 18.9以降では、ネームスペース関連のエラーが発生する場合があります。

この問題を解決するには、set a default GitLab Duo namespace。

エラー: `SSL certificate OpenSSL verify result: unable to get local issuer certificate (20)`

カスタムまたは自己署名CA証明書を使用するGitLab Self-Managedインスタンスでは、GitLab Duo Agent Platformのジョブが最初のgit clone（get_sourcesフェーズ）中に失敗すると、このメッセージが表示される場合があります。

これは、GitLab Duo Agent PlatformのジョブがGIT_CONFIG_GLOBAL=/dev/nullとGIT_CONFIG_NOSYSTEM=1を設定してエージェントサンドボックスを強化するためです。これらの変数は、Gitがシステムおよびグローバルな設定ファイルを読み取るのを防ぎます。これにより、Runnerのget_sources中のCA証明書パスを注入するメカニズムが破損します。

CI/CDのジョブがフローを実行しない場合は影響を受けません。この問題は、GitLab Duo Agent Platformのワークロードパイプラインに固有のものです。

この問題を解決するには、config.tomlファイルで、GIT_SSL_CAINFO環境変数をRunnerレベルで設定し、CA証明書をコンテナにマウントします:

[[runners]]
  environment = ["GIT_SSL_CAINFO=/etc/gitlab-runner/certs/ca.crt"]
  [runners.docker]
    volumes = ["/path/to/your/ca-bundle.crt:/etc/gitlab-runner/certs/ca.crt:ro"]

/path/to/your/ca-bundle.crtをRunnerホスト上のCA証明書バンドルへのパスに置き換えます。このファイルは、ルートCAおよびすべての中間証明書を含むPEM形式のCAバンドルである必要があります。

これをCI/CD変数として設定することを期待するかもしれませんが、カスタムCI/CD変数はGitLab Duo Agent Platformのジョブではnot availableです。代わりに、Runnerのconfig.toml environmentディレクティブを使用する必要があります。

GitLab Duo CLIをカスタムCA経由でGitLabインスタンスに接続するには、NODE_EXTRA_CA_CERTSを同じenvironment行に追加します:

[[runners]]
  environment = [
    "GIT_SSL_CAINFO=/etc/gitlab-runner/certs/ca.crt",
    "NODE_EXTRA_CA_CERTS=/etc/gitlab-runner/certs/ca.crt"
  ]
  [runners.docker]
    volumes = ["/path/to/your/ca-bundle.crt:/etc/gitlab-runner/certs/ca.crt:ro"]

GitLab Duo CLIがAnthropic Sandbox Runtime（SRT）で実行されている場合、Runner environment変数は到達しない可能性があります。この変更後もTLSエラーが続く場合は、agent-config.ymlのsetup_scriptで、代わりにNODE_EXTRA_CA_CERTSを設定します。setup_scriptはコンテナ内で実行され、サンドボックスによってフィルタリングされません。

GIT_SSL_CAINFO変数は、GitLab Duo CLIが起動する前に発生するGit操作に対処します。GitLab Duo CLIの証明書設定については、certificate errorsを参照してください。

WebSocketエラー`1006`または`404`で接続が失敗します

GitLab Duo CLI、GitLab言語サーバー、およびIDEクライアント（GitLab for VS Code、JetBrains IDE用GitLab Duoプラグイン、およびGitLab for Visual Studio）は、WebSocket接続を介してGitLab Duo Agent Platformに接続します。この接続が失敗すると、クライアントは次のいずれかのエラーをログに記録します:

1006: WebSocketは、クローズハンドシェイクなしで異常終了しました。
404: クライアントは次のWebSocketエンドポイントに到達できません:
- GitLab Duo非エージェント型: /-/cable。
- GitLab Duo Agent Platform: wss://\<instance\>/api/v4/ai/duo_workflows/ws。

これらのエラーは通常、カスタム認証局（CA）、HTTPプロキシ、TLS検査プロキシ、またはネットワーク上の相互TLS（mTLS）プロキシが接続を妨げるときに発生します。この問題を解決するには、次の原因を確認してください。

カスタムCA証明書

ネットワークがカスタムまたは自己署名CA証明書を使用している場合、クライアントはGitLabインスタンスへの接続を検証できません。クライアントの証明書を設定します:

GitLab Duo CLIの場合は、NODE_EXTRA_CA_CERTS環境変数をCA証明書のパスに設定します。
IDEクライアントの場合、GitLab言語サーバーが証明書を管理します。JetBrains IDEの場合は、certificate errorsを参照してください。VS Codeの場合は、errors with custom certificatesを参照してください。

HTTPプロキシ

ネットワークがHTTPプロキシを必要とする場合は、クライアントのプロキシを設定します:

GitLab Duo CLIの場合は、HTTP_PROXY、HTTPS_PROXY、およびNO_PROXY環境変数を設定します。
IDEクライアントの場合は、configure the Language Server to use a proxy。

WebSocketトラフィックがブロックされました

404エラー、またはログに/-/cable WebSocketエンドポイントの代わりにHTTP/1.1応答が表示される場合、GitLabインスタンスが受信WebSocket接続をブロックしている可能性があります。管理者に、allow WebSocket traffic to your GitLab instanceを依頼してください。

mTLSまたはTLS検査プロキシ

ネットワークがTLS検査（SSLインターセプション）プロキシを介してトラフィックをルーティングする場合、次の両方を設定します:

HTTPS_PROXY環境変数をプロキシURLに設定します。
プロキシのCA certificateを追加します。

GitLab Duo CLI、JetBrains IDE用GitLab Duoプラグイン、およびGitLab for Visual Studioには、2つの既知の問題があります:

プロキシURLがhttps://を使用している場合、WebSocket接続は失敗します。可能であれば、http://プロキシURLを使用します。
これらのクライアントは、mTLS用のクライアント証明書を提示できません。

詳細については、issue 2527を参照してください。GitLab for VS Codeは影響を受けません。

IDEでのトラブルシューティング

IDEでGitLab Duo Agent Platformを使用中に問題が発生した場合は、GitLab Duoがオンになっており、適切に接続されていることを確認することから始めます。

GitLab Duo Agent Platformのprerequisitesを満たしています。
管理者モードはdisabledです。
プロジェクトはgroup namespaceにあります。
default GitLab Duo namespaceが設定されているか、GitLab Duoアクセス権のあるプロジェクトを開いています。

詳細なサポートについては、拡張機能とIDEのトラブルシューティングページを参照してください:

設定診断スクリプトを実行する

関連する機能ドキュメントからGitLab Duo Agent Platformの問題の原因を特定できない場合は、診断スクリプトを実行して設定を確認します。

このスクリプトは、GitLab Duo Agent Platform機能に必要な完全な設定チェーンをチェックします:

ライセンスの有効性とプラン。
インスタンスレベルのGitLab Duo設定。
gitlab--duoタグを持つCI/CD Runner。
ネームスペースおよびプロジェクトのGitLab Duo設定。
基本フローとそのサービスアカウント。
コードレビューフローの可用性や自動レビュー設定などの機能の利用可能性。

このスクリプトは設定データのみを読み取り、設定を変更しません。出力には内部設定の詳細が含まれる場合があります。サポートと共有する前に、出力をサニタイズしてください。