Claude Code GitHub Actions

The useful change is who has to stay available. A developer previously had to open the repository, launch Claude, carry the result back into GitHub, and keep the local session running. With an Action, a maintainer leaves a scoped request and returns to a comment or proposed change. Work can start outside that developer's working hours; the time needed to check the result remains.

This guide uses Anthropic's current documentation, checked October 15, 2026. The workflow below is a deliberately constrained starting configuration, not a claim that every issue can be solved unattended.

Give the Repository an On-Call Assistant

Think of the GitHub App as the access badge, the workflow as the job sheet, and the runner as a temporary workstation. A workflow is the configuration file that tells GitHub when to start; a runner is the machine that executes it.

The action can respond to mentions in issues and pull requests. Supplying a prompt instead makes it an automated job. For a small team, explicit requests are the easiest way to find useful tasks before paying for a review on every change. Action usage.

Install It Once, Then Merge the Workflow

Use the guided installation with repository admin access. Authenticate the installed GitHub CLI with gh auth login, open claude inside the repository, and run /install-github-app. Choose workflows and API-key or subscription authentication, then create and merge the prepared workflow PR. Installation happens locally; subsequent jobs run on GitHub. Official quick setup.

The manual route reaches the same destination:

1. Install the Claude GitHub App on the selected repository.
2. Open repository Settings → Secrets and variables → Actions, then add one authentication secret from the table below.
3. Copy Anthropic's working example into .github/workflows/claude.yml, select its matching authentication input, and merge the file.
4. Leave a comment containing @claude and a specific request.

Those are the official manual setup steps, with the credential choice made explicit. Action setup guide.

For the subscription route, run claude setup-token locally and store its output as the secret. Anthropic documents this for Pro, Max, Team, and Enterprise plans. The generated token lasts one year, so give renewal an owner. Token authentication.

Billing follows the credential: API-key runs use API billing; OAuth-token runs use your Claude subscription instead, while GitHub Actions runner usage is accounted for separately. A subscription token belongs to the person who generated it; Anthropic recommends an API key for secrets shared across repositories. Authentication and costs.

You do not need a personal GitHub access token for the default app setup. GitHub access and Claude authentication are separate: the app supplies the former, your selected secret supplies the latter. Authentication inputs.

Start With a Small, Mention-Triggered Workflow

Use this profile for trusted team repositories and small file changes. It can read and edit files and commit through GitHub's API. Claude gets no shell tool, so it cannot run your test commands in this profile. Keep your normal CI, the automated checks that run on proposed changes, responsible for executing tests.

Save this as .github/workflows/claude.yml. The action references, actions/checkout@v6 and anthropics/claude-code-action@v1, appear in Anthropic's current example. The five-turn cap and fifteen-minute timeout are starter choices, not Anthropic defaults. Official workflow.

name: Claude on request
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: 15
    concurrency:
      group: claude-small-team
      cancel-in-progress: false
    permissions:
      contents: write
      issues: write
      pull-requests: write
      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 }}
          use_commit_signing: true
          claude_args: |
            --max-turns 5
            --tools "Read,Glob,Grep,Edit,Write"
            --disallowedTools "Bash,WebFetch,WebSearch"

For subscription billing, replace the anthropic_api_key line with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. Pass one route. Keep id-token: write, which the default GitHub App authentication requires. Official workflow and authentication, input reference.

The controls do different jobs:

• --tools selects the built-in tools Claude can use. Read, Glob, and Grep inspect files; Edit and Write change them. It does not restrict MCP tools, the separately connected tools the action uses to talk to GitHub.
• --allowedTools grants permission to use named tools without asking. It is not a complete tool whitelist. The explicit --disallowedTools line denies shell and web tools here.
• --max-turns limits the agent's working iterations. It does not cap tokens or dollars, and reaching the cap can end the run with an error and unfinished work. CLI reference.

use_commit_signing: true routes commits through the GitHub API. This is what lets this profile save changes without giving Claude shell-based git commands. It needs no additional signing secret. The action's GitHub tools remain available, so this profile is write-capable. Commit signing, action implementation.

The fixed concurrency group permits one running job from this workflow per repository. With the default queue behavior, a new pending request can replace an older pending request; this is not a durable task queue. The timeout bounds elapsed job time, including setup. GitHub concurrency, workflow syntax.

Try @claude review this PR for missing permission checks; report findings without changing files. For an issue, try @claude fix the null handling described above, change only the parser and its regression test, and state which checks were not run.

By default, the triggering person needs repository write access and bots are blocked. For an issue fix, expect a branch and a link for a human to create the PR. Keep that distinction in your team's instructions. Action security.

Add Automatic Reviews After the Trial

Select the review workflow during /install-github-app setup for automatic PR reviews. Its code-review plugin uses --comment and the commenting-tool allowance below to publish findings. Official review example.

In that separate review workflow, the action's inputs include:

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: >-
  --max-turns 5
  --allowedTools "mcp__github_inline_comment__create_inline_comment"

Use those inputs inside the official pull_request workflow, not the mention workflow above. Keep its checkout, authentication, and job permissions, add a job timeout, and skip fork PRs with if: github.event.pull_request.head.repo.full_name == github.repository. Treat the turn cap as a pilot setting: a review that runs out of turns is incomplete. The documented review skill also skips some PRs, including drafts.

Keep Installation Scope and Tool Scope Separate

Install on selected repositories first. The official Claude App shares permissions across several Claude features, and GitHub does not let you accept only part of that permission set. A small YAML permissions block does not shrink the app installation. App permission model.

If that installation is too broad, follow the custom-app route with Contents, Issues, and Pull requests access. It adds APP_ID and APP_PRIVATE_KEY secrets, plus a step that creates an app token and passes it as github_token. For teams ready to remove static Claude API keys, the setup guide also documents workload identity federation, which exchanges GitHub's job identity for short-lived API access. Custom app and federation setup.

Add a concise CLAUDE.md with review priorities, permitted change areas, and what evidence a fix must include. Instructions guide the work; repository permissions and tool restrictions enforce access. Review any configured hooks, commands run automatically at lifecycle events, or extra tool servers before enabling unattended runs. Project instructions. Our Claude Code review guide covers the broader review decision, and the slash commands guide explains commands used during setup.

Six Jobs Worth Giving It, in Order

Start where the request is easy to describe and the output is easy to check. These are proposed workflows, not measured savings or guarantees.

The starter profile cannot install dependencies or run a test suite. If the job needs those, add a separately reviewed execution profile for trusted code, with specific command permissions and its own limits. A permitted test command still executes repository code; its friendly name does not make that code safe.

Fix These Failures Before Adding More Triggers

Forked PRs can lose access to secrets. GitHub normally withholds secrets from fork-triggered pull_request and pull_request_review_comment runs. An empty Claude credential in those jobs is a trust-boundary behavior. Do not switch to pull_request_target and execute the fork's code just to obtain secrets. A maintainer-triggered issue_comment job can also have secrets, so a trusted commenter does not make the PR's files trusted. GitHub's fork security guidance.

Tool limits do not neutralize project startup code. The action restores selected Claude configuration from the base branch, but scripts and other project files can still come from the PR. Audit hooks and tool-server configuration as well as Claude's permitted tools. Action trust boundaries.

Runner time remains a separate constraint. Standard GitHub-hosted runners are free for public repositories. Private repositories have plan allowances and paid overages; exhausted allowances without a payment method can stop jobs. Check the Actions usage page alongside Claude usage. GitHub Actions billing.

Rate limits can interrupt a valid workflow. API limits cover requests and input/output tokens, the pieces of text the model processes, per minute. For a 429 with retry-after, wait before retrying and reduce simultaneous jobs. A tier spend-cap 429 without that header needs a billing or limit resolution, not repeated reruns. Subscription authentication remains subject to the plan's usage limits. API rate limits, Claude usage limits.

A silent bot and a missing CI run are different failures. For silence, check the workflow exists on the default branch, Actions is enabled, the secret matches its input, and the commenter has write access. Use the complete mention @claude. For downstream CI, check whether somebody replaced app authentication with github_token: ${{ secrets.GITHUB_TOKEN }}: GitHub suppresses many events created by that token, and some PR workflows require approval. GitHub token behavior.

Two Things Worth Building Around This

The strongest opportunity is a managed review setup for small teams. The buyer is an engineering lead who wants useful findings, clear ownership, and predictable operating limits. DataForSEO's US English estimates retrieved October 15, 2026 put “ai code review” at 1,300 monthly searches. That is evidence of interest, not a count of customers. A sellable first version could configure one repository, encode its review priorities, evaluate findings against historical PRs, and provide an ongoing usage and failure report. The catch is false-positive fatigue: the durable work is maintaining review quality as the codebase changes. A generic prompt wrapper offers little reason to stay.

An agency could buy a reusable review-policy package for client repositories. DataForSEO estimates 590 monthly searches for “ai code review tools” and 140 for “github ai code review” in the same market. The smallest product could combine a reusable workflow, client-specific instruction templates, credential ownership records, and checks for missing limits. It could help an agency maintain consistent setups across handovers. The catch is that each client's permissions and test environment differ; a template needs maintenance and evaluation to remain useful. These query audiences overlap, so do not add their volumes together as a market size.

Choose the Home That Matches the Job

Choose GitHub Actions when the work belongs to a repository event and your team wants the configuration, permissions, and logs managed with its CI. Choose a cloud session for a one-off task you want to start and steer from a browser while your laptop is closed. Choose a scheduled routine for a saved recurring task, such as a nightly backlog check, when you prefer Claude's hosted scheduling and configuration to maintaining workflow YAML. Routines also support GitHub and API triggers, so scheduling alone does not force you into Actions; routines remain in research preview. Cloud sessions, routines.

On Monday, have the repository admin install the app and merge the constrained workflow. Give it a known bug and a focused review request, then compare the output with the team's own judgment. Expand the triggers only after the results justify the attention and usage.

If you want this workflow built and maintained for your team, get help with AI automation.