lockstep
5 min readNaman Jain

Claude Code GitHub Actions: setup, PR review, and automation

How to set up Claude Code GitHub Actions: /install-github-app, @claude mentions, automated PR review with a plugin skill, scheduled runs, and cost controls.

An issue sits in the backlog with a clear description and an obvious fix, waiting for someone to pick it up. With Claude Code in GitHub Actions, a teammate comments @claude implement this based on the issue description, and a pull request appears for review.

This guide covers setup, the two ways the action runs, automated review, scheduled jobs, and keeping costs down, from Anthropic's GitHub Actions documentation, checked on 16 November 2026.

What it is

Claude Code GitHub Actions is a GitHub Action that runs Claude Code inside your repository's workflows, built on the Claude Agent SDK. It is separate from Anthropic's Code Review product, which reviews pull requests automatically without a workflow file.

Setup

Quick setup. Open claude in the repository and run:

/install-github-app

It installs the Claude GitHub App, saves an authentication secret, pushes a branch with the workflow files you pick, and opens the pull request for you to merge. You need admin access to the repository and the GitHub CLI logged in with gh auth login. It works with github.com repositories only.

Manual setup. Install the Claude GitHub App, add a secret, and copy examples/claude.yml from the action's repository into .github/workflows/. The app needs read and write access to contents, issues, and pull requests.

Secrets:

SecretWhen
ANTHROPIC_API_KEYYou use a Claude API key
CLAUDE_CODE_OAUTH_TOKENYou use a Claude subscription; generate it with claude setup-token

Two modes

  • Interactive: with no prompt input, the action waits for @claude in an issue or PR comment, a review, or a new issue, and replies in a comment.
  • Automation: with a prompt input, it runs on whatever event triggers the workflow, and results go to the workflow log unless the prompt tells Claude to post.

In both, only users with write access can trigger runs by default, and bot actors are rejected unless listed in allowed_bots, which prevents loops.

Respond to @claude

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
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

actions: read lets Claude see CI results on pull requests, and the if line keeps runners from starting on comments that don't mention @claude. Then, in any issue or PR:

@claude implement this feature based on the issue description
@claude fix the TypeError in the user dashboard component

Review every pull request

The prompt input accepts a skill. This workflow installs Anthropic's code-review plugin and runs it when a pull request is opened, updated, reopened, or marked ready:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-plugins-official.git"
          plugins: "code-review@claude-plugins-official"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

--comment makes Claude post inline comments on the pull request; without it, findings only appear in the run log. Keep the claude_args line: the action only starts the inline-comment tool when --allowedTools names it. Claude skips drafts, closed pull requests, ones it judges trivial or automated, and ones it has already commented on.

To run your own skill from .claude/skills/, check out the repository first and pass /skill-name as the prompt. See Claude Code skills: 6 examples.

Run on a schedule

With a prompt, any GitHub event works, including cron. This daily job writes a summary to the run log:

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: |
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

For a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools it needs with --allowedTools or a permission rule. See Claude Code permissions.

Best practices

  • Put standards in CLAUDE.md. Claude reads it on every run and follows it when writing pull requests. Keep it short, because it's read every time. See CLAUDE.md examples.
  • Never commit keys. Store them as GitHub secrets, grant the workflow only the permissions it needs, and review Claude's changes before merging.
  • Cap the work. Each run uses Actions minutes and tokens. Write specific requests, set --max-turns in claude_args, add workflow timeouts, and use concurrency controls.

What CI can't see

A workflow reviews the diff in front of it against whatever the repository says. A decision made in a planning meeting or a Slack thread isn't in the repository, so an automated review can approve a change that contradicts it.

Where Lockstep fits

Lockstep adds that context to review. It captures decisions from PRDs, Slack, and pull requests, makes each binding when its owner approves it, and includes a GitHub Action that checks pull requests against the approved record. Its newer advisory checks flag code that may conflict with a decision and report results as completed, partial, skipped, or unavailable, never a silent pass. Claude Code sessions are also briefed on the decisions that apply at session start.

See how it works.

Sources checked 16 November 2026

For running Claude Code in scripts, see Claude Code best practices. For claude -p outside GitHub, see Claude Code headless mode. For plugins used in workflows, see Claude Code plugins and marketplaces. For running tasks in Anthropic's cloud instead of CI, see Claude Code cloud sessions. For building your own agent on Claude Code, see Claude Agent SDK vs Claude Code. For review practices that work with AI, see AI code review best practices.

Frequently asked questions

How do I set up Claude Code GitHub Actions?
Run /install-github-app in Claude Code inside the repository. It installs the Claude GitHub App, saves an authentication secret, and opens a pull request with the workflow files. You need admin access to the repository and the GitHub CLI authenticated. You can also install the app, add the secret, and copy the workflow file manually.
What can @claude do in a pull request?
Mention @claude in an issue or PR comment with a request, such as implementing a feature from the issue description or fixing an error. Claude replies in a comment on the same issue or PR, updates it as it works, and can push commits or open a pull request.
Can Claude Code review every pull request automatically?
Yes. Give the workflow a prompt that runs the code-review plugin's skill on pull request events, with --comment so Claude posts inline comments. Claude skips drafts, closed pull requests, trivial or automated ones, and pull requests it has already commented on.
How do I authenticate Claude Code GitHub Actions?
With a repository secret: ANTHROPIC_API_KEY for a Claude API key, or CLAUDE_CODE_OAUTH_TOKEN for a token tied to a Claude subscription, generated with claude setup-token. Never commit keys to the repository.
How do I control the cost of Claude Code in GitHub Actions?
Each run uses GitHub Actions minutes and model tokens. Write specific @claude requests, keep CLAUDE.md concise because it is read on every run, set --max-turns in claude_args, add workflow timeouts, and use GitHub's concurrency controls.

Keep reading