Claude Code GitHub Actions

The useful change is who has to stay available. In a local-only workflow, a developer has 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.

Setup and inputs verified against the action README and Anthropic's documentation on October 30, 2026, with claude-code-action v1.0.265 released that day. 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 enabling a review on every change. Action usage.

Keep the task in prompt and CLI settings in claude_args: --model, --max-turns, and tool permissions belong there. Older workflows should replace direct_prompt with prompt, remove mode, and move standalone model and max_turns inputs into claude_args. Automation normally leaves its result in the run log; to get a PR comment, request one and grant the posting tool, as in the review example below. Input migration, automation behavior.

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 the API-key or subscription-token secret from the table below. Federation and cloud routes require their linked setup instead.
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.

The cloud routes use a separate setup, including provider model access and a cloud authentication step before the action. OIDC, OpenID Connect, lets the cloud exchange GitHub's job identity for short-lived credentials. For Bedrock, configure the AWS role and region; for Vertex, configure the Google service account, ANTHROPIC_VERTEX_PROJECT_ID, and CLOUD_ML_REGION. Use the provider's model ID in claude_args when selecting a model. Anthropic now calls the Google service Google Cloud's Agent Platform, while the action input remains use_vertex. Cloud provider setup, authentication inputs.

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.

A subscription token belongs to the person who generated it; Anthropic recommends an API key for secrets shared across repositories. Organization authentication.

Billing follows the inference route: API key or Anthropic federation uses your Anthropic API account; Bedrock, Vertex, or Foundry uses the corresponding cloud account; direct-action OAuth uses your Claude subscription; Agentic Workflows can also route inference through Copilot, with GitHub Actions compute accounted for separately. Anthropic billing, Copilot inference, Actions billing.

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 credential or federated identity 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 authentication, 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-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: >-
  --max-turns 5
  --allowedTools "mcp__github_inline_comment__create_inline_comment"

Use those inputs inside the official pull_request workflow, with types: [opened, synchronize, ready_for_review, reopened]. 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. Keep the inline-comment tool in claude_args even though the skill also names it: the action uses that flag to start its commenting server. 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. Review workflow.

Direct Action or GitHub Agentic Workflows With Claude?

Use claude-code-action directly for a focused review step or an @claude assistant inside YAML your team already maintains. Choose GitHub Agentic Workflows with Claude when recurring issue triage needs explicit, validated write operations and a consistent workflow framework. Both run in GitHub Actions; the choice is how you define and control the work.

Since October 28, 2026, GitHub Agentic Workflows is generally available: Markdown instructions compile into standard Actions YAML and reuse your runner groups and policies. Its engine choices include Copilot, Claude, Codex, and Antigravity, though the Antigravity adapter is still documented as experimental.

Keep the direct action when the useful unit is a Claude-specific step: the review plugin above, a maintainer-requested fix, or an existing workflow with carefully chosen tools. You configure prompt, claude_args, triggers, and permissions directly. Adding a compiler and generated workflow file is extra maintenance if that already meets the need. Anthropic's workflow configuration.

Choose Agentic Workflows when a backlog job should read issues, propose labels, and post a triage comment through declared operations. Its agent has read-only GitHub permissions by default; safe-outputs defines the requested writes, which separate permission-controlled jobs validate and apply. The sandbox, network firewall, and threat-detection job add controls around that process. Start triage with staged outputs so you can inspect proposed changes before enabling writes. Safe outputs, built-in safeguards.

For the Claude engine, install the extension with gh extension install github/gh-aw, set engine: claude in the Markdown workflow, and configure ANTHROPIC_API_KEY or Anthropic workload identity federation. Compile with gh aw compile, then commit both the Markdown and generated .lock.yml under .github/workflows/. Subscription OAuth tokens supported by the direct action are not supported by this engine; GitHub also documents a Copilot-hosted inference option. Do not copy the direct action's authentication block into it unchanged. Quickstart, Claude engine setup.

For an engineering lead, keep a working PR review action and pilot Agentic Workflows on issue triage first. Migrate the review only when its output controls justify maintaining the compiled workflow.

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, workload identity federation exchanges GitHub's job identity for short-lived API access. Configure anthropic_federation_rule_id and anthropic_organization_id, retain id-token: write, and omit anthropic_api_key and claude_code_oauth_token so a static credential does not override federation. 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.

A queued request is not a completed job. Check whether the runner started, whether concurrency replaced an older pending request, and whether the job reached its timeout before debugging Claude's response. The starter profile deliberately bounds elapsed time and simultaneous work. Concurrency behavior.

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. 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. 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.

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 cloud scheduled task, formerly called a 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. Scheduled tasks also support GitHub and API triggers, so scheduling alone does not force you into Actions; they remain in research preview. Cloud sessions, scheduled tasks.

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.