CI/CD Integration

Your GitHub Action with Claude works perfectly — until a rate limit hits mid-review, the step fails, and the entire pipeline blocks for 20 minutes. Running Claude in CI means planning for failures you don’t see in interactive mode.

Claude Code runs headless in CI/CD pipelines for automated code review, test generation, documentation, and more. The official GitHub Action provides turnkey integration, while the CLI’s --print mode enables custom pipeline workflows with explicit cost caps and retry logic.

GitHub Action

The anthropics/claude-code-action@v1 action wraps the CLI with sensible CI defaults. It auto-detects whether it is running on a PR or issue event, injects the diff context, and posts Claude’s response as a comment.

The action handles checkout, context injection, and comment posting automatically. You supply a prompt, your API key, and an optional budget cap. For more control, you can install the CLI directly and run it yourself.

CI Flags

Every CI invocation needs a specific set of flags to run safely in a headless environment. Here is the breakdown.

The minimum viable CI invocation combines four of these flags:

claude -p "Review this code for bugs" \
  --output-format json \
  --max-budget-usd 0.50 \
  --no-session-persistence \
  --permission-mode bypassPermissions

Custom Pipelines

Beyond GitHub Actions, you can embed Claude in any CI system — GitLab CI, Jenkins, CircleCI, or a plain bash script. The pattern is the same everywhere: capture JSON output, parse with jq, and act on the result.

Cost-Capped PR Review:

claude -p "Review the changes in this PR" \
  --from-pr "$PR_URL" \
  --output-format json \
  --max-budget-usd 0.50 \
  --no-session-persistence \
  --permission-mode bypassPermissions

Batch File Processing:

for file in src/**/*.ts; do
  claude -p "Add JSDoc comments to $file" \
    --output-format json \
    --max-budget-usd 0.10 \
    --no-session-persistence \
    --permission-mode bypassPermissions
done

Each invocation is fully isolated — no session state leaks between files.

Plan-Review-Execute in CI:

A three-step workflow: generate a plan, post it for human review, then execute on approval.

# Step 1: Generate plan
PLAN_RESULT=$(claude -p "Fix all lint errors in src/" \
  --permission-mode plan \
  --output-format json \
  --max-budget-usd 0.50)

# Step 2: Post plan as PR comment
PLAN=$(echo "$PLAN_RESULT" | jq -r \
  '.permission_denials[] | select(.tool_name == "ExitPlanMode") | .tool_input.plan')
gh pr comment "$PR_NUMBER" --body "$PLAN"

# Step 3: On approval, execute
SESSION=$(echo "$PLAN_RESULT" | jq -r '.session_id')
claude -p "yes, proceed" \
  --resume "$SESSION" \
  --permission-mode bypassPermissions

In plan mode, Claude’s proposed changes appear as permission_denials with tool_name: "ExitPlanMode". The plan text lives in the tool_input.plan field.

CI Response Payload

Here is a real response from a CI run with --no-session-persistence, --max-budget-usd 0.50, and --output-format json.

Key fields to parse in your CI scripts:

• is_error / subtype — check for "error_max_budget_usd" to detect budget exceeded
• total_cost_usd — aggregate across pipeline steps for total CI run cost
• result — the actual output text
• session_id — present even with --no-session-persistence (valid during process lifetime only)
• stop_reason — "end_turn" means normal completion; other values indicate interruption

Parsing the Result in Bash

#!/usr/bin/env bash
set -euo pipefail

RESULT=$(claude -p "Review this diff for bugs" \
  --output-format json \
  --max-budget-usd 0.50 \
  --no-session-persistence \
  --permission-mode bypassPermissions)

# Check for budget exceeded
SUBTYPE=$(echo "$RESULT" | jq -r '.subtype // ""')
if [ "$SUBTYPE" = "error_max_budget_usd" ]; then
  echo "::error::Claude exceeded budget cap"
  exit 1
fi

# Extract result and cost
REVIEW=$(echo "$RESULT" | jq -r '.result')
COST=$(echo "$RESULT" | jq -r '.total_cost_usd')

echo "Review cost: $COST"
echo "$REVIEW"

The ::error:: prefix is GitHub Actions syntax for surfacing errors in the workflow summary. Replace it with your CI system’s equivalent.

--from-pr PR Review Workflow

The --from-pr flag injects PR context into a session, enabling automated code review:

# Review a PR by number (must be in the correct git repo)
claude -p "Review this PR for security issues" \
  --from-pr 42 \
  --output-format json \
  --max-budget-usd 0.25 \
  --permission-mode bypassPermissions

# Review by full URL
claude -p "Summarize what this PR changes" \
  --from-pr "https://github.com/org/repo/pull/42" \
  --output-format json

Experimentally confirmed behaviors:

• Both PR number and URL formats are accepted syntactically
• Not a data pre-loader — --from-pr signals to the model that a PR review is requested. The model then uses tools (gh pr view, gh pr diff, git log) to investigate. This means it requires tool permissions and sufficient budget for multiple turns
• Budget consideration — PR reviews are multi-turn operations. A $0.10 budget may not be sufficient for large PRs. Use $0.25+ for thorough reviews
• Graceful degradation — invalid PR numbers and non-git directories produce helpful messages, not crashes
• GitHub auth — for private repos, the gh CLI must be authenticated via GITHUB_TOKEN

CI/CD Resilience Patterns

Your CI pipeline with Claude works 95% of the time. The other 5%, the API returns a 529, your step fails, and the entire PR workflow blocks for 20 minutes while developers wait. Production pipelines need retry logic, fallback models, and graceful degradation — not just a Claude command.

CI pipelines fail. APIs return 500s, rate limits kick in, networks drop. The --fallback-model flag handles one failure mode (429 rate limiting), but production pipelines need explicit retry logic, error classification, and graceful degradation to stay reliable.

Retry Patterns

The --fallback-model flag only handles 429 overload errors. For other transient failures — network errors, timeouts, API 500s — you need explicit retry logic.

Bash Retry Function

retry_claude() {
    local max_retries=3 prompt="$1"; shift
    for attempt in $(seq 1 "$max_retries"); do
        if RESULT=$(claude -p "$prompt" "$@" 2>/dev/null); then
            if echo "$RESULT" | jq -e '.is_error != true' >/dev/null 2>&1; then
                echo "$RESULT"
                return 0
            fi
        fi
        echo "Attempt $attempt/$max_retries failed, retrying in $((attempt * 5))s..." >&2
        sleep "$((attempt * 5))"
    done
    echo "All $max_retries attempts failed" >&2
    return 1
}

The function validates two things on each attempt: that the CLI process exited successfully, and that the JSON response does not have is_error: true. Backoff increases linearly — 5 seconds, 10 seconds, 15 seconds.

Node.js Retry Function

For Node.js pipelines, the same pattern translates directly:

async function retryClaudeSync(args, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            const output = execFileSync('claude', args, {
                encoding: 'utf-8', timeout: 120_000,
                env: { ...process.env, CLAUDECODE: '' }
            });
            const data = JSON.parse(output);
            if (!data.is_error) return data;
        } catch (err) { /* retry */ }
        if (attempt < maxRetries) {
            await new Promise(r => setTimeout(r, attempt * 5000));
        }
    }
    throw new Error(`All ${maxRetries} attempts failed`);
}

Advanced Retry with Error Classification

Not all errors deserve retries. Auth failures (401/403) will never succeed on retry. Budget errors mean the work is done but exceeded limits. Only transient failures benefit from retrying:

retry_claude_smart() {
    local max_retries=3 prompt="$1"; shift
    for attempt in $(seq 1 "$max_retries"); do
        RESULT=$(claude -p "$prompt" "$@" 2>&1) && {
            SUBTYPE=$(echo "$RESULT" | jq -r '.subtype // ""')
            case "$SUBTYPE" in
                error_max_budget_usd)
                    echo "Budget exceeded — not retrying" >&2
                    echo "$RESULT"; return 1 ;;
                success)
                    echo "$RESULT"; return 0 ;;
                *)
                    # Unknown subtype — check is_error
                    if echo "$RESULT" | jq -e '.is_error != true' >/dev/null 2>&1; then
                        echo "$RESULT"; return 0
                    fi ;;
            esac
        }
        # Check for auth failure (non-JSON exit)
        if echo "$RESULT" | grep -qi "unauthorized\|forbidden\|invalid.*key"; then
            echo "Auth failure — not retrying" >&2
            return 1
        fi
        echo "Attempt $attempt/$max_retries failed, retrying in $((attempt * 5))s..." >&2
        sleep "$((attempt * 5))"
    done
    echo "All $max_retries attempts failed" >&2
    return 1
}

This version distinguishes between retryable failures (network errors, 500s, timeouts) and permanent failures (auth errors, budget exceeded) to avoid wasting time and money on doomed retries.

Fallback Models

The --fallback-model flag provides a backup when the primary model is rate-limited:

claude -p "Review this PR" \
  --fallback-model claude-haiku-4-5-20251001 \
  --max-budget-usd 0.50

There is a critical limitation here. Fallback only triggers on HTTP 429 (rate limiting). It does not trigger on other failures:

This means --fallback-model is not a general resilience mechanism. Combine it with the retry function above for full coverage.

Full Resilience Pipeline

Combining retry logic, fallback models, error classification, and budget controls gives you a production-ready pipeline function:

#!/usr/bin/env bash
set -euo pipefail

# Production-grade CI wrapper
ci_claude() {
    local prompt="$1"
    local budget="${2:-0.50}"
    local max_retries="${3:-3}"

    for attempt in $(seq 1 "$max_retries"); do
        RESULT=$(claude -p "$prompt" \
            --output-format json \
            --max-budget-usd "$budget" \
            --fallback-model claude-haiku-4-5-20251001 \
            --no-session-persistence \
            --permission-mode bypassPermissions 2>/dev/null) && {

            SUBTYPE=$(echo "$RESULT" | jq -r '.subtype // ""')

            if [ "$SUBTYPE" = "error_max_budget_usd" ]; then
                echo "::warning::Budget exceeded on attempt $attempt" >&2
                echo "$RESULT"
                return 1
            fi

            if echo "$RESULT" | jq -e '.is_error != true' >/dev/null 2>&1; then
                # Log cost for aggregation
                COST=$(echo "$RESULT" | jq -r '.total_cost_usd // 0')
                echo "::notice::Claude call cost: \$$COST (attempt $attempt)" >&2
                echo "$RESULT"
                return 0
            fi
        }

        if [ "$attempt" -lt "$max_retries" ]; then
            DELAY=$((attempt * 5))
            echo "::warning::Attempt $attempt/$max_retries failed, retrying in ${DELAY}s..." >&2
            sleep "$DELAY"
        fi
    done

    echo "::error::All $max_retries attempts failed" >&2
    return 1
}

# Usage
REVIEW=$(ci_claude "Review this PR for security issues" 1.00 3)
echo "$REVIEW" | jq -r '.result'

This wrapper combines all the resilience patterns: retry with backoff, fallback model for rate limiting, budget cap enforcement, error classification, and GitHub Actions annotation output (::warning::, ::error::, ::notice::).

Error Handling in CI

Budget Exceeded Detection

SUBTYPE=$(echo "$RESULT" | jq -r '.subtype // ""')
if [ "$SUBTYPE" = "error_max_budget_usd" ]; then
  echo "::error::Claude exceeded budget cap"
  exit 1
fi

The ::error:: prefix is GitHub Actions syntax for surfacing errors in the workflow summary. Replace it with your CI system’s equivalent.

Missing API Key

Hooks in Headless Mode

Resilience Next Steps

With resilience patterns in place, your CI pipelines can handle transient failures without human intervention. For managing the cost of running these pipelines at scale, see Budget Controls and Cost at Scale.