Claude Code GitHub Actions: setup, workflows and safe limits

A Claude Code session on your laptop helps one person. The same agent inside GitHub helps everyone who opens an issue or a pull request, including the people who never open a terminal.

That is what Claude Code GitHub Actions does. You mention @claude in a comment, or a pull request comes in, and a workflow starts Claude on a GitHub runner. It reads the code, does the work and answers in the thread.

This guide covers how it works, how to set it up, which workflows to start with, what it costs and where I would draw the limits.

What is Claude Code GitHub Actions?

Claude Code GitHub Actions is an official GitHub Action from Anthropic that runs Claude Code inside a GitHub workflow, so Claude can respond to issues and pull requests without anyone running it locally. The action lives in the anthropics/claude-code-action repository and is open source.

It works in two ways. The first is interactive: someone writes @claude in an issue or pull request comment, and Claude picks up the request. The second is automated: you give the workflow a fixed prompt and a trigger, such as every new pull request, and Claude runs without anyone asking.

Under the hood it is the same Claude Code you use in the terminal. It runs in a fresh environment on a GitHub runner, it reads your CLAUDE.md, and it works through tools like reading files, editing them and running commands. The difference is that nobody is watching the session live. The output is a comment, a commit on a branch or a pull request.

How is it different from routines and claude -p?

Claude Code GitHub Actions runs on GitHub's infrastructure and is built around issues and pull requests, while routines run on Anthropic's cloud and claude -p runs wherever you call it. All three are ways to run Claude without a person typing.

If the work starts and ends in GitHub, Actions is the natural fit. Your team already lives there, the permissions already exist and the review flow is already built. For scheduled business tasks that are not about code, look at Claude Code routines instead. For scripts on your own server, see the -p flag in the Claude Code commands overview.

How do you set up Claude Code GitHub Actions?

The quickest way to set up Claude Code GitHub Actions is to run /install-github-app inside Claude Code, which installs the GitHub app, stores your API key as a secret and adds the workflow file. You need admin rights on the repository.

If you prefer to do it by hand, or the quick setup does not fit your account, these are the steps:

1. Install the Claude GitHub app on the repository. It needs read and write access to contents, issues and pull requests.
2. Add your API key as a secret. In the repository settings, add ANTHROPIC_API_KEY under Actions secrets. Never paste the key into the workflow file itself.
3. Add a workflow file. Copy the example from the anthropics/claude-code-action repository into .github/workflows/claude.yml. It listens for comments that mention @claude.
4. Write or update CLAUDE.md. This is the brief Claude reads on every run. Put your coding standards, test commands and what it must never touch in there.
5. Test it on a small issue. Open an issue, write @claude explain what this function does, and watch the run in the Actions tab.

A minimal workflow for the interactive mode looks like this:

name: Claude
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
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 10"

Check the action's README before you copy this. Input names change between versions, and the README is the source of truth. You can also run it through Amazon Bedrock or Google Vertex AI if your company keeps model access there.

Which workflows should you start with?

Start with workflows where Claude writes something a person reads before anything changes: an answer, a review comment or a draft pull request. These are the ones I would try first, in this order.

Ask the codebase is the underrated one. A product manager or support person can ask how a feature works without pulling a developer away. Nothing gets changed. It is a good way to see how well your CLAUDE.md holds up.

Pull request review is where most teams start. Give it a narrow prompt. "Review this PR" gives you a wall of generic comments. "Flag security issues, missing tests and anything that breaks the rules in CLAUDE.md" gives you comments people act on.

Small fixes need the clearest issues. Say a 10-person team has a backlog of typo fixes, small copy changes and obvious bugs. Each one becomes an issue with @claude and a precise request, and the output is a pull request someone reviews in two minutes. Vague issues produce vague pull requests.

What does a Claude Code GitHub Actions run cost?

A run costs GitHub Actions minutes for the runner plus model usage for the tokens Claude reads and writes. The action itself is free and open source.

On the GitHub side, standard GitHub-hosted runners are free for public repositories, and private repositories get an included monthly allowance. According to GitHub's billing docs, the Free plan includes 2,000 minutes a month for private repositories. A typical review run takes a few minutes, so minutes are rarely the bottleneck for a small team.

Model usage is the bigger number, and it grows with the size of the repo and the length of the task. A run that reads half the codebase to answer one question costs more than it should. Three settings keep it under control:

• Max turns. Pass --max-turns in claude_args so a confused run stops instead of looping.
• Model choice. Use a smaller, faster model for routine reviews and the stronger model for real code changes.
• Narrow triggers. Do not run a full review on every push to every branch. Run it when a pull request opens or is marked ready.

Look at the token usage of your first twenty runs before you widen anything. That gives you a real cost per run instead of a guess.

How do you keep Claude safe in your repository?

You keep Claude safe in a repository by limiting what it can touch, what it can run and what it can finish without a person. The action can write code and push branches, so treat it like a new team member with commit access.

These are the limits I would set from day one:

1. A human merges every pull request. Use branch protection on main so no change lands without an approving review. Claude proposes, people decide.
2. Scope the workflow permissions. Give the job only the permissions it needs. A review workflow does not need to push code.
3. Limit the tools. Use the allowed tools setting in claude_args so Claude can only run the commands the task requires, like your test command.
4. Keep secrets out of reach. Only pass the secrets the job needs. Claude can read anything the runner can read.
5. Decide who can trigger it. On a public repository, anyone can write a comment. Make sure only people with write access can start a run that changes code.
6. Read the runs. Every run leaves a log in the Actions tab. Read them for the first weeks, the same way you would for any agent in production.

This matters because adoption is moving faster than review habits. According to the 2025 Stack Overflow Developer Survey, 84% of developers now use AI tools or plan to start. More AI-written code means more code to review, not less.

How do you make the output better over time?

You make the output better by improving CLAUDE.md, not by rewriting prompts in every workflow file. Claude reads that file on every run, so one fix there improves every future review and pull request.

When a review comment misses the point, ask why. Usually the rule Claude should have applied was never written down. Add it to CLAUDE.md in one plain sentence. When a pull request touches files it should not, add that boundary too. How to keep that file short and structured is covered in the Claude Code memory article.

The pattern is the same as in every agent I build. Start with the lowest-risk task, read the output, write down what was missing and only then give it more room. GitHub makes that easy, because every step already leaves a comment, a commit or a log behind.