# Running Claude Code in CI/CD with GitHub Actions and headless mode

URL: https://developertoolkit.ai/en/claude-code/ship/ci-cd-integration/
Description: Run Claude Code in GitHub Actions and headless CI jobs for @claude requests, PR review, issue-to-PR and CI auto-fix, with gates, security and cost caps.

Claude Code runs in CI/CD through the `anthropics/claude-code-action@v1` GitHub Action and through headless mode (`claude -p`) in any other pipeline. The action answers `@claude` mentions or runs a fixed prompt on any GitHub event, such as a label or a failed build. Every run is bounded by tool allowlists, turn limits and the same required checks as human code.

Your team opens 30 pull requests a week, each waits half a day for a first human pass, and the build breaks twice a week on a forgotten lint rule. You want an agent in the pipeline that cannot push a deleted test to green or leak a secret to a stranger's pull request. This page is for the developer who wires the workflows and the tech lead who decides what they are allowed to do.

## What a working Claude Code CI setup gives you

- An `@claude` workflow that answers requests in issue and pull request comments
- An automatic review pass on every pull request that posts inline findings, plus a custom security-focused review prompt
- A labelled-issue-to-pull-request job with a spec gate in front of it
- A CI auto-fix workflow that cannot delete or skip a test to go green and never runs the branch's code next to your API key, because a separate job with no secrets re-runs the gate before anything is pushed
- A headless `claude -p` recipe for GitLab, Jenkins or any runner, with structured JSON output a script can gate on
- Bedrock, Google Cloud and Foundry configurations, cost caps, and the failure modes to expect in the first week

## Which Claude Code CI entry point should you use?

| You want                                              | Use                                                                             | Result lands in                              |
| ----------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------- |
| Ad hoc requests from people on issues and PRs         | The action with no `prompt` input (interactive mode)                            | A comment Claude updates as it works         |
| A fixed task on an event (PR opened, label, schedule) | The action with a `prompt` input (automation mode)                              | The run log, or a comment if the prompt asks |
| Review on every PR without maintaining a workflow     | Managed [Code Review](https://code.claude.com/docs/en/code-review) (Team and Enterprise plans, GitHub) | Inline PR comments                           |
| Claude in GitLab, Jenkins, Buildkite or a cron box    | Headless `claude -p` in a script                                                | stdout, JSON you parse                       |
| A recurring task that needs no repository event       | [Routines](/en/claude-code/automate/routines/)                                  | A cloud session                              |

With no `prompt` the action waits for the trigger phrase (`@claude` by default); with one it runs immediately. For the pipeline YAML itself (caching, matrices, path filters) see [pipeline configuration using Claude Code](/en/claude-code/ship/ci-cd/). This page covers the agent running inside that pipeline.

## Install the Claude GitHub App and the @claude workflow

1. **Run the installer from a local session.** Install the [GitHub CLI](https://cli.github.com) and run `gh auth login`. Open `claude` in the repository and enter `/install-github-app`. You need admin access to the repository, and the command works only for github.com remotes. It installs the Claude GitHub App and stores a repository secret: `ANTHROPIC_API_KEY` for an API key, or `CLAUDE_CODE_OAUTH_TOKEN` for a subscription token (generate one with `claude setup-token`).

2. **Merge the workflow pull request it opens.** The installer pushes a branch with `claude.yml` (and `claude-code-review.yml` if you select the review workflow) and opens GitHub on a ready pull request. Merging it activates `@claude`.

3. **Or add the workflow by hand.** Use manual setup for Bedrock, Google Cloud or Foundry, or when you want to control the file. Install the [Claude GitHub App](https://github.com/apps/claude), add the secret, and commit this file:

   ```yaml
   # .github/workflows/claude.yml
   name: Claude Code
   on:
     issue_comment:
       types: [created]
     pull_request_review_comment:
       types: [created]
   jobs:
     claude:
       if: contains(github.event.comment.body, '@claude')
       runs-on: ubuntu-latest
       timeout-minutes: 30
       permissions:
         contents: write
         pull-requests: write
         issues: write
         id-token: write   # the action's GitHub App authentication
         actions: read     # lets Claude read CI results on the PR
       steps:
         - uses: actions/checkout@v7
           with:
             fetch-depth: 1
             persist-credentials: false
         - uses: anthropics/claude-code-action@v1
           with:
             anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
             claude_args: '--max-turns 30'
   ```

4. **Test it.** Comment `@claude fix the TypeError in the dashboard component` on an issue. Claude replies in a comment it updates as it works and commits to a new branch. Its comment links to GitHub's pull request page, so a person decides what gets proposed.

**Who can start a run**

Before Claude starts, the action rejects any actor without write access to the repository and any bot not listed in `allowed_bots`. That check is your first control on a public repository. Do not widen it with `allowed_non_write_users` on a workflow that can write code.

On a pull request, the action restores Claude's own configuration paths from the base branch before Claude starts: `.claude/`, `.mcp.json`, `.claude.json`, `CLAUDE.md`, `CLAUDE.local.md`, `.husky/` and a few others. A pull request therefore cannot bring its own hooks or MCP servers. Everything else stays at the pull request's head, including `package.json`, so a base-branch hook that calls `npm run format` runs a script the pull request wrote. Call tools directly, with a pinned version (the action's `docs/security.md`, read 2026-09-26).

### Which action inputs exist, and which are silently ignored?

The common inputs are `prompt`, `claude_args`, `anthropic_api_key` or `claude_code_oauth_token`, `github_token`, `settings`, `plugins`, `plugin_marketplaces`, `trigger_phrase`, `track_progress`, `allowed_bots`, and `use_bedrock`, `use_vertex` or `use_foundry` (full list in [`action.yml`](https://github.com/anthropics/claude-code-action/blob/main/action.yml)). The beta-era `model`, `max_turns`, `timeout_minutes`, `direct_prompt` and `custom_instructions` do not exist in v1 (`action.yml` on `main`, 2026-09-26): GitHub prints an "Unexpected input" warning and the run continues with defaults. Move CLI options into `claude_args`:

- `--model claude-sonnet-5` pins the model. Without it the action uses the Claude Code default model, so the per-run cost moves when the default moves. See the [models hub](/en/ecosystem/models/) before choosing.
- `--max-turns 10` ends the run with an error when Claude reaches the limit.
- `--allowedTools "..."` grants tools. In automation mode Claude has no shell and no GitHub API access beyond what you grant.
- `--append-system-prompt "..."` replaces the old `custom_instructions`.

The job clock is GitHub's own `timeout-minutes:` on the job, not an action input.

To store no long-lived Claude credential, the action can exchange the workflow's OIDC token for API access through a Claude Console service account. Set `anthropic_federation_rule_id` and `anthropic_organization_id` (plus `anthropic_service_account_id` or `anthropic_workspace_id` when the rule needs them) and keep `id-token: write`. If you share one secret across an organization, make it a Console API key: a `CLAUDE_CODE_OAUTH_TOKEN` is tied to the subscription of whoever ran `claude setup-token`.

## Review every pull request with Claude Code

The quick setup's review workflow runs the `code-review` plugin from Anthropic's `claude-code` marketplace. This is the same workflow written out, so you control triggers, model and permissions:

```yaml
# .github/workflows/claude-review.yml
name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 20
    concurrency:
      group: claude-review-${{ github.event.pull_request.number }}
      cancel-in-progress: true
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 1
          persist-credentials: false
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
          plugins: 'code-review@claude-code-plugins'
          prompt: '/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'
```

Two lines decide whether anyone sees the review. `--comment` makes Claude post inline comments, or one summary comment when it finds nothing; without it the findings stay in the run log. The action starts the inline-comment MCP server only when `--allowedTools` grants it. On public repositories GitHub withholds secrets from fork pull requests, so this job reviews same-repository branches only.

To make the review follow your house rules, write them in `CLAUDE.md` or in a skill under `.claude/skills/` and invoke it as the prompt (`/security-pass`). The checkout step must run first so the skill files exist on the runner. Custom slash commands are skills now; see [custom commands](/en/claude-code/automate/custom-commands/).

**Copy-paste prompt: security-first PR review**

```text
Review the pull request diff (run `gh pr diff` to read it) as a senior security engineer.
Check, in this order:
1. Security: missing authn/authz checks, injection (SQL, shell, SSRF, path traversal),
   secrets or tokens in code or fixtures, unsafe deserialization.
2. Correctness: unhandled errors and promise rejections, race conditions, off-by-one
   boundaries in pagination and date ranges.
3. Tests: every new branch in the diff has a test that would fail without it. Name the
   branch that has none.
4. Performance: N+1 queries, unbounded loops over request data.

Report only real defects, no style comments. Post each finding as an inline comment on the
exact line, formatted: [HIGH|MEDIUM|LOW] <problem> -> <concrete fix>.
Use mcp__github_inline_comment__create_inline_comment with confirmed: true.
If nothing is HIGH or MEDIUM, post one summary comment saying so and listing what you checked.
```

Use it as the `prompt:` of the workflow above in place of the plugin call, and extend `--allowedTools` with `Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr comment:*)`, so Claude can read the diff and post the summary comment. The prompt's `confirmed: true` line matters too: the action's inline-comment tool holds back unconfirmed comments and classifies them after the session, so a custom prompt without it can see comments delayed or filtered out. The severity labels matter: a review that flags everything equally is ignored by week two, and "nothing HIGH, here is what I checked" is evidence a reviewer can use.

Treat this review as one sensor, not as the approval. What a person reads instead of the whole diff is covered in [reviewing an agent's pull request without reading every line](/en/workflows/ship/agent-pr-review/). For local review before a push, see [review automation](/en/claude-code/ship/review-automation/).

## Turn a labelled issue into a pull request

The label is the spec gate: nothing runs until a person decides the issue has acceptance criteria an agent can meet.

```yaml
# .github/workflows/issue-to-pr.yml
name: Issue to PR
on:
  issues:
    types: [labeled]
permissions: {}
jobs:
  implement:
    # Holds the API key and a read-only token. Claude edits and tests; it cannot push.
    if: >-
      github.event.label.name == 'claude-implement' &&
      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association)
    runs-on: ubuntu-latest
    timeout-minutes: 45
    permissions:
      contents: read
      issues: read
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ github.token }}   # scoped to this job's read-only permissions
          prompt: |
            Implement issue #${{ github.event.issue.number }} in ${{ github.repository }}.
            Read it with `gh issue view ${{ github.event.issue.number }}` and ignore its comments.
            Follow the instructions in .github/claude/implement.md.
            Write the pull request body to ${{ runner.temp }}/pr-body.md.
          claude_args: >-
            --max-turns 40
            --add-dir ${{ runner.temp }}
            --allowedTools "Read,Edit,Write,Glob,Grep,Bash(gh issue view:*),Bash(npm ci),Bash(npm test:*),Bash(npm run lint:*),Bash(npm run typecheck:*)"
      - name: Export Claude's change as a patch
        run: |
          git add -A && git diff --cached --binary > "$RUNNER_TEMP/change.patch"
          [ -s "$RUNNER_TEMP/pr-body.md" ] || echo "Claude wrote no PR body." > "$RUNNER_TEMP/pr-body.md"
      - uses: actions/upload-artifact@v7
        with:
          name: claude-implement
          path: |
            ${{ runner.temp }}/change.patch
            ${{ runner.temp }}/pr-body.md

  open-pr:
    # Holds the write token, never sees the API key, runs nothing Claude wrote.
    needs: implement
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/download-artifact@v8
        with:
          name: claude-implement
          path: ${{ runner.temp }}
      - name: Push claude/issue-N and open a PR, or post Claude's questions
        env:
          GH_TOKEN: ${{ github.token }}
          ISSUE: ${{ github.event.issue.number }}
        run: |
          if [ ! -s "$RUNNER_TEMP/change.patch" ]; then
            gh issue comment "$ISSUE" --body-file "$RUNNER_TEMP/pr-body.md"; exit 0; fi
          BR="claude/issue-$ISSUE"
          git apply --index "$RUNNER_TEMP/change.patch"
          if git diff --cached --name-only | grep '^\.github/'; then
            echo "Refusing: the change touches .github/"; exit 1; fi
          git config user.name "claude[bot]"
          git config user.email "claude[bot]@users.noreply.github.com"
          git switch -c "$BR"
          git commit -m "Implement #$ISSUE"
          git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:refs/heads/$BR"
          gh pr create --head "$BR" --title "Implement #$ISSUE" --body-file "$RUNNER_TEMP/pr-body.md"
```

The prompt passes the issue number, not `${{ github.event.issue.body }}`. Interpolating the body makes the issue author's text part of your instructions; passing the number keeps your instructions yours and leaves the issue as data Claude reads. That lowers prompt-injection risk but does not remove it, so the workflow adds four controls around it:

- **Who wrote the text, and who labelled it.** Triage users can apply the label too, but `claude-code-action` refuses to start for any actor without write or admin access unless you set `allowed_non_write_users`, so only a write-access labeller starts a run. That gate lives in the action (`checkWritePermissions`, checked on `main` at 97c5347, 2026-10-01): replace the action with a plain `claude -p` step and you lose it. The `author_association` condition skips issues not written by an owner, organisation member or collaborator, and `COLLABORATOR` includes read- and triage-level collaborators. Claude reads the issue without its comments, because anyone can comment after the label goes on.
- **No git for Claude.** An allowlist entry such as `Bash(git:*)` is arbitrary shell: `git -c alias.x='!sh -c …' x` runs any command, and the action ships its own `scripts/git-push.sh` wrapper because `git push --receive-pack=…` does the same. Here Claude has no git and a token scoped to `contents: read`.
- **The write token sits in another job.** `open-pr` never sees the API key and runs nothing Claude wrote: it applies the patch, refuses any change under `.github/`, then pushes `claude/issue-<number>` and opens the pull request, or posts Claude's questions on the issue when there is no change.
- **Every checkout uses `persist-credentials: false`**, so no step leaves a token in `.git/config` for a later step to find.

`npm test` is still code execution beside the API key, because Claude writes the tests it runs. That is acceptable here only because both the code (the default branch) and the instructions (a trusted author's issue) are trusted. For issues from outside contributors, use the shape of the CI-fix workflow below: file tools only for Claude and a job with no secrets for the gate. A pull request opened with the workflow's `GITHUB_TOKEN` does not trigger other workflows, so use a GitHub App token in `open-pr` if CI must run on it.

The risk is not theoretical. In the chain security researcher Adnan Khan named "Clinejection", as [Simon Willison summarised it](https://simonwillison.net/2026/Mar/6/clinejection/) on 2026-03-06 (a secondary account), a prompt injected through an issue title into an AI triage workflow built on `claude-code-action` with Bash, Write and Edit tools led to Actions cache poisoning and stolen publish tokens.

**Copy-paste prompt: issue to pull request (save as .github/claude/implement.md)**

```text
You are implementing one GitHub issue end to end.

1. Read the issue body, not its comments. List its acceptance criteria. If there are none, or
   they contradict each other, write only the questions you need answered to the PR body file
   named in your task, change no code, and stop.
2. Write failing tests that encode each acceptance criterion first, then make them pass.
   Do not edit or delete existing tests unless the issue says their behaviour changes.
3. Run `npm run lint`, `npm run typecheck` and `npm test`. All three must pass before step 4.
4. Do not commit, push or open a pull request; the workflow does that. Write the PR body to
   the file named in your task. It must contain: a link to the issue, each acceptance
   criterion with the test that proves it, the commands you ran and their result, and
   anything you were unsure about under a heading "Needs human judgement".
Keep the change to what the issue asks. No refactors of unrelated code.
```

A pull request opened this way carries its own evidence: criteria mapped to tests, commands run, open questions. That is the shape the [evidence bundle](/en/workflows/ship/evidence-bundle/) defines, and it is what lets a reviewer approve on evidence rather than on a line-by-line read.

## Fix a failing CI run without weakening the tests

The dangerous version of this job checks out the failing branch, gives Claude the API key and a shell, and pushes what it produces. Sooner or later it deletes the flaky test that was failing. It also runs the branch's `package.json` scripts, test files and build config in the same job as your secret, so anyone who can push a branch can read the key.

The version below splits the work into three jobs with different privileges:

| Job       | Holds                                       | Executes the branch's code? | Does                                            |
| --------- | ------------------------------------------- | --------------------------- | ----------------------------------------------- |
| `patch`   | API key, read-only token                    | No                          | Claude reads the logs and edits a copy of the commit |
| `verify`  | Nothing: no secrets, read-only token        | Yes                         | Applies the patch, rejects weakened tests, re-runs the gate |
| `open-pr` | Write token                                 | No                          | Commits the verified patch to a new branch and opens a PR |

**Never check out the failing commit at the workspace root before the action**

`workflow_run` runs with your repository's secrets. The action's own security notes (`docs/security.md`, read 2026-09-26) say not to check out an untrusted ref into the workspace root before the action: check out the default branch there, put the pull request's commit in a subdirectory, and pass it with `--add-dir`. The `pull_requests[0]` condition also excludes fork pull requests, and the action refuses runs whose upstream actor lacks write access.

```yaml
# .github/workflows/claude-fix-ci.yml
name: Claude fixes CI
on:
  workflow_run:
    workflows: ['CI']
    types: [completed]
permissions: {}
jobs:
  patch:
    # Holds the API key. Reads and edits the failing commit, never executes it.
    if: >-
      github.event.workflow_run.conclusion == 'failure' &&
      github.event.workflow_run.pull_requests[0] &&
      !startsWith(github.event.workflow_run.head_branch, 'claude-fix/')
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
      actions: read
      id-token: write
    steps:
      - uses: actions/checkout@v7        # trusted default branch at the workspace root
        with:
          persist-credentials: false
      - uses: actions/checkout@v7        # the failing commit, in a subdirectory
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          path: pr-head
          persist-credentials: false
      - name: Save the failing jobs' logs
        env:
          GH_TOKEN: ${{ github.token }}
          RUN_ID: ${{ github.event.workflow_run.id }}
        run: gh run view "$RUN_ID" --repo "$GITHUB_REPOSITORY" --log-failed | tail -c 60000 > "$RUNNER_TEMP/ci-failure.log"
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            CI failed on the commit checked out in pr-head/. The failing jobs' logs are in
            ${{ runner.temp }}/ci-failure.log. Edit files under pr-head/ only.
            Follow the CI-fix rules in .github/claude/fix-ci.md.
          claude_args: >-
            --max-turns 25
            --add-dir pr-head ${{ runner.temp }}
            --allowedTools "Read,Edit,Write,Glob,Grep"
      - name: Export Claude's change as a patch
        run: git -C pr-head add -A && git -C pr-head diff --cached --binary > fix.patch
      - uses: actions/upload-artifact@v7
        with:
          name: claude-fix
          path: fix.patch

  verify:
    # Executes the branch's code, so it gets no secrets and a read-only token.
    needs: patch
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          persist-credentials: false
      - uses: actions/download-artifact@v8
        with:
          name: claude-fix
          path: ${{ runner.temp }}
      - name: Apply the patch and re-run the gate outside Claude
        run: |
          [ -s "$RUNNER_TEMP/fix.patch" ] || { echo "Claude changed nothing"; exit 1; }
          git apply --index "$RUNNER_TEMP/fix.patch"
          if git diff --cached --name-only --diff-filter=D | grep -E '\.(test|spec)\.'; then
            echo "Refusing: a test file was deleted"; exit 1; fi
          if git diff --cached -U0 | grep -E '^\+.*\.(skip|only)\(|^\+.*\bxit\('; then
            echo "Refusing: a test was skipped or focused"; exit 1; fi
          if git diff --cached --name-only | grep -E '^\.github/|(^|/)package(-lock)?\.json$|(jest|vitest|playwright|karma)\.config\.'; then
            echo "Refusing: the patch edits CI, package scripts or test config"; exit 1; fi
          npm ci && npm run lint && npm run typecheck && npm test

  open-pr:
    # Can write to the repository, but runs no code from the branch.
    needs: verify
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          persist-credentials: false
      - uses: actions/download-artifact@v8
        with:
          name: claude-fix
          path: ${{ runner.temp }}
      - name: Push to a fix branch and open a PR
        env:
          GH_TOKEN: ${{ github.token }}
          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          RUN_ID: ${{ github.run_id }}
        run: |
          SAFE=$(printf '%s' "$HEAD_BRANCH" | tr -cd 'a-zA-Z0-9/_.-')
          BR="claude-fix/$SAFE-$RUN_ID"
          git apply --index "$RUNNER_TEMP/fix.patch"
          git config user.name "claude[bot]"
          git config user.email "claude[bot]@users.noreply.github.com"
          git switch -c "$BR"
          git commit -m "fix: repair CI failure from run $RUN_ID"
          git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:refs/heads/$BR"
          gh pr create --head "$BR" --base "$HEAD_BRANCH" --fill
```

Four choices carry the safety. Claude gets file tools and no shell, so the branch's code never runs beside the key. That code runs only in `verify`, which holds no secret and refuses a patch that touches `.github/`, `package.json` or a test config, so Claude cannot rewrite the gate that checks it. The `claude-fix/` prefix check stops the workflow triggering itself. And the pull request targets the developer's branch, so the author accepts or rejects the fix.

`verify` is not a sandbox, though. A `workflow_run` job runs in the default branch's context and shares its Actions cache scope, so untrusted code there can poison the cache without any secret, which is the Clinejection vector cited above. Keep `actions/cache` and `setup-node` caching out of `verify`, and never restore caches in release or publish workflows.

The price is that Claude cannot run the tests, so a failed `verify` means no pull request, not a retry; the `claude-fix` artifact keeps the patch and diagnosis. A pull request opened with the workflow's `GITHUB_TOKEN` does not trigger other workflows; `verify` already ran the gate, and a GitHub App token (`actions/create-github-app-token`) in `open-pr` makes CI run on it as well.

**Copy-paste prompt: CI fix rules (save as .github/claude/fix-ci.md)**

```text
You cannot run commands. Diagnose the root cause of the CI failure by reading the log file
and tracing it to the code under pr-head/ before changing anything.
Rules:
- Fix the code, not the test. Change a test only when it asserts behaviour that is wrong,
  and say why in pr-head/CLAUDE_FIX_NOTES.md.
- Never delete, skip, or loosen a test (no .skip, .only, lowered thresholds, widened
  snapshot tolerances, or catch-and-ignore) to make CI green.
- If the failure is flaky (timing, network, test order) rather than a bug, make the test
  deterministic: fake the clock, stub the network, or isolate the shared state.
- If the fix needs a dependency upgrade, a config change outside src/, or more than about
  50 changed lines, change no code and write only the diagnosis to CLAUDE_FIX_NOTES.md.
- Never edit package.json scripts, CI workflow files, or test configuration.
End CLAUDE_FIX_NOTES.md with three lines: root cause, fix, and the exact command that
proves it (the failing command from the log).
```

The prompt file lives on the default branch, so a pull request cannot rewrite the rules Claude follows. `CLAUDE_FIX_NOTES.md` rides along in the commit for the reviewer; delete it before merging or move it into the PR body.

## Run Claude Code headless in GitLab, Jenkins or any runner

Outside GitHub Actions, call the CLI directly. In CI, load nothing from the checkout. `--bare` skips hooks, plugin sync, auto memory, LSP and `CLAUDE.md` auto-discovery, and since v2.1.286 (both release channels on 2026-10-12) it connects only the MCP servers named on the command line, sends no system reminders and starts no background tasks. `--setting-sources ""` skips the user, project and local settings files. `--strict-mcp-config` ignores every MCP server you did not pass with `--mcp-config`. Bare mode authenticates only with `ANTHROPIC_API_KEY`, an `apiKeyHelper` passed with `--settings`, or cloud provider credentials, never with a subscription login or the keychain (`claude --help`, 2.1.283; the v2.1.286 change: Claude Code changelog, checked 2026-10-12).

```bash
# In the CI job; ANTHROPIC_API_KEY comes from the CI secret store.
CI_TMP=$(mktemp -d)
git diff "origin/$TARGET_BRANCH...HEAD" > "$CI_TMP/change.diff"

claude --bare -p "Classify the risk of the change in $CI_TMP/change.diff for release. Read the files it touches. Answer in the schema." \
  --setting-sources "" --strict-mcp-config \
  --add-dir "$CI_TMP" \
  --allowedTools "Read,Grep,Glob" \
  --permission-mode dontAsk \
  --max-turns 15 --max-budget-usd 3 \
  --output-format json \
  --json-schema '{"type":"object","properties":{"risk":{"enum":["low","medium","high"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["risk","reasons"]}' \
  > risk.json

jq -e '.is_error == false and (.structured_output.risk == "low" or .structured_output.risk == "medium")' risk.json || { jq '.structured_output.reasons // .result' risk.json; exit 1; }
```

`--permission-mode dontAsk` denies anything that would prompt instead of waiting for an answer that never comes (reads in the working directories and read-only commands still run). `--max-budget-usd` stops the run at a dollar cap and works only with `-p`. `--json-schema` puts a validated object in the `structured_output` field, so the pipeline branches on a value, not on free text. A run that errors, hits the budget or hits the turn cap has no `structured_output`, so the gate must treat a missing verdict as a failure; that is why the `jq` line checks `is_error` and allows only the two known-safe values. `--max-turns` does not appear in `claude --help` output but is documented in the [CLI reference](https://code.claude.com/docs/en/cli-reference) and works with `-p` (checked on 2.1.283). For a job that must only read, `--restricted` also removes Bash and the other code-running tools and confines the file tools to the working directories and `--add-dir`.

For GitLab there is also a GitLab-maintained [Claude Code GitLab CI/CD integration](https://code.claude.com/docs/en/gitlab-ci-cd), in beta. For programmatic control beyond a shell call, use the [Claude Agent SDK](/en/claude-code/automate/agent-sdk/). Longer multi-step scripts belong in [automation with Claude Code](/en/claude-code/automate/automation/).

## Run the action on Bedrock, Google Cloud or Foundry

With a cloud provider, the action authenticates through OIDC federation, so the repository stores no static cloud credentials. Set one input (`use_bedrock`, `use_vertex` or `use_foundry`), grant `id-token: write`, and add the provider's login step before the action.

**Amazon Bedrock**

```yaml
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-west-2   # exported as AWS_REGION for the rest of the job
      - uses: anthropics/claude-code-action@v1
        with:
          use_bedrock: 'true'
          claude_args: '--model us.anthropic.claude-opus-5-5 --max-turns 10'
```
Use the inference-profile ID your Bedrock console shows for the region group where you granted model access, for example `us.` plus the Bedrock model ID `anthropic.claude-opus-5-5`. The IAM role needs Anthropic's scoped invocation policy, which includes `bedrock:InvokeModel`.

**Google Cloud's Agent Platform**

```yaml
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - id: auth
        uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
      - uses: anthropics/claude-code-action@v1
        with:
          use_vertex: 'true'
          claude_args: '--model claude-sonnet-5 --max-turns 10'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5
```
The input is still called `use_vertex`, and region and project come from the `CLOUD_ML_REGION` and `ANTHROPIC_VERTEX_PROJECT_ID` environment variables, not from action inputs.

**Microsoft Foundry**

```yaml
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: azure/login@v3
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - uses: anthropics/claude-code-action@v1
        with:
          use_foundry: 'true'
          claude_args: '--model claude-sonnet-5 --max-turns 10'
        env:
          ANTHROPIC_FOUNDRY_RESOURCE: your-foundry-resource
```
Use a model ID that matches a Claude deployment in your Foundry resource.

On a public repository, any comment with the trigger phrase starts these jobs, and the cloud login runs before the action checks the commenter's write access. Add a first step that checks the commenter's permission with `gh api` and exits early. The full provider setup, including a custom GitHub App with only Contents, Issues and Pull requests, is in Anthropic's [cloud providers guide](https://code.claude.com/docs/en/github-actions-cloud-providers) and our [enterprise integration](/en/claude-code/team/enterprise-integration/) page.

## Keep Claude Code CI spend bounded

Each run spends GitHub Actions minutes and model tokens; a `CLAUDE_CODE_OAUTH_TOKEN` bills the subscription instead of the API. Five controls do most of the work:

- **Do not run at all** on drafts, docs-only changes or bot pull requests: `if: github.event.pull_request.draft == false` plus a `paths:` filter on the trigger.
- **Pin the model** in `claude_args`, so a change of default does not change your bill. Prices live on the [models hub](/en/ecosystem/models/).
- **Cap the work**: `--max-turns` in the action, `--max-turns` plus `--max-budget-usd` in headless runs.
- **Cap the clock** with the job's `timeout-minutes:`.
- **Cancel superseded runs** with a `concurrency:` group per pull request, as in the review workflow above.

Managed Code Review is billed separately, on token usage through usage credits, with no flat per-review price: read each repository's average cost per review in admin settings and multiply it by the pull requests the repository opens each month, and again by the pushes per pull request for repositories set to review every push; a repository you add from the admin page starts there, while one in a GitHub organization covered as a whole takes that organization's setting (Code Review costs and setup pages, checked 2026-10-16). The launch announcement of 2026-03-09 said reviews "generally average $15–25"; the current documentation publishes no such figure. Track CI spend next to interactive usage with [cost control for Claude Code](/en/claude-code/operate/cost-control/).

## How do you know the automated output is right?

The proof comes from gates Claude cannot edit:

1. **Required status checks.** Branch protection requires the same tests, typecheck and lint jobs on Claude's pull requests as on anyone else's. The auto-fix workflow re-runs them in a job Claude never touches.
2. **Protected tests.** A CODEOWNERS rule on test directories and CI config means a change to the oracle needs a named human's approval. The auto-fix workflow refuses deleted, skipped or focused tests before pushing.
3. **Evidence in the PR body.** Acceptance criteria mapped to tests, commands run, and open questions, following the [evidence bundle](/en/workflows/ship/evidence-bundle/).
4. **Structured verdicts.** Headless jobs return `--json-schema` output, and the pipeline fails on a value rather than on a human reading prose.
5. **A human approver per risk class.** Claude's review comments are input. The merge decision stays with the person CODEOWNERS names, and for high-risk paths that person reads the sampled hotspots described in [agent PR review](/en/workflows/ship/agent-pr-review/).

For a tech lead, the adoption order is: the review workflow first (read-only, low risk), then `@claude`, then issue-to-PR behind a label, then auto-fix once the `verify` job and CODEOWNERS on tests are in place.

## When Claude Code in GitHub Actions breaks

**Claude does not answer `@claude`.** Check the Claude GitHub App installation, that Actions are enabled, the secret name, that `@claude` is a whole word, and the commenter's write access. The run log names the check that rejected the event.

**CI does not run on Claude's commits.** GitHub does not trigger workflows on pushes made with the default `GITHUB_TOKEN`. Remove `github_token: ${{ secrets.GITHUB_TOKEN }}` from the action so it authenticates as the Claude GitHub App, or pass a custom GitHub App token.

**The review runs but posts nothing.** The prompt lacks `--comment`, or `claude_args` does not allow `mcp__github_inline_comment__create_inline_comment`. The `code-review` plugin also skips drafts, closed pull requests, and pull requests Claude already commented on.

**The workflow ignores your model or turn limit.** You set `model:` or `max_turns:` as action inputs. Look for the "Unexpected input" warning annotation on the run, and move the values into `claude_args`.

**A scheduled job fails the actor check.** GitHub attributes scheduled runs to the user who last changed the cron line. If that is a bot, add it to `allowed_bots`. In public repositories GitHub also disables schedules after 60 days without activity.

**The job ends with a max-turns error.** The task is too large for one run. Split it (one issue per run, one failing job per fix) before raising the limit.

**The auto-fix workflow never opens a pull request.** `verify` failed, or Claude stopped by rule and wrote only a diagnosis. Read `CLAUDE_FIX_NOTES.md` in the `claude-fix` artifact and finish by hand. If `verify` fails on most runs, keep a person on these failures rather than giving the key-holding job a shell.

**`open-pr` fails with "GitHub Actions is not permitted to create or approve pull requests".** The fix branch is pushed, but the repository or organization blocks the workflow's `GITHUB_TOKEN` from opening pull requests. Enable "Allow GitHub Actions to create and approve pull requests" under Settings → Actions → General, or use a GitHub App token in `open-pr`.

**The auto-fix workflow opens a pull request that weakens a test.** The patterns in `verify` missed it, for example a lowered coverage threshold. Close the PR, add that pattern to `verify`, and put the config file behind CODEOWNERS.

**A release or publish job runs code you never merged.** A job that executed branch code, such as `verify`, wrote to the default branch's Actions cache, and a later trusted workflow restored it. Remove caching from every job that runs untrusted code, stop restoring caches in release and publish workflows, and clear the repository's caches under Actions → Caches.

**Bedrock or Google Cloud returns 401 or 403.** The OIDC trust policy does not match this repository or branch, or the role lacks model-invocation permission, or model access is missing in one region of the inference profile.

## Where to go next with Claude Code in CI

- [Pipeline automation with AI](/en/workflows/ship/ci-cd-pipelines/): the cross-tool view of agents in the delivery pipeline
- [Pipeline configuration using Claude Code](/en/claude-code/ship/ci-cd/): generate and speed up the pipeline these jobs run in
- [Reviewing an agent's pull request without reading every line](/en/workflows/ship/agent-pr-review/): what the human reads after Claude's review
- [The evidence bundle](/en/workflows/ship/evidence-bundle/): the PR contract the issue-to-PR prompt fills in
- [Permissions and sandboxing](/en/workflows/harness/permissions-and-sandboxing/): tool allowlists and sandboxes for unattended agents
- [Hooks and automation](/en/claude-code/automate/hooks-automation/): enforce the same rules locally before code reaches CI
- [Headless agents in CI](/en/ecosystem/agent-tools/headless-agents-ci/): `claude -p`, `codex exec` and the Agent SDKs compared as pipeline building blocks
- The same jobs in the other tools: [Codex in CI/CD](/en/codex/ship/ci-cd/) and [Cursor in CI/CD](/en/cursor-ide/ship/ci-cd/)
