要約: AIエージェントを使ってCIの失敗を自動修正するには、CIの失敗イベントをWebhookに送信し、コーディングエージェントに対応可能な問題かどうかを判定させ、クリーンな作業ツリー（worktree）でローカルに再現した上で、修正内容をブランチへDraftプルリクエストとしてプッシュします。最終的な確認とマージは人間が行います。ローカルで再現できなければプッシュは行いません。
夕方4時にビルドが落ちたときのコストは、修正そのものにかかる手間以上です。誰かが作業の手を止め、ログを開き、900行にも及ぶセットアップ出力をスクロールして、ようやくリントエラーや古いスナップショットを見つけ出します。修正自体は2分で終わっても、コンテキストスイッチの代償として20分が奪われます。
この無駄な時間こそ、コーディングエージェントの腕の見せ所です。すでに手元の環境でClaude CodeやCodexなどのエージェントを動かしている方も多いでしょう。足りないのはそれらをつなぐ「配線（wiring）」です。失敗を検知し、適切なコンテキストをエージェントに渡し、エージェントが当てずっぽうなコードをリポジトリにプッシュするのを防ぐ仕組みが必要です。本ガイドでは、GitHub ActionsとSharkly Automationを組み合わせてその配線を構築します。なお、この設計パターンはHTTPリクエストを送信できるあらゆるCIツールに応用可能です。
AIエージェントがCIでうまく修正できる問題・できない問題
エージェントが最も力を発揮するのは、開発用PC上で再現可能で、修正内容が小さく検証しやすいエラーです。逆に、インフラ、認証情報、外部サービスに起因するエラーの修正は苦手とします。自動化を進める前に、まずは切り分けを行いましょう。
| 失敗の種類 | エージェントの適性 | 理由 |
|---|---|---|
| リントおよびフォーマットのエラー | 極めて高い | 結果が決定論的であり、リンターの実行によって修正を確認できるため |
| 型エラー | 極めて高い | コンパイラによって修正を確認できるため |
| 意図的なUI変更に伴うスナップショットの不整合 | 高い | 再現は容易だが、その変更が意図したものかどうかは人間が確認する必要があるため |
| フレイキーテスト（不安定なテスト） | 中程度 | 再現に複数回の実行が必要であり、根本原因が実際の競合状態（レースコンディション）であるケースが多いため |
| ロジック変更に伴うユニットテストの失敗 | 中程度 | テスト側の期待値が正しく、コード側が誤っている可能性があるため |
| ランナーのディスク容量不足、ネットワークのタイムアウト | 低い | リポジトリ側で修正できる箇所が存在しないため |
| シークレットの欠落・期限切れ、権限エラー | 不可 | エージェントに認証情報を取り扱わせてはならないため |
この表から導き出される鉄則は、「エージェント自身のComputer上で、失敗（Red）から成功（Green）への変化を実際に確認できた修正のみを提出させる」ということです。DeepSeek HarnessチームがXに投稿した設計エッセイでは、このパターンを「静かに再現して修正する（silently reproduce and fix）」と呼んでいます。トリガーがイベントを監視し、通常時は何もせず、確認済みのシンプルな修正だけを表に出すというアプローチです。このエッセイで語られているのは完成した製品ではなくプロトタイプの設計ですが、その原則は独自に仕組みを構築する場合にもそのまま当てはまります。
CI修正ループの仕組み
この修正ループは、失敗イベント、署名付きWebhook、低コストなフィルタリング、隔離環境での再現、人間によるレビューゲートという5つの要素で構成されています。
- CIの実行が失敗で終了します。
- 軽量なワークフローが、署名付きJSONペイロードをWebhook URLに送信します。
- エージェントがペイロードを読み取り、対象外のリポジトリやリリースブランチでの失敗など、対応範囲外のイベントを除外します。
- エージェントがタスクを作成し、クリーンな作業ツリー（worktree）をチェックアウトして失敗を再現し、修正を行います。
- ブランチをプッシュしてDraftプルリクエストを作成します。人間が確認してマージまたはクローズします。
ステップ3とステップ4は、Sharkly Automationとして実行されます。Automationとは、保存された一連の指示（プロンプト）とそれを実行するAgentまたはCrewの組み合わせであり、スケジュール、タスクのステータス変更、コメント内の特定フレーズ、あるいはWebhookなどのトリガーによって起動されます。
ステップ1: CIの失敗をWebhookに送信する
GitHub Actionsには、別のワークフローの完了時に発火するworkflow_runイベントが用意されています。このイベントはあらゆる結果（conclusion）に対して発火するため、ジョブの条件式を使ってfailureのみにフィルタリングします。なお、GitHubのドキュメントにも記載されている注意点として、このワークフローファイルはデフォルトブランチに存在していなければトリガーされません。
以下のワークフローは、CIという名前のワークフローを監視し、軽量なJSONペイロードを構築・署名してPOST送信します。
name: Report CI failure
on:
workflow_run:
workflows: [CI]
types: [completed]
jobs:
notify:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
steps:
- name: Send signed webhook
env:
WEBHOOK_URL: ${{ secrets.SHARKLY_WEBHOOK_URL }}
SIGNING_SECRET: ${{ secrets.SHARKLY_SIGNING_SECRET }}
REPO: ${{ github.repository }}
RUN_ID: ${{ github.event.workflow_run.id }}
RUN_URL: ${{ github.event.workflow_run.html_url }}
BRANCH: ${{ github.event.workflow_run.head_branch }}
SHA: ${{ github.event.workflow_run.head_sha }}
run: |
BODY=$(jq -nc --arg repo "$REPO" --arg run_id "$RUN_ID" \
--arg url "$RUN_URL" --arg branch "$BRANCH" --arg sha "$SHA" \
'{event:"ci_failure",repo:$repo,run_id:$run_id,run_url:$url,branch:$branch,sha:$sha}')
TS=$(date +%s)
SIG=$(printf '%s\n%s' "$TS" "$BODY" \
| openssl dgst -sha256 -hmac "$SIGNING_SECRET" -binary | base64)
curl -fsS -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "X-Webhook-Timestamp: $TS" \
-H "X-Webhook-Signature: v1=$SIG" \
--data-raw "$BODY"
ブランチ名にはコントリビューターが指定した任意の文字列が含まれる可能性があるため、シェルスクリプト内に直接埋め込むのではなく、envとjqを経由して安全に渡しています。また、URLとシークレットはファイル内に直接書き込まず、必ず暗号化されたリポジトリシークレットとして保存してください。
ステップ2: AutomationとWebhookトリガーを作成する
ご利用のSpaceでAutomationを新規作成し、修正を担当させるAgentを割り当てて、Webhookトリガーを追加します。Sharklyはトリガーの作成時または再生成時に一度だけ完全なURLを表示するため、そのままGitHubのシークレットへコピーしてください。
署名シークレット（signing secret）を有効にします。これを設定しない場合、URL自体がベアラートークンのように機能してしまい、URLを知っている人なら誰でも実行を開始できてしまいます。Automationsのドキュメントに従って署名を有効化すると、各リクエストにはv1=というプレフィックスに加えて、タイムスタンプ、改行、および未加工のリクエストボディをwhsec_シークレットでHMAC-SHA256ハッシュ化しBase64エンコードした値を含むX-Webhook-Signatureヘッダーが必要になります。Sharklyは300秒以上のタイムスタンプのズレを拒否し、同一署名は10分以内に一度しか受け付けないため、インターセプトされたリクエストのリプレイ攻撃を防ぐことができます。
有効なリクエストから実行を開始させるには、トリガーが有効化されており、AutomationのステータスがActiveになっている必要があります。まずは「Run now（今すぐ実行）」でテストを行いましょう。
ステップ3: まずフィルタリングし、次に修正する指示（プロンプト）を作成する
Webhookから起動されたAutomationの実行は、デフォルトではタスクを自動作成しません。実行履歴が特定のタスクに紐付かないため、プロンプト内でタスクを作成させるように指示します。これにより、失敗ごとに記録が残り、質問用のスレッドが確保され、チーム全体に進捗状況が見えるようになります。また、処理コストの低いチェックをプロンプトの先頭に配置し、大半の不要なイベントが数秒で終了するようにします。
You receive a CI failure webhook. The trigger payload is JSON with
event, repo, run_id, run_url, branch, sha.
1. Stop with no output unless event == "ci_failure" and repo is
acme/web. Stop if branch starts with "release/".
2. Search open tasks for run_id. If one exists, stop.
3. File a task titled "CI fix: <repo> run <run_id>" with run_url in
the body. Do all further work under that task.
4. Read the failed steps: gh run view <run_id> --log-failed
5. If the cause is a secret, permission, runner, or network problem,
comment the diagnosis on the task and stop. Change nothing.
6. Check out sha in a fresh worktree. Run the failing command and
confirm it fails the same way. If it does not reproduce, comment
what you tried and stop. Never push an unreproduced fix.
7. Make the smallest change that fixes it. Do not edit CI config,
lockfiles, or tests you were not asked to fix. Rerun the command
and the nearest test suite.
8. Push to branch ci-fix/<TASK-ID> and open a draft PR with
gh pr create --draft, task ID in the title. Comment the PR link
on the task and hand it to a human for review.
ここで重要なポイントが2つあります。現時点では、ステータスやコメントによるトリガーは組織全体を対象にマッチするため、ドキュメントでは指示内容の内部で入力を検証することが推奨されています。Webhook自体は専用のURLにスコープされていますが、ステップ1のチェックは誤ルーティングされたリクエストを防ぐセーフガードとして依然として有効です。もう1点は、ブランチ名にタスクIDを含めることの実用的な効果です。GitHub連携を接続しておくと、ブランチ名、PRのタイトル、またはPR本文にタスクIDが含まれている場合、プルリクエストが自動的にタスクへリンクされます。
ステップ4: 独立した作業ツリー環境のComputer上で実行する
Computerとは、Agentが稼働する接続ホストのことであり、独自のRuntime、ファイル、Git認証情報を備えています。Agentのリポジトリ設定をTemporaryモードに設定することで、実行ごとに個別のタスクディレクトリと独立した作業ツリー（worktree）が割り当てられます。これにより、1分差で2つのビルド失敗が発生した場合でも、互いのファイルが衝突することはありません。詳しい仕組みについては、独立した作業ツリーでの並列エージェント実行およびgit worktreeのリファレンスを参照してください。
Gitのアクセス権限は、GitHub AppではなくComputer側から提供されます。GitHub連携が行うのはプルリクエストのリンクとIssueの同期のみであり、クローンやプッシュの実行にはそのホスト上のSSHキー、HTTPSトークン、またはgh CLIのログインセッションが使用されます。この認証情報にはブランチへのプッシュ権限のみを付与し、マージには必ずレビューを要するようデフォルトブランチを保護してください。
コスト管理とガードレール
各実行の料金は、使用しているRuntime自体のプランに基づいて請求されます。Sharklyはトークンを直接販売していないため、CI修正の実行にかかる費用は、普段利用しているClaude CodeやCodexのセッション費用と同等です。ステップ1に設置した高速フィルタリングは、最も重要なコスト抑制策となります。ステップ1で即座に終了するイベントなら、完全な再現処理を行うことなく、数百トークンの消費だけで済みます。
2つ目の制御策は同時実行数の制限です。すべてのComputerには同時実行タスク数の上限が設定されており、一時ディレクトリでの実行はデフォルトでその上限の半分に制限されます。処理許容量に達した場合、1台のマシンに負荷が集中するのではなく、超過分の実行はキューに入ります。朝一番に30件のビルド失敗が重なっても、システムが破綻することはなく、整然とキューで処理されます。
残りのルールは、一度設定すれば済む運用方針です。
- Draft PRのみを作成する。エージェント自身には決してマージさせないこと。レビューゲートをどこに配置すべきかについては、ヒューマン・イン・ザ・ループのコーディングエージェントを参照してください。
- 1回の実行につき試行は1回のみとする。最初の修正を適用して再実行した結果が失敗した場合、エージェントはコメントを残して停止します。
- 変更禁止リスト（デナイリスト）を設ける。CI設定、シークレット、ロックファイル、マイグレーションファイルなどは変更対象外とします。
- 指示内容を変更する際は、管理画面からAutomationを一時停止し、「Run now」での動作確認を経てから再開します。
信頼する前に必ず検証してください。ここでもPlan、Observe、Verifyのループが当てはまります。対象リポジトリを拡大する前に、まずは1週間分の実行履歴を確認しましょう。
代替アプローチ
Webhook Automationを使用する代わりに、失敗ごとにタスクを作成する構成も可能です。ワークフローからsharkly task createを呼び出すスクリプトを実行し、割り当てられたAgentに処理を拾わせます。この方法ではエージェントが無視すべきエラーも含めてすべての失敗に対してタスクが起票されるため、ビルド頻度の低いリポジトリに適しています。すでにGitHub上でIssueのトリアージを行っているチームであれば、GitHub IssueをAIエージェントに割り当てる方法から導入するのも良い選択肢です。
まずは1つのリポジトリから始める
まずはリントや型の失敗が最も多いリポジトリを1つ選び、上記のワークフローを接続して、Webhookによる自動トリガーを有効化する前に手動でAutomationを3回テスト実行してみましょう。1つのエージェントからさらにスケールアップする準備ができたら、10台のAIコーディングエージェントを同時に実行する方法をご覧ください。Sharklyは無料で使い始めることができます。Computerを接続し、次に発生するビルド失敗の対応を既存のエージェントに任せてみましょう。
よくある質問（FAQ）
AIエージェントは失敗したCIビルドを自律的に修正できますか？
ローカルで再現可能なリント、型、スナップショットのエラーであれば修正できます。ただし、マージまで自律的に行わせるべきではありません。成果物はDraft PRにとどめ、人間が承認する運用を徹底してください。
GitHub Actionsが失敗したときにAIエージェントを起動するにはどうすればよいですか？
workflow_runイベント（types: [completed]）をトリガーとし、conclusion == 'failure'というジョブ条件を設定したワークフローを追加します。そのジョブから、エージェントのWebhook URLに対して署名付きリクエストをPOST送信します。
エージェントが誤った修正をプッシュするのを防ぐ仕組みはありますか？
「再現の原則」がそれを防ぎます。エージェントはローカルで失敗を確認し、変更を適用した上で、同じコマンドが成功することを確認しなければなりません。再現できなければタスクにコメントを残すだけで、プッシュは一切行われません。
SharklyのGitHub連携機能はプルリクエストを作成しますか？
いいえ、作成しません。GitHub連携が行うのは、プルリクエストとタスクの紐付けやIssueの同期です。プルリクエストの作成自体は、エージェントが自身のComputer上にあるGitおよびghの認証情報を使用して実行します。
フレイキーテスト（不安定なテスト）への対応はどうなりますか？
エージェントには、成否を判断する前に失敗したテストを複数回再実行するように指示します。成功したり失敗したりする場合は、無理に対処コードを当てるのではなく、不安定なテストである旨をタスクに報告させます。
CI修正の実行にはどのくらいのコストがかかりますか？
そのセッションでRuntimeが消費したトークン分の費用のみです。Sharklyでの実行料金は、お客様が契約しているClaude Code、Codex、または各種APIプランに対して直接請求されます。
