May 19, 2026

Claude Code Async Hooks × GitHub Actions 連携ガイド2026：CI/CDパイプラインを10分で自動化する実践チュートリアル

#Claude Code #GitHub Actions #CICD #Async Hooks #DevOps #自動化 #フリーランス

Claude Code Async Hooks × GitHub Actions 連携ガイド2026：CI/CDパイプラインを10分で自動化する実践チュートリアル

PR: 本記事にはアフィリエイトリンク（プロモーション）が含まれます。掲載するサービスは編集部が記事内容との関連性で選定しており、報酬の有無で評価を変えていません。

この記事でわかること（読了目安約10分）

対象読者: Claude Code を CI/CD やチーム開発で本格運用したいエンジニア、GitHub Actions と連携してレビュー・テスト・デプロイを自動化したい個人開発者・フリーランス

前提知識: Claude Code CLI 基本操作（claude 実行経験あり）、GitHub Actions の YAML を最低限読める

結論: .claude/settings.json の hooks セクションに async: true を1行加えるだけで、長時間かかる外部処理（CI 起動・Slack 通知・DB クエリ）をブロックせずに走らせられる。GitHub Actions と組み合わせれば「Claude が編集した瞬間に PR コメント / CI 実行」が完成する。

2026年5月、Claude Code 2.1.x 系統で Async Hooks（非同期フック） と HTTP Hooks の追加がドキュメント側で確認できる状態になった（Claude Code Hooks 公式の Async / HTTP セクション参照）。Skill のセマンティック検索と並んで「2026年5月アップデートの目玉」と位置づけられているが、日本語の包括的ハンズオン記事はまだ少ない。

「同期 Hooks と何が違うのか」「GitHub Actions と本当に10分で繋がるのか」「payload が大きいときの timeout 設計はどうするか」――こうした実務側の疑問に答える記事が不足している。

本記事ではこれらを 一気通貫の10分ハンズオン として整理する。Anthropic 公式ドキュメント・Hacker News の議論・実機検証を突き合わせた上で、.claude/settings.json 1ファイルと GitHub Actions ワークフロー1本 で完結する CI/CD パイプライン構築手順を提示する。

記事内の設定値・コマンドについて: 2026年5月19日時点での Claude Code 2.1.x 公式仕様に基づく。更新頻度が高いため、実装前に Claude Code Hooks 公式ドキュメントで最新構文を確認することを強く推奨する。

この記事の一次分析

同期 Hooks / Async Hooks / HTTP Hooks の三者比較マトリクス（公式ドキュメントに散在する仕様を1枚に集約）

10分セットアップの実機ログ（Claude Code 2.1.128 で再現確認）

PR 自動コメントワークフロー（GitHub Actions の workflow_dispatch × Async Hook の最小実装）

timeout / payload size / lock 排他の実践トラブルシューティング3項目

1. Async Hooks とは — 同期 Hooks との3つの違い

1-1. Hooks 機能のおさらい

Claude Code の Hooks は「Claude が特定の操作を実行する前後（PreToolUse / PostToolUse / Stop / SessionStart 等）に、ユーザーが定義したシェルコマンドや HTTP リクエストを自動実行する」仕組みだ。.claude/settings.json の hooks セクションに JSON で定義する。

従来の Hooks（同期 Hooks）は、Claude のメイン処理をブロックして実行される。たとえば PreToolUse に「npm test を走らせる」を仕込むと、テストが完了するまで Claude は次の Tool 呼び出しに進まない。安全装置としては優秀だが、テストが5分かかれば Claude も5分待つ。

1-2. Async Hooks がもたらすもの

Async Hooks は同じトリガーで実行されるが、Claude のメイン処理をブロックしない。fire-and-forget で背景プロセスに処理を投げ、Claude はそのまま次の作業に進む。

観点	同期 Hooks（従来）	Async Hooks（2026-05〜）	HTTP Hooks（2026-05〜）
メイン処理ブロック	する	しない	しない（HTTPで投げる）
実行先	ローカル shell	ローカル shell	外部 Webhook URL
戻り値の扱い	exit code で Claude に影響	戻り値は無視（ログのみ）	response status は記録
timeout デフォルト	60s	設定可（推奨300s）	30s（HTTP 仕様）
失敗時の挙動	Claude が即停止 / 警告	サイレント失敗 + ログ	サイレント失敗 + status code 記録
適した用途	保護（型チェック / lint）	副作用処理（通知 / CI 起動）	外部 SaaS 連携（Slack / Datadog）

1-3. 「いつ Async を使うべきか」の判断軸

簡潔に言えば、「失敗しても Claude を止めるべきでない処理」は Async、「失敗したら Claude を止めて欲しい処理」は同期だ。

同期にすべき例: 編集前のフォーマッタ / 型チェック / 危険操作（rm -rf 等）の事前検証
Async にすべき例: Slack 通知 / GitHub Actions ワークフロー起動 / 監査ログ送信 / DB 統計更新
HTTP にすべき例: Datadog event / Sentry breadcrumb / Linear ticket 作成

ここで重要なのは、CI/CD 起動は基本的に Async で扱うべきという点だ。GitHub Actions は数分〜数十分かかることがあり、同期 Hooks に乗せると Claude が完全に止まる。Async なら「編集瞬間にトリガーを投げて、CI の結果は別途 PR コメントで確認」というワークフローが組める。

2. なぜ Async Hooks が「CI/CD 連携の決定打」なのか

2-1. 従来手法の限界

Claude Code を CI/CD と連携させる従来の方法には次の3パターンがあった。

Claude 終了後の手動 push: Claude が編集 → 人間が git push → GitHub Actions が走る。手作業が残る。
同期 Hooks 内で git push: 編集ごとに push されるが、Claude が CI 完了まで待たされる。1日10回編集すれば数時間ロス。
完全な別プロセス（cron 等）: 1分粒度のポーリング。リアルタイム性ゼロ。

Async Hooks はこの3つすべての欠点を解決する。編集瞬間にトリガーが飛び、Claude は止まらず、CI 結果は別経路で受け取れる。

2-2. 実務インパクト（筆者観測値・n=1事例）

以下は筆者の個人開発リポジトリ（小〜中規模 TypeScript プロジェクト・1週間運用比較）で観測した1サンプル所感ベースのデータ。統計検定はしておらず、リポジトリ規模・編集パターン・ネットワーク条件で大きく振れるため、あくまで参考値として扱ってほしい。

項目	Async Hooks 導入前	導入後	体感差分（n=1）
平均 PR 作成までの体感時間	約40分	約20分	大幅短縮
Claude セッション中断（人間が CI 待ちで離席）回数 / 日	体感約10回	体感約1-2回	大幅減
CI 実行待ちで失われる Claude 思考連続性	高	ほぼゼロ	—

数字以上に効くのが「Claude の思考が途切れない」点だ。同期 Hooks で5分待たされると、Claude のコンテキストは保持されていても人間側のレビュー疲弊が貯まる。Async ならその疲弊が発生しない。導入効果は環境依存が大きいため、まずは自分のプロジェクトで1-2日試して計測することを推奨する。

📌 フリーランスエンジニア向けPR CI/CD 自動化スキルは2026年現在、フリーランス案件の単価差を生む最重要スキルの1つだ。月単価60万円以上の案件は CI/CD 設計経験を高頻度で要求する。Async Hooks レベルの最新ツールチェーンを使いこなせる人材は希少性が高く、エージェント経由で案件を見つけると相場が把握しやすい。 👉 フリーランスボードで CI/CD 案件の単価相場を確認する（PR）

3. 前提環境チェック（30秒）

実装に入る前に、以下を確認する。

# Claude Code バージョン（2.1.0 以降必須）
claude --version
# → 2.1.128 (or higher)

# GitHub CLI（ワークフロー検証で使う）
gh --version

# 対象リポジトリで GH_TOKEN が使えるか
gh auth status

claude --version が 2.0 系を返す場合、npm i -g @anthropic-ai/claude-code@latest で更新する。Async Hooks は 2.1.x 系で正式サポートされた機能のため、それ以前のバージョンでは設定ファイルに書いても無視される。

4. 10分セットアップ — `.claude/settings.json` の async hook 定義

4-1. 最小構成

プロジェクトルートで .claude/settings.json を作成（または既存ファイルに hooks を追記）する。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "async": true,
        "timeout": 300,
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/ci-trigger.sh \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

ポイントは3点。

async: true: これがないと従来の同期 Hooks として動く（一番ハマりやすい）
matcher: 正規表現で対象 Tool を絞る。Edit|Write でファイル編集系のみに反応させる
timeout: 300: 5分。GitHub Actions 起動の API レイテンシーを考慮するとデフォルト60sでは足りない場合がある

4-2. trigger スクリプト本体

scripts/ci-trigger.sh を作成。

#!/usr/bin/env bash
# Async hook trigger — GitHub Actions に編集イベントを投げる
set -euo pipefail

FILE_PATH="${1:-unknown}"
LOG_DIR=".claude/logs/async-hooks"
mkdir -p "$LOG_DIR"
LOG_FILE="$LOG_DIR/$(date +%Y%m%d-%H%M%S)-$$.log"

# 排他制御（同時実行で GitHub Actions が暴発しないよう lock）
LOCK_FILE="/tmp/claude-async-hook-$(basename "$PWD").lock"
exec 200>"$LOCK_FILE"
flock -n 200 || { echo "lock held, skip" >> "$LOG_FILE"; exit 0; }

{
  echo "=== $(date -Iseconds) edit detected: $FILE_PATH ==="

  # GitHub Actions の workflow_dispatch を起動
  gh workflow run claude-ci.yml \
    --ref "$(git rev-parse --abbrev-ref HEAD)" \
    -f file_path="$FILE_PATH" \
    -f triggered_by="claude-async-hook" 2>&1

  echo "=== triggered at $(date -Iseconds) ==="
} >> "$LOG_FILE" 2>&1

chmod +x scripts/ci-trigger.sh を忘れずに。

4-3. 動作確認

Claude Code を起動して、適当なファイルを編集させる。

claude
> sites/blog/README.md に「Async Hooks 検証」と1行追記して

編集後、Claude はすぐ次の対話に進めるはず（ブロックされないのが Async Hooks の挙動）。一方、裏で：

ls -la .claude/logs/async-hooks/ | tail -3
# 20260519-103045-12345.log のようなファイルが生成されている

gh run list --workflow=claude-ci.yml --limit 1
# 直近の run が "triggered_by: claude-async-hook" で表示される

これで Claude が編集した瞬間に GitHub Actions が起動 している状態になった。

5. GitHub Actions ワークフロー側の実装（5分）

.github/workflows/claude-ci.yml を作成。

name: Claude CI (async-triggered)

on:
  workflow_dispatch:
    inputs:
      file_path:
        description: "編集されたファイルパス"
        required: false
        default: "unknown"
      triggered_by:
        description: "トリガー識別子"
        required: false
        default: "manual"

jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Echo trigger metadata
        run: |
          echo "triggered_by: ${{ inputs.triggered_by }}"
          echo "file_path:   ${{ inputs.file_path }}"

      - name: Run lint
        run: npm ci && npm run lint || true

      - name: Run tests
        run: npm test || true

      - name: Post PR comment (if branch has PR)
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR=$(gh pr list --head "${{ github.ref_name }}" --json number --jq '.[0].number')
          if [[ -n "$PR" ]]; then
            gh pr comment "$PR" --body "🤖 Claude の編集 (\`${{ inputs.file_path }}\`) が trigger した CI が完了しました。詳細は [このrun](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) を参照。"
          fi

これだけで「Claude が編集した瞬間に lint + test + PR コメント」が成立する。

5-1. 設計上のポイント

workflow_dispatch を使うことで git push 不要でワークフローを起動できる
inputs.file_path を引数で受け取り、CI 内で何が編集されたかを把握できる
PR コメントは「該当ブランチに紐づく PR があれば」で gracefully 動く（main 直編集でもエラーにならない）

6. 実践例: 編集瞬間にレビュー要約を PR に投げる

GitHub Actions 側にもう1ステップ追加すれば、「Claude が編集したコードの diff を別の LLM で要約して PR に投稿」も実装できる。

      - name: Diff summary via Claude API
        if: github.ref_name != 'main'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff HEAD~1..HEAD -- "${{ inputs.file_path }}" | head -c 8000)
          curl -sS https://api.anthropic.com/v1/messages \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "content-type: application/json" \
            -d "$(jq -n --arg diff "$DIFF" '{
              model: "claude-haiku-4-5-20251001",
              max_tokens: 400,
              messages: [{role: "user", content: ("以下の diff を3行で要約: \($diff)")}]
            }')" | jq -r '.content[0].text' > diff-summary.txt
          PR=$(gh pr list --head "${{ github.ref_name }}" --json number --jq '.[0].number')
          [[ -n "$PR" ]] && gh pr comment "$PR" --body-file diff-summary.txt

Haiku 4.5 はトークン単価が極めて安く、1編集あたり数十円未満で要約が回る。Async Hook → GitHub Actions → Haiku API の3段リレーで、**「Claude が編集 → 30秒後に PR コメントに要約が来る」**自動化が完成する。

7. トラブルシューティング3項目

7-1. timeout が頻発する

症状: .claude/logs/async-hooks/ のログが途中で切れる。gh workflow run がタイムアウト。

対策:

.claude/settings.json の timeout を 300 → 600 に上げる
GitHub API のレイテンシーが大きい時間帯（UTC 14:00-18:00）は別経路（HTTP Hooks）の検討も
ネットワーク不調時は gh workflow run を & でバックグラウンド化 + 即時 exit で対処

7-2. payload size 上限に当たる

workflow_dispatch の inputs は1フィールド最大 1024 文字。長いファイルパスや diff を直接渡すと切れる。

対策: 大きな payload は gist 化してから URL だけ渡す。

GIST_URL=$(echo "$LARGE_PAYLOAD" | gh gist create --filename payload.txt -)
gh workflow run claude-ci.yml -f payload_url="$GIST_URL"

7-3. 同時実行で GitHub Actions が暴発する

Claude が3秒間に5回ファイル編集すると、Async Hook が5回 fire し、CI が5本同時に走る。GitHub Actions の同時実行数制限（無料プラン 20本）を即枯渇させる。

対策: 上のスクリプトで導入した flock による排他に加え、GitHub Actions 側でも concurrency 制限を入れる。

concurrency:
  group: claude-ci-${{ github.ref }}
  cancel-in-progress: true

cancel-in-progress: true により、新しい run が走ると古い run は自動キャンセルされる。Claude の連続編集にも耐える。

8. まとめ + 次のステップ

Async Hooks は「Claude を止めない CI/CD 連携」を初めて実用レベルで可能にした機能だ。本記事の手順をなぞれば、.claude/settings.json 1ファイル + ワークフロー1本で、編集瞬間に GitHub Actions が走り、PR コメントまで自動で返る環境が完成する。

次に試す価値が高い拡張は以下の3つ。

HTTP Hooks 経由の Slack 通知: Async Hooks の type を webhook に変えれば Slack incoming webhook に直接投げられる
Cursor / VS Code 拡張との並列連携: Async Hooks は他 IDE のターミナル経由でも動くため、Cursor 連携も同じ仕組みで構築できる
fan-out パターン: 1回の編集で「テスト / lint / セキュリティスキャン / ドキュメント生成」の4本を並列起動するワークフロー設計

学習リソースとしては、Coloso（コロソ） の DevOps / CI/CD 系オンライン講座が体系的だ。買い切り型で自分のペースで進められるため、副業や転職準備の合間にも学習しやすい。

フリーランスや転職でのキャリアアップを視野に入れている場合は、TechGo（テックゴー）の無料キャリア面談で、Async Hooks レベルの CI/CD 経験がどの程度の単価レンジに位置するかを把握しておくと、案件選びの判断軸が増える。

筆者注: 本記事の設定例は Claude Code 2.1.128 で動作検証済みだが、Hooks 仕様は Claude Code の minor バージョンで頻繁に拡張される。実装後は公式 Hooks ドキュメントを四半期ごとに見直すことを推奨する。

Claude Code Async Hooks × GitHub Actions 連携ガイド2026：CI/CDパイプラインを10分で自動化する実践チュートリアル

Claude Code Async Hooks × GitHub Actions 連携ガイド2026：CI/CDパイプラインを10分で自動化する実践チュートリアル

1. Async Hooks とは — 同期 Hooks との3つの違い

1-1. Hooks 機能のおさらい

1-2. Async Hooks がもたらすもの

1-3. 「いつ Async を使うべきか」の判断軸

2. なぜ Async Hooks が「CI/CD 連携の決定打」なのか

2-1. 従来手法の限界

2-2. 実務インパクト（筆者観測値・n=1事例）

3. 前提環境チェック（30秒）

4. 10分セットアップ — .claude/settings.json の async hook 定義

4-1. 最小構成

4-2. trigger スクリプト本体

4-3. 動作確認

5. GitHub Actions ワークフロー側の実装（5分）

5-1. 設計上のポイント

6. 実践例: 編集瞬間にレビュー要約を PR に投げる

7. トラブルシューティング3項目

7-1. timeout が頻発する

7-2. payload size 上限に当たる

7-3. 同時実行で GitHub Actions が暴発する

8. まとめ + 次のステップ

関連記事

4. 10分セットアップ — `.claude/settings.json` の async hook 定義