Running Claude Code in CI: Headless Mode & GitHub Actions

Everything Claude Code does interactively, it can do unattended: triage an issue, fix a failing test, review a PR, draft release notes on a schedule. The interactive session is one frontend; this guide covers the other two — the headless CLI and the GitHub Action — and the permission discipline that makes unattended runs safe.

Headless mode: claude -p

claude -p "Find and fix the failing test in auth.test.ts"

That's the whole interface. The full agent runs — searching files, editing, executing commands under your permission rules — and prints the result. It composes like a Unix tool:

cat error.log | claude -p "Explain the root cause in two sentences"

Output formats are where headless gets practical:

• --output-format json — the result plus metadata your script wants: result, session_id, usage, and total_cost_usd (track spend per CI run).
• --output-format stream-json — newline-delimited events for live streaming.
• --json-schema '<schema>' — enforce a shape; the response includes a validated structured_output field. Extraction tasks stop being prompt-and-pray.

Session flags carry over from interactive use: --continue resumes the most recent session in the directory, --resume <id> picks a specific one — so a multi-step pipeline can keep one conversation across steps.

Scoping flags are the safety story:

claude -p "Fix the lint errors" \
  --allowedTools "Read,Edit,Bash(npm run lint:*)" \
  --permission-mode acceptEdits \
  --max-turns 10

--allowedTools/--disallowedTools pre-approve exactly what the run may do (same rule syntax as settings), and --max-turns is the circuit breaker. One more flag earns its keep in CI: --bare skips hooks, skills, plugins, CLAUDE.md, and MCP auto-discovery for a fast, deterministic start — then you add back only what the job needs via --settings, --mcp-config, or --append-system-prompt. Auth in CI is ANTHROPIC_API_KEY (or Bedrock/Vertex credentials); piped stdin is capped at 10MB; transient API errors retry automatically.

The GitHub Action

The official integration is anthropics/claude-code-action@v1, and the fastest setup is one command from the repo:

claude /install-github-app

It installs the GitHub App, stores the ANTHROPIC_API_KEY secret, and scaffolds the workflow. The minimal file it produces looks like:

name: Claude Code
on:
  issue_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

The action auto-detects its mode: with no prompt input, it listens for @claude mentions on issues, PRs, and review comments — "@claude fix the type error in this file" gets a commit on a branch and a PR. With a prompt input, it runs immediately on whatever trigger you chose, which is how you build scheduled jobs (nightly dependency audit), PR-opened reviewers, or release-notes generators.

Tuning happens through claude_args, which forwards the same CLI flags you proved out locally:

        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for security issues and comment your findings"
          claude_args: "--max-turns 12 --model claude-sonnet-4-6"

It can also load plugins and MCP servers (plugins:, plugin_marketplaces: inputs), run skills with prompt: "/skill-name", and authenticate via Bedrock or Vertex (use_bedrock / use_vertex with OIDC) instead of a static key.

The safety model for unattended runs

A CI agent is code with write access to your repo. The discipline:

• Minimum tools. The narrowest --allowedTools that completes the task. A reviewer needs Read and a comment path — not Bash.
• Bounded runs. --max-turns always; treat a hit limit as a failed job, not a retry loop.
• Trusted triggers only. @claude mentions are gated by the App's permissions, but be deliberate about workflows that run on fork PRs with secrets in scope.
• Human merge gate. The action deliberately cannot approve PRs — it writes code, you keep review. Don't engineer around that.
• Same guardrails as local. Permission rules and hooks checked into the repo apply to CI runs too — a deny-rule on secrets protects the bot exactly as it protects you.

When a workflow outgrows YAML — multi-step pipelines, custom tools, your own orchestration — the same engine is available as a library: that's the Claude Agent SDK.