更新日: 2026年10月28日

17分で読めます

GitLab Duo Agent Platformを業務システムまで広げる

Salesforceからカスタムフローを呼び出し、エラー発生と同時に根本原因分析付きのGitLabイシューを作成する方法を解説します。修正からデプロイまで、すべてGitLab上で完結します。

デベロッパーがGitLab Duo Agent Platformを使う場所は、たいていIDE、マージリクエスト、イシューといった日々の作業の現場です。一方で、DevSecOpsチームが支えている範囲はそれだけではありません。全社の業務を動かすビジネスシステムもまた、同じように壊れます。

たとえばSalesforceで検証が失敗したとき、コールアウトがタイムアウトしたとき、あるいはnullがトリガーをすり抜けたとき。エラーはログに記録されますが、ログは原因まで説明してくれません。結局エンジニアが、スタックトレースを読み、リポジトリから該当クラスを探し、直近の変更を確認し、単発の事象なのかリグレッションなのかを判断することになります。その間、エラーに遭遇した業務部門のユーザーは待たされたまま。

SalesforceのメタデータをGitLabで管理し、GitLab CI/CDでデプロイしているなら、エラーの原因を説明できるコードはすでに手元にあります。このチュートリアルで作るのは、エラーが発生したその瞬間に、SalesforceがFlows API経由でGitLab Duo Agent Platformのカスタムフローを呼び出す仕組み。フローがコードを調査し、根本原因の分析まで書き込まれた状態のGitLabイシューがチームに届きます。

この仕組みでは、GitLabプラットフォームの3つの要素が連携します。GitLab Duo Agent Platformがエラーを調査し、GitLabイシューが作業を追跡し、GitLab CI/CDがフローを実行して修正をデプロイする。この3つです。

本記事ではSalesforceを例に説明しますが、HTTPリクエストを送信できるシステムであれば、同じやり方が通用します。

構築する仕組みの全体像

SalesforceからGitLabへの呼び出しは1回だけ。あとはGitLab Duo Agent Platformのカスタムフローが引き受けます。

Salesforceのエラーから修正のデプロイまで、1つのプラットフォームで完結

エラーは、Apexのエラーハンドリングから自動的に、あるいはボタンを押してオンデマンドで、GitLab Duo Agent Platformに届きます。どちらの経路でも、呼び出すのは同じApexジョブ。Flows APIを呼び出し、フローが分析結果とともにイシューを作成します。

前提条件

  • GitLab PremiumまたはUltimate(GitLab.com、またはGitLab 19.5以降)。本チュートリアルで使用するFlows APIは、19.5以降で一般提供されています。
  • GitLab Duo Agent Platformが有効になっており、トップレベルグループでカスタムフローが許可されていること。
  • Salesforceのメタデータ(Apexクラス、トリガー、Salesforceフロー)がGitLabプロジェクトに保存されていること。フローが読み取る対象はこのプロジェクトです。
  • そのプロジェクトのメンテナーまたはオーナーロール。
  • Salesforce側で、指定ログイン情報、カスタムメタデータ型、Apexクラスを作成できる権限。
  • SalesforceのデプロイがGitLab CI/CDパイプライン経由で実行されていること。同じイシューから修正をデプロイするために必要です。

ステップ1: トリアージフローを作成する

最初に手を付けるのはGitLab側です。後の手順で、SalesforceがこのフローのIDを必要とするためです。

カスタムフローの実体は、フローレジストリv1構文で書かれたYAMLファイル1つ。今回のフローに含まれるエージェントは1つだけ。Salesforceがフローを開始すると、エラーの詳細がフローのgoalとして送られます。エージェントはそれをcontext:goalとして受け取り、リポジトリを調査して、イシューを1件作成します。

      version: "v1"
environment: ambient

components:
  - name: "sf_error_triage"
    type: AgentComponent
    prompt_id: "sf_error_triage_prompt"
    inputs:
      - from: "context:project_id"
        as: "project_id"
      - from: "context:goal"
        as: "error_report"
    toolset:
      - "find_files"      # locate the class or Flow in the repository
      - "grep"
      - "read_file"
      - "list_commits"    # find recent changes to that file
      - "create_issue"    # the only write: open the triage issue

prompts:
  - prompt_id: "sf_error_triage_prompt"
    prompt_template:
      system: |
        You triage Salesforce runtime errors for a team that keeps its
        Salesforce metadata (Apex classes, triggers, Flows) in this project.

        You receive an error report with a class name, exception type,
        message and stack trace.

        1. Find the source file for the class or Flow named in the report.
        2. Read the code around the lines in the stack trace.
        3. List recent commits that touched that file and identify any change
           that plausibly introduced the error.
        4. Create one issue:
           - Title: "[Salesforce error] <exception type> in <class>"
           - Label: salesforce-error
           - Description: the original error, then sections for
             Likely cause, Affected component, Suspect change,
             Suggested next step, and Confidence (high, medium or low,
             with one line of reasoning).

        Rules:
        - Cite file paths, line numbers and commit SHAs for every claim.
        - If you cannot find the code or a suspect commit, say so. Do not guess.
        - Do not change code. A person decides what happens next.
      user: |
        Project ID: {{project_id}}
        Error report:
        {{error_report}}
      placeholder: history

routers:
  - from: "sf_error_triage"
    to: "end"

flow:
  entry_point: "sf_error_triage"

    

ツールセットは意図的に絞り込んでいます。読み取り用が4つ、イシュー作成が1つ。コードをプッシュすることも、既存のイシューを書き換えることもできません。レビューしやすく、信頼しやすい構成です。

プロンプトの中で最も効いているのは2行です。すべての主張に出典を求めておけば、エンジニアは1分で根拠を確認できます。そして「見つからなかった」と言うことを許しておけば、エージェントが原因をでっち上げることもありません。

フローを作成するには、プロジェクトでAI > フロー > 新しいフローを選択し、フローを選んでYAMLを貼り付け、フローを作成を選択します。VS CodeのGitLab flow builderで構築・テストする方法もあります。

ステップ2: フローを有効化してコンシューマーIDを取得する

フローは、プロジェクトで有効化しないかぎり実行できません。

  1. プロジェクトでAI > フローを選択し、管理中タブを開いて、作成したフローを選択します。
  2. 有効にするを選択し、Salesforceのコードを格納しているプロジェクトを選びます。GitLabはai-<flow>-<group>という名前のサービスアカウントをフロー用に作成します。フローは複合アイデンティティで実行されるため、フローを開始したユーザーの権限を超えてアクセスすることはありません。SalesforceがAPI経由でフローを開始した場合、GitLabはこのサービスアカウントとしてフローを実行します。
  3. メンションや割り当てによるトリガーの設定は不要。このフローを開始するのは、SalesforceからのAPI呼び出しです。

API経由でカスタムフローを開始する際、Salesforceはフローのai_catalog_item_consumer_idを渡します。ドキュメントの短いGraphQLクエリで検索し、返ってきたgid://gitlab/AiCatalogItemConsumer/<number>の末尾の数値を使います。プロジェクトIDとあわせて控えておいてください。

最後に、apiスコープとデベロッパー以上のロールを持つプロジェクトアクセストークンを作成します。SalesforceがGitLabを呼び出す際に使うのが、このトークン。これより低いロールでは、APIがカタログフローの実行を拒否します。

ステップ3: Salesforceからフローを呼び出す

トークンは指定ログイン情報に保存する。 GitLab_APIという名前の指定ログイン情報を、URL https://gitlab.com で作成します。その裏側には、プロジェクトアクセストークンをPRIVATE-TOKENヘッダーで送信する外部ログイン情報を設定。トークンがコードに現れることはありません。

Flows APIはQueueableから呼び出す。 Salesforceはレコード保存の途中でのコールアウトを許可していないため、呼び出しはバックグラウンドジョブとして実行します。ジョブは例外をフローのgoalに変換し、フローを開始します。

      public with sharing class DuoTriageJob implements Queueable, Database.AllowsCallouts {
    private final String goal;

    public DuoTriageJob(Exception e, String className) {
        goal = 'Class: ' + className
            + '\nException: ' + e.getTypeName()
            + '\nMessage: ' + e.getMessage()
            + '\nStack trace:\n' + e.getStackTraceString();
    }

    public void execute(QueueableContext ctx) {
        Duo_Triage_Setting__mdt cfg = Duo_Triage_Setting__mdt.getInstance('Default');

        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:GitLab_API/api/v4/ai/duo_workflows/workflows');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(new Map<String, Object>{
            'project_id'                    => cfg.Project_Id__c,
            'ai_catalog_item_consumer_id'   => cfg.Consumer_Id__c.intValue(),
            'goal'                          => goal,
            'start_workflow'                => true,
            'allow_agent_to_request_user'   => false,
            'agent_privileges'              => new List<Integer>{ 1, 2, 3 },
            'pre_approved_agent_privileges' => new List<Integer>{ 1, 2, 3 }
        }));
        HttpResponse res = new Http().send(req);
        // 201 Created: the response includes web_url, a link to the agent session.
    }
}

    

ステップ2で控えたプロジェクトIDとコンシューマーIDは、カスタムメタデータ型Duo_Triage_Setting__mdtに保持します。デプロイなしで変更できる形です。

リクエストボディの中で特に重要な設定は3つです。

  • allow_agent_to_request_user: false: フローは途中で質問のために停止せず、最後まで実行されます。深夜2時にSalesforceのエラーを見張っている人は、どこにもいません。
  • agent_privileges: エージェントの権限を、ファイルの読み取り(1)、GitLabの読み取り(2)、GitLabへの書き込み(3)に限定します。イシューの作成に必要なのはこれだけ。コマンドの実行やGitの使用はできません。IDはインスタンスによって異なる場合があるため、すべてのエージェント特権をリストするで確認してください。
  • pre_approved_agent_privileges: 同じリストを指定します。これにより、フローがツールの承認待ちで止まることがなくなります。

このサンプルでは、レスポンスのチェック、リトライ、テストを省いています。本番環境に投入する前に追加してください。

ステップ4: 自動とオンデマンド、2つの起動方法

自動で起動する。 例外をキャッチして処理している箇所で、ジョブをキューに入れます。

      try {
    OpportunityDiscountService.applyTierDiscount(opportunities);
} catch (Exception e) {
    System.enqueueJob(new DuoTriageJob(e, 'OpportunityDiscountService'));
    // ...your existing error handling
}

    

トランザクション全体がロールバックされると、キューに入れたジョブもSalesforceによって破棄されます。そのため、エラーを処理して処理を続行する箇所に呼び出しを配置してください。

オンデマンドで起動する。 調査する価値のあるエラーを自分たちで選びたい、というチームもあります。その場合は、ジョブをInvocable Apexアクションでラップし、GitLab Duoに調査を依頼というラベルを付けて、画面フローに追加します。画面フローは、ログレコードやサポートケースなど、エラーを記録しているレコード上のクイックアクションとして実行。Salesforceで1回クリックすれば、数分後にはGitLabにイシューが現れます。

ステップ5: チームが受け取るもの

ユーザーが商談を保存し、Apexトリガーが例外を投げる。その数分後、GitLabプロジェクトに新しいイシューが作成されます。フローが書き込む内容の例を示します。

      ## [Salesforce error] System.NullPointerException in OpportunityDiscountService

Label: salesforce-error

### Original error
Attempt to de-reference a null object
Class.OpportunityDiscountService.applyTierDiscount: line 48, column 1
Trigger.OpportunityTrigger: line 12, column 1

### Likely cause
applyTierDiscount() reads opp.Account.Tier__c without a null check (line 48).
Opportunities saved without an Account reach this line with opp.Account == null.

### Affected component
force-app/main/default/classes/OpportunityDiscountService.cls,
called from OpportunityTrigger (before update).

### Suspect change
Commit 3f9c2ab, "Apply tier discount on stage change", added the Tier__c lookup.
Before that commit, the method returned early when AccountId was blank.

### Suggested next step
Restore the early return for a blank AccountId, or guard the lookup.
Add a test that updates an Opportunity with no Account.

### Confidence
High. The stack trace line matches the new code in 3f9c2ab.

    

Salesforceにもコードベースにも、変更は加えられていません。フローが担ったのは一次調査まで。今すぐ直すのか、予定に組み込むのか、仕様どおりとしてクローズするのか。判断はエンジニアに委ねられます。

Flows APIのレスポンスには、エージェントセッションのweb_urlが含まれます。開けばフローがたどった各ステップを確認でき、プロンプトを調整する際の近道になります。

本番運用のためのガードレール

本番環境で動かす前に、次の点を確認してください。実際のトラフィックに耐えられるかどうかは、ここで決まります。

  • データではなく、エラーの構造を送る。 メッセージがSalesforceを出る前に、レコードID、メールアドレス、顧客データを含む可能性のある自由入力テキストを取り除きます。goalに何が含まれるのかは、運用開始前にセキュリティチームと確認してください。
  • 権限は最小限にとどめる。 ファイルの読み取り、GitLabの読み取り、イシューの作成。必要なのはこれだけです。マージリクエストの作成などフローの役割を広げるのは、正確な分析で信頼を獲得してからにしてください。
  • トークンのスコープを絞る。 パーソナルアクセストークンではなく、単一プロジェクト向けのプロジェクトアクセストークンを使い、定期的にローテーションします。
  • 判断は人が担う。 フローは調査し、エンジニアが決める。すべてのイシューに出典が付いているため、エンジニアは調査をやり直すことなく、根拠を検証できます。

エラーから修正まで、1つのプラットフォームで

1件のエラーを、最初から最後まで追ってみます。

  • GitLab Duoが調査する。 フローがスタックトレースを読み、コードを特定し、エラーの原因となった可能性が最も高い変更を指し示します。
  • GitLabイシューが追跡する。 分析結果は、ラベルを付け、優先度を決め、担当者を割り当て、マイルストーンに組み込める作業になります。他のイシューと同じように扱える形です。
  • GitLab CI/CDが実行し、修正をデプロイする。 フロー自体がGitLab CI/CD上で動き、Salesforceのデプロイパイプラインも同じGitLab CI/CDで動きます。エンジニアがイシューからマージリクエストを作成すると、パイプラインが変更を検証してSalesforceにデプロイし、マージリクエストのマージとともにイシューがクローズされます。

すべてのステップがGitLabの中で完結するため、履歴は途切れません。イシューはマージリクエストに、マージリクエストはパイプラインに、パイプラインはデプロイにつながります。何が壊れ、なぜ壊れ、誰が直し、いつ修正が本番に届いたのか。誰でも追跡できます。

Salesforce以外への応用

Salesforce固有の部分を取り払えば、パターンはシンプルです。業務システムがHTTPリクエストを1回送り、自社のコードを把握したGitLab Duoのカスタムフローが調査を引き受ける。リクエストを送信できるシステムであれば、どれでもフローを開始できます。

同じパターンが活きそうな場面を、いくつか挙げます。

  • ERP連携の同期失敗を、最後に変更されたマッピングコードまで遡る。
  • 「バグの可能性あり」とタグ付けされたサポートケースを、エンジニアに届く前に直近のリリースと突き合わせる。
  • スケジュール実行のデータジョブの失敗を、パイプライン定義の最後の変更と照合する。

DevSecOpsチームにとって、これは支援対象の業務システムから届くエラーが、手作業で追跡する生ログではなく、原因の仮説が付いたイシューとして届くことを意味します。業務部門がGitLabを覚える必要はなく、エンジニアが新しいダッシュボードを見張る必要もありません。各システムはそれぞれの役割を果たし続け、何かが壊れるたびに、GitLab Duo Agent Platformがエンジニアリングチームに一歩先んじた状態を用意します。

試してみる

チームが支えている業務システムを1つ選び、そのシステムが今日ログに記録しているエラーを1つ選んでください。カスタムフローにコードを渡し、そのシステムから呼び出して、最初の分析が何を教えてくれるかを確かめてみましょう。GitLab Duo Agent Platformの無料トライアルを始めるか、すでにGitLab PremiumまたはUltimateをお使いなら、Duo Agent Platformを有効化して、最初のカスタムフローを作成してください。

参考資料

ご意見をお寄せください

このブログ記事を楽しんでいただけましたか?ご質問やフィードバックがあればお知らせください。GitLabコミュニティフォーラムで新しいトピックを作成してあなたの声を届けましょう。

フィードバックを共有する

今すぐ開発をスピードアップ

DevSecOpsに特化したインテリジェントオーケストレーションプラットフォームで実現できることをご確認ください。