Claude Code HTTP Hooks × GitHub Actions Integration Guide — Production Patterns for Automated Code Review, Testing, and Deployment

// webhook-server/src/index.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import { bearerAuth } from "hono/bearer-auth";
import { Octokit } from "@octokit/rest";
 
type Bindings = {
  CLAUDE_HOOK_SECRET: string;
  GITHUB_TOKEN: string;
  REPO_OWNER: string;
  REPO_NAME: string;
};
 
const app = new Hono<{ Bindings: Bindings }>();
 
app.use("*", cors({ origin: "https://claude.ai" }));
 
// ─── File-changed hook ────────────────────────────────────
app.post(
  "/hooks/file-changed",
  bearerAuth({ token: (c) => c.env.CLAUDE_HOOK_SECRET }),
  async (c) => {
    const payload = await c.req.json();
    const { tool_name, tool_input, tool_response, session_id } = payload;
 
    if (!tool_name || !session_id) {
      return c.json({ error: "Invalid payload" }, 400);
    }
 
    const filePath: string = tool_input?.path || tool_input?.file_path || "";
    const content: string = tool_response?.content || "";
 
    // Only check JS/TS files
    if (!filePath.match(/\.(ts|tsx|js|jsx)$/)) {
      return c.json({ decision: "proceed", message: "Non-JS file, skipping check" });
    }
 
    const issues: string[] = [];
 
    if (content.includes("console.log(")) {
      issues.push("⚠️ console.log statement detected");
    }
 
    const todoCount = (content.match(/\/\/ TODO/g) || []).length;
    if (todoCount > 3) {
      issues.push(`⚠️ ${todoCount} TODO comments found`);
    }
 
    if (content.match(/["']([A-Za-z0-9+/]{40,})["']/)) {
      issues.push("🚨 Possible hardcoded secret detected");
    }
 
    if (issues.length > 0) {
      return c.json({
        decision: "block",
        reason: `Code quality issues detected:\n${issues.join("\n")}`,
      });
    }
 
    return c.json({ decision: "proceed" });
  }
);
 
// ─── Session-complete hook ────────────────────────────────
app.post(
  "/hooks/session-complete",
  bearerAuth({ token: (c) => c.env.CLAUDE_HOOK_SECRET }),
  async (c) => {
    const { session_id } = await c.req.json();
    const prNumber = parseInt(process.env.GITHUB_PR_NUMBER || "0");
 
    if (prNumber > 0) {
      const octokit = new Octokit({ auth: c.env.GITHUB_TOKEN });
      await octokit.issues.createComment({
        owner: c.env.REPO_OWNER,
        repo: c.env.REPO_NAME,
        issue_number: prNumber,
        body: `## 🤖 Claude Code Review Complete\n\nSession ID: \`${session_id}\`\n\nAutomated review finished. Check the transcript for details.`,
      });
    }
 
    return c.json({ success: true });
  }
);
 
export default app;

# .github/workflows/claude-code-review.yml
name: Claude Code Review
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Get changed files
        id: changed-files
        run: |
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | head -20)
          echo "files<<EOF" >> $GITHUB_OUTPUT
          echo "$CHANGED" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
 
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_HOOK_SECRET: ${{ secrets.CLAUDE_HOOK_SECRET }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          CHANGED_FILES="${{ steps.changed-files.outputs.files }}"
 
          claude --dangerously-skip-permissions \
            --print \
            --settings .claude/settings.json \
            "Please review the following changed files for bugs, security issues,
            performance problems, and coding convention violations.
            Provide specific, actionable feedback for each issue found.
 
            Changed files:
            $CHANGED_FILES
 
            After the review, post the results as a GitHub PR comment." \
            2>&1 | tee review-output.txt
 
      - name: Post review results
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const output = fs.readFileSync('review-output.txt', 'utf8').slice(-3000);
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🤖 Claude Code Automated Review\n\n\`\`\`\n${output}\n\`\`\``
            });

# .github/workflows/claude-auto-fix.yml
name: Claude Code Auto Fix
 
on:
  workflow_run:
    workflows: ["Tests"]
    types: [completed]
 
jobs:
  auto-fix:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Download test logs
        uses: actions/download-artifact@v4
        with:
          name: test-results
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Analyze failures with Claude Code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          TEST_LOG=$(cat test-results.txt 2>/dev/null || echo "Could not retrieve test log")
 
          claude --dangerously-skip-permissions \
            --print \
            "Analyze the following test failure log.
 
            1. Identify the root cause of the failure
            2. Explain the fix in concrete terms
            3. Provide a code snippet if possible
 
            Output your answer in clean markdown suitable for a GitHub PR comment.
 
            ===Test Log===
            $TEST_LOG
            ===" \
            > fix-suggestion.txt 2>&1
 
      - name: Post fix suggestion
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const suggestion = fs.readFileSync('fix-suggestion.txt', 'utf8');
            const prs = await github.rest.pulls.list({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'open',
              head: context.ref
            });
            if (prs.data.length > 0) {
              await github.rest.issues.createComment({
                issue_number: prs.data[0].number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: `## 🔧 Claude Code Test Failure Analysis\n\n${suggestion}`
              });
            }

# .github/workflows/claude-version-bump.yml
name: Claude Code Version Bump
 
on:
  push:
    branches: [main]
 
jobs:
  version-bump:
    runs-on: ubuntu-latest
    permissions:
      contents: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 10
          token: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Determine version bump
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          COMMITS=$(git log --oneline -10)
          DIFF=$(git diff HEAD~5..HEAD --stat)
 
          BUMP_TYPE=$(claude --dangerously-skip-permissions --print \
            "Based on the commits and diff below, determine the semantic version bump.
            Output EXACTLY ONE of: patch, minor, or major — no other text.
 
            Rules:
            - Breaking changes → major
            - New features (backward-compatible) → minor
            - Bug fixes / refactoring → patch
 
            Commits:
            $COMMITS
 
            File changes:
            $DIFF" 2>&1 | tr -d '[:space:]')
 
          if [[ "$BUMP_TYPE" != "patch" && "$BUMP_TYPE" != "minor" && "$BUMP_TYPE" != "major" ]]; then
            BUMP_TYPE="patch"
          fi
 
          echo "BUMP_TYPE=$BUMP_TYPE" >> $GITHUB_ENV
          echo "Version bump determined: $BUMP_TYPE"
 
      - name: Bump version
        run: |
          npm version ${{ env.BUMP_TYPE }} --no-git-tag-version
          git config user.email "bot@example.com"
          git config user.name "Claude Code Bot"
          git add package.json package-lock.json
          git commit -m "chore: bump version [${{ env.BUMP_TYPE }}] via Claude Code"
          git push

const authHeader = request.headers.get("Authorization");
if (!authHeader || authHeader !== `Bearer ${env.CLAUDE_HOOK_SECRET}`) {
  return new Response("Unauthorized", { status: 401 });
}

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyHmacSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const hmac = createHmac("sha256", secret);
  hmac.update(payload);
  const expected = `sha256=${hmac.digest("hex")}`;
  // Use timingSafeEqual to prevent timing attacks
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
 
const signature = request.headers.get("X-Claude-Signature") || "";
const body = await request.text();
if (!verifyHmacSignature(body, signature, env.CLAUDE_HOOK_SECRET)) {
  return new Response("Invalid signature", { status: 401 });
}

// ✅ Correct: reference environment variables
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "http",
            "url": "${WEBHOOK_URL}",
            "headers": {
              "Authorization": "Bearer ${CLAUDE_HOOK_SECRET}"
            }
          }
        ]
      }
    ]
  }
}

// Advanced quality check: ESLint + TypeScript type checking
async function runQualityCheck(
  filePath: string,
  content: string
): Promise<{ pass: boolean; issues: string[] }> {
  const issues: string[] = [];
 
  // 1. ESLint check (in-memory)
  const eslintResult = await runEslint(content, filePath);
  if (eslintResult.errorCount > 0) {
    eslintResult.messages
      .filter((m) => m.severity === 2)
      .forEach((m) => issues.push(`ESLint error (L${m.line}): ${m.message}`));
  }
 
  // 2. TypeScript type check (incremental)
  const tsResult = await runTsc(filePath, content);
  if (tsResult.errors.length > 0) {
    tsResult.errors
      .slice(0, 3) // Cap at 3 to avoid overwhelming Claude
      .forEach((e) => issues.push(`TypeScript error: ${e.messageText}`));
  }
 
  // 3. Security pattern check
  const securityIssues = checkSecurityPatterns(content);
  issues.push(...securityIssues);
 
  return { pass: issues.length === 0, issues };
}

app.post("/hooks/notification", bearerAuth(...), async (c) => {
  const { message, session_id } = await c.req.json();
 
  await fetch(c.env.SLACK_WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `🤖 *Claude Code Progress*\nSession: \`${session_id}\`\n\n${message}`,
      channel: "#dev-automation",
    }),
  });
 
  return c.json({ success: true });
});

# wrangler.toml
name = "claude-hooks-server"
main = "src/index.ts"
compatibility_date = "2026-03-01"
 
[vars]
REPO_OWNER = "your-org"
REPO_NAME = "your-repo"
 
# Set secrets with: wrangler secret put <KEY>
# CLAUDE_HOOK_SECRET
# GITHUB_TOKEN
# SLACK_WEBHOOK_URL

wrangler deploy
 
wrangler secret put CLAUDE_HOOK_SECRET
wrangler secret put GITHUB_TOKEN

# Start local dev server
npm run dev  # listening on localhost:8787
 
# Create a public tunnel
ngrok http 8787
 
# Update .claude/settings.json to point at the ngrok URL
# "url": "https://xxxx.ngrok-free.app/hooks/file-changed"

// webhook-server/src/logger.ts
type LogLevel = "info" | "warn" | "error" | "debug";
 
interface LogEntry {
  timestamp: string;
  level: LogLevel;
  event: string;
  session_id?: string;
  tool_name?: string;
  decision?: string;
  duration_ms?: number;
  [key: string]: unknown;
}
 
export function log(level: LogLevel, event: string, meta: Partial<LogEntry> = {}) {
  const entry: LogEntry = {
    timestamp: new Date().toISOString(),
    level,
    event,
    ...meta,
  };
  // In Cloudflare Workers, console.log streams to Workers Logs
  console.log(JSON.stringify(entry));
}
 
// Usage in your hook handler
const start = Date.now();
const result = await runQualityCheck(filePath, content);
log("info", "quality_check_complete", {
  session_id,
  tool_name,
  filePath,
  decision: result.pass ? "proceed" : "block",
  issue_count: result.issues.length,
  duration_ms: Date.now() - start,
});

// Simple metrics using Cloudflare Workers Analytics Engine
async function recordMetric(
  env: Bindings,
  event: string,
  data: Record<string, number | string>
) {
  if (!env.ANALYTICS) return; // Optional binding
  env.ANALYTICS.writeDataPoint({
    blobs: [event, data.decision as string || ""],
    doubles: [data.duration_ms as number || 0],
    indexes: [event],
  });
}
 
// In your hook handler
await recordMetric(env, "hook_invocation", {
  decision: result.pass ? "proceed" : "block",
  duration_ms: Date.now() - start,
});

// Debug endpoint — never expose in production
app.post("/debug/echo", async (c) => {
  if (c.env.NODE_ENV !== "development") {
    return c.json({ error: "Not available in production" }, 403);
  }
  const payload = await c.req.json();
  console.log("Hook payload:", JSON.stringify(payload, null, 2));
  return c.json({ decision: "proceed", echo: payload });
});

// Propagate session_id as a trace header to downstream services
async function callDownstreamService(
  url: string,
  payload: unknown,
  sessionId: string
) {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Session-Id": sessionId, // Carry session_id through the call chain
      "X-Request-Id": crypto.randomUUID(),
    },
    body: JSON.stringify(payload),
  });
  return response.json();
}

# .github/workflows/claude-code-review.yml (with graceful degradation)
jobs:
  check-webhook-health:
    runs-on: ubuntu-latest
    outputs:
      healthy: ${{ steps.health.outputs.healthy }}
    steps:
      - id: health
        run: |
          STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
            https://your-webhook-server.example.com/health)
          if [ "$STATUS" = "200" ]; then
            echo "healthy=true" >> $GITHUB_OUTPUT
          else
            echo "healthy=false" >> $GITHUB_OUTPUT
            echo "⚠️ Webhook server is degraded (status $STATUS). Continuing without hooks."
          fi
 
  review:
    needs: check-webhook-health
    if: needs.check-webhook-health.outputs.healthy == 'true'
    # ... rest of review job

// Use a cache (KV, Redis, or in-memory) to deduplicate based on session_id + tool call index
const dedupeKey = `${session_id}:${tool_call_index}`;
const cached = await env.KV.get(dedupeKey);
if (cached) {
  // Already processed — return the cached decision
  return c.json(JSON.parse(cached));
}
 
const result = await processHook(payload);
 
// Cache with a short TTL (e.g., 5 minutes)
await env.KV.put(dedupeKey, JSON.stringify(result), { expirationTtl: 300 });
return c.json(result);

async function withRetry<T>(
  fn: () => Promise<T>,
  maxAttempts = 3,
  baseDelayMs = 200
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxAttempts) throw error;
      const delay = baseDelayMs * Math.pow(2, attempt - 1);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
  throw new Error("Unreachable");
}
 
// Usage
const eslintResult = await withRetry(() => runEslint(content, filePath));