deployment

Claude Code in GitHub Actions

Headless Claude Code in CI. Auto-review PRs, run audits, generate release notes, and pay only for what runs.

10 min read·2026-05-06

GitHub Actions + Claude Code

Headless Claude in CI. No human needed.

Tag @claude in any pull request comment and it reads your CLAUDE.md, understands the codebase, writes code, and pushes commits. Or skip the mention entirely and let a GitHub Actions workflow trigger Claude automatically on every PR, running security audits, generating release notes, and fixing tests while you sleep. You pay only for what runs.

Setup time after install

Every PR

Works on any pull request

CLAUDE.md

Read automatically

Why CI Claude

What you actually get

Most CI tools lint, test, and deploy. Claude reads the diff the same way a senior engineer would, then acts on it. The gap is context.

In PR comments

Tag @claude directly in any pull request comment. Claude reads the diff, understands context, and pushes fixes.

@claude fix the failing tests
@claude review for security issues
@claude implement the feature described
@claude write tests for auth module

→ Creates commits on the PR branch

In issue comments

Tag @claude in any issue. Claude reads the issue, creates a branch, implements, and opens a PR.

@claude implement this feature
@claude investigate this bug and suggest a fix

→ Creates implementation branch automatically

Automated on every PR

No @mention needed. A GitHub Actions workflow triggers Claude on every PR open, running your custom prompt automatically.

Via .github/workflows/claude.yml
Triggers on pull_request
Runs your prompt automatically

→ Fully hands-off CI/CD integration

Getting Started

Setup in 4 steps

From zero to @claude responding in your PRs.

Install the GitHub App

Run the guided installer from your terminal. It connects Claude to your GitHub repos.

$/install-github-app

Follow the prompts to authorize and select repositories.

Add API key to repo secrets

Go to your repo Settings → Secrets and variables → Actions. Add your Anthropic key.

Secret:ANTHROPIC_API_KEY

Create the workflow file

Add a .github/workflows/claude.yml to your repo. Copy the full YAML below; it handles both automated PR reviews and on-demand @claude mentions.

First @claude mention

Open any PR, type @claude review this PR in a comment. Watch it work.

Full Workflow YAML

.github/workflows/claude.yml

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    # Only run on @claude mentions or PR opens
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' &&
       contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Claude
        uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request for:
            1. Code quality and best practices
            2. Security vulnerabilities
            3. Performance issues
            4. Missing tests
            Post your findings as a PR comment.
          allowed-tools: Read,Grep,Glob,Bash

Important Context

What Claude sees in every run

Understanding what information Claude has access to during a GitHub Action run.

Reads your CLAUDE.md automatically

Your project instructions, coding standards, architecture notes: everything in CLAUDE.md is loaded as system context before Claude starts working.

Has access to changed files in the PR

Claude sees the full diff. It knows exactly what was added, removed, or modified in the pull request.

Can run bash commands (if allowed)

When Bash is in allowed-tools, Claude can run test suites, linters, build commands, and inspect the environment.

Creates commits and pushes to the PR branch

When write tools are enabled, Claude commits directly to the PR branch. Each commit has a clear message explaining what changed.

Posts a comment with what it did

After every run, Claude posts a PR comment summarizing its findings, changes made, and any recommendations.

Ready to Use

4 workflow templates

Copy any of these into your .github/workflows/ directory. Each is a complete, working YAML file.

.github/workflows/claude.yml

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    # Only run on @claude mentions or PR opens
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' &&
       contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Claude
        uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request for:
            1. Code quality and best practices
            2. Security vulnerabilities
            3. Performance issues
            4. Missing tests
            Post your findings as a PR comment.
          allowed-tools: Read,Grep,Glob,Bash

Secrets + Auth Setup

Connecting Claude to your repo

Two secrets power every workflow. One for Anthropic, one for GitHub write access.

GitHub: Repo Secrets

ANTHROPIC_API_KEY
Your Anthropic API key. Found at console.anthropic.com. Required for every workflow.
GITHUB_TOKEN
Auto-provided by GitHub Actions. Lets Claude post PR comments and push commits. No setup needed.

GitLab: CI/CD Variables

GitLab uses CI/CD Variables instead of repo secrets. Add ANTHROPIC_API_KEY in Settings → CI/CD → Variables. Mark it as masked and protected.

.gitlab-ci.yml

stages:
  - review

claude-review:
  stage: review
  image: node:20
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      claude --print "Review this merge request for:
        1. Code quality issues
        2. Security vulnerabilities
        3. Performance concerns
        Post findings in a structured format." \
        --allowedTools Read,Grep,Glob

Safety First

Permissions and cost controls

The allowed-tools parameter controls exactly what Claude can do. Match the permission level to the task, and only pay for the tokens each job actually needs.

Use Case	Allowed Tools	Level	Why
Security review	`Read,Grep,Glob`	read-only	Auditors should never write code
API validation	`Read,Grep,Glob,Bash`	read-only	Needs bash to compare branches
Code review	`Read,Grep,Glob,Bash`	read-only	Reviews should not auto-fix
Auto-fix tests	`Read,Edit,Write,Bash,Grep,Glob`	full access	Needs to run, edit, and push
Changelog	`Read,Edit,Write,Grep,Glob`	read + edit	Writes changelog, no bash needed
Translation	`Read,Edit,Write,Grep,Glob`	read + edit	Edits locale files only

Key Principle

Give Claude the minimum tools needed for each task. A security review with write access defeats the purpose. A test-fixer without Bash cannot run tests. Match the scope to the job.

Cost controls

→Use path filters (paths:) to only trigger when relevant files change
→Set concurrency: group to cancel outdated runs on force-push
→Read-only jobs cost ~3-5× less than write jobs; use them for reviews
→Add if: conditions to gate on branch names or PR labels
→Shorter, focused prompts mean fewer output tokens per run

Gotchas

!fetch-depth: 0 is required; Claude needs full history to compare diffs
!For PR comment triggers, checkout the PR branch ref, not the default
!contents: write permission is required to push commits back
!CLAUDE.md is loaded automatically; keep project-specific rules there
!Scheduled tasks in the Desktop app survive restarts; /loop does not
!Avoid granting write access to security-review jobs; it defeats the purpose

Beyond CI

Scheduled tasks and persistent loops

For tasks that need to survive restarts and run on a calendar schedule without you present.

Scheduled tasks (Desktop app)

Persistent. Survive restarts. Run on a calendar schedule. Best for recurring CI/CD-like jobs that must happen whether you are working or not.

→Daily: run test suite and report failures
→Weekly: generate dependency update PRs
→On push: lint and format new code
→Monthly: audit unused code and dead imports

/loop (Terminal session)

Session-scoped. Dies when terminal closes. Best for "keep doing X until done" tasks during active work: watch-and-fix loops, iterative builds.

Note

Use scheduled tasks (GitHub Actions schedule: trigger or the Desktop app scheduler) when the job must run overnight or on weekends without an open terminal.

Want this running in your stack?

AY Automate builds AI automation systems for production teams.

Book a free strategy call See what we build