Back to Blog

Claude Code GitHub Actions: set it up, and decide what it can touch

Alex Kim
11 min read
Claude Code GitHub Actions: set it up, and decide what it can touch

Last updated: November 20, 2026

TL;DR

Claude Code GitHub Actions is Anthropic's anthropics/claude-code-action: a GitHub Action that runs Claude Code inside your repository's workflows. Someone mentions @claude in an issue or pull request, or a workflow hands it a prompt, and Claude reads the code, answers, and can push commits (Anthropic's GitHub Actions docs). Setting it up takes four decisions:

  • ๐Ÿ”ง How to install it: /install-github-app from Claude Code, or the app, a secret and a workflow file by hand.
  • ๐Ÿ”‘ How it signs in: a Claude API key, a subscription token, or, for an organization, workload identity federation with no stored secret.
  • ๐Ÿ’ฌ What starts a run: an @claude mention, or a prompt that runs on any GitHub event, a schedule included.
  • ๐Ÿงฑ What a run may touch: the workflow's own permissions, who may trigger it, which tools it may use, and how long it may go.

Before you start

  • Admin access to the repository. Both setup paths need it.
  • A repository on github.com. /install-github-app exits with a notice on a gitlab.com or bitbucket.org remote. GitLab has its own CI/CD integration.
  • The GitHub CLI, signed in with gh auth login, for the quick setup. That is how Claude Code reaches your repository to save the secret and push the workflow files.
  • A credential. A Claude API key from the Claude Console, or a long-lived subscription token from claude setup-token, available on Pro, Max, Ultra, Team and Enterprise plans.

If the job is one prompt that should run from your own script or server rather than from GitHub, that is headless mode. Our Claude Code automation guide compares every way to run it without you.

Step 1: Install with /install-github-app

Run claude in the repository, then /install-github-app at the prompt. The command walks you through the rest:

  1. Install the Claude GitHub App in the browser page it opens, with access to your repository, then press Enter back in Claude Code.
  2. Choose the workflows. Select "Set up GitHub Actions workflows", then keep or deselect the @claude mentions workflow and the pull request review workflow.
  3. Choose the credential. A subscription token or an API key. Claude Code saves it as a repository secret, CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.
  4. Confirm, then merge. Claude Code pushes a branch with the workflow files and opens a pull request for you to create. The workflows switch on when you merge it.

To test it, tag @claude in an issue comment. Press Esc to stop setup partway: Claude Code finishes the change it is writing and lists what already happened, such as a pushed branch or a saved secret.

If the repository already has a claude.yml, setup offers to update it instead. Pick "Skip workflow update (configure secrets only)" to keep yours.

Step 2: Or set it up by hand

Use the manual path when you don't run Claude Code locally, when the command fails, or when you want to own every line of the workflow:

  1. Install the Claude GitHub App on the repository.
  2. Add one secret: ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN from claude setup-token.
  3. Add a workflow under .github/workflows/. This is the mentions workflow from Anthropic's docs:
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 }}

With a subscription token, replace the last line with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. The if line keeps a runner from starting on comments that don't mention @claude, id-token: write is needed for the action's default GitHub App sign-in, and actions: read lets Claude read CI results on a pull request.

For an organization, install the app once at the organization level, store the secret as an organization Actions secret, and add the workflow to each repository or call one reusable workflow. Use an API key for a shared secret, since a subscription token is tied to the person who ran claude setup-token. To store no long-lived secret at all, the action can trade the workflow's GitHub OIDC token for Claude API access through a Claude Console service account (workload identity federation).

Step 3: Pick what starts a run

The action decides its mode from your workflow:

ModeWhenWhere results go
InteractiveNo prompt input. Claude waits for @claude in a comment, a review, or a new issue's title or bodyA comment on the issue or pull request, updated as it works
AutomationA prompt input, plain text or a skill such as /skill-nameThe workflow run log, unless the prompt tells Claude to post and it has a tool that can

In interactive mode, requests read like this:

@claude fix the TypeError in the user dashboard component

Automation mode runs on any GitHub event, a cron schedule included. This is Anthropic's daily report example: it runs at 09:00 UTC, reads commits and issues through two GitHub MCP tools, and needs no checkout step. Its last input, claude_args, passes the allowedTools flag (two hyphens before it, as on the command line) with "mcp__github__list_commits,mcp__github__list_issues". This blog names long flags without their hyphens, so that line is left out of the block below; add it, or the run has no tools to read with:

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"

GitHub runs scheduled workflows only from the default branch, and in a public repository it turns the schedule off after 60 days without activity.

Step 4: Decide what a run can touch

Four layers decide it. Set each one on purpose.

The app's permissions are wider than the action needs. The Claude GitHub App is shared by every Claude feature on GitHub, Code Review and web auto-fix included, and GitHub makes you accept its whole permission set. The action itself relies on three: Contents, Issues and Pull requests, each read and write. The rest of the set includes write access to Actions, Workflows and Repository hooks. If your organization accepts only what the action uses, create a custom GitHub App with those three permissions. It covers the action only; Code Review and web auto-fix still need the official app.

The workflow's permissions block narrows each run. The mentions workflow asks for write on contents, pull requests and issues because Claude pushes and comments. The daily report asks only for read. Give each workflow the least it needs.

Who can trigger a run is checked twice. On issue and pull request events, the person who triggered it must have write access to the repository; allowed_non_write_users, with your own github_token, opens it to named others. On every event, a bot is refused unless you list it in allowed_bots, which keeps bots from setting Claude off in a loop. Scheduled runs count as the user who last changed the cron line, so list that user if it is a bot.

Tools, turns and time. With a plain-text prompt, Claude has no shell or GitHub API access until you grant it, through allowedTools in claude_args or a permission rule in the settings input. A skill gets the tools its own allowed-tools frontmatter grants. Then cap the run: max-turns in claude_args, a timeout on the workflow, and GitHub's concurrency controls so runs don't stack.

claude_args takes any Claude Code CLI flag, written as you would on the command line, with two hyphens before each long flag. The common ones are max-turns, model, mcp-config, allowedTools and debug.

Never commit a key or token: keep it in GitHub Secrets and reference it, as the examples do. And review what Claude changes before you merge it.

Step 5: Know what each run costs

Each run spends two things:

  • GitHub Actions minutes, because the action runs on GitHub-hosted runners.
  • Claude usage: API tokens with an API key, or your subscription with a subscription token.

Anthropic's ways to spend less: write specific @claude requests so Claude needs fewer turns, use issue templates to give context up front, keep CLAUDE.md short since Claude reads it on every run, and cap turns, time and parallel runs as in Step 4.

To route the calls through your own cloud account instead, set use_bedrock, use_vertex or use_foundry to "true". All three sign in through OIDC, so no static cloud credentials sit in the repository. Our Claude Code on Bedrock guide covers when a team should route through AWS.

Upgrading from the beta

If a workflow still uses anthropics/claude-code-action@beta: change @beta to @v1, remove the mode input (v1 detects it), rename direct_prompt to prompt, and move options such as max_turns and model into claude_args. custom_instructions becomes the append-system-prompt flag.

Troubleshooting

SymptomLikely causeFix
Claude doesn't answer @claudeApp not installed, workflows disabled, or secret missingCheck all three in the repository settings
Claude doesn't answer one personThey lack write accessGrant it, or list them in allowed_non_write_users with your own github_token
@claude-bot or /claude does nothingThe trigger must be @claude as a whole wordUse @claude, or set trigger_phrase
CI doesn't run on Claude's commitsCommits made with the default GITHUB_TOKEN don't trigger workflowsRemove the github_token input so the action signs in as the Claude app, or pass a custom app token
A scheduled run fails the actor checkThe user who last changed the cron line is a botAdd it to allowed_bots
Authentication errorsThe key or token is invalidTest it locally with claude before debugging the workflow

Frequently asked questions

What is Claude Code GitHub Actions?

It's Anthropic's GitHub Action, anthropics/claude-code-action, that runs Claude Code inside your repository's workflows. Claude answers @claude mentions in issues and pull requests, and can run a prompt on any GitHub event, a schedule included, to analyze code, make changes and push commits. It's built on the Claude Agent SDK.

How do I set up Claude Code in GitHub Actions?

Run /install-github-app in Claude Code inside the repository. It installs the Claude GitHub App, saves your API key or subscription token as a repository secret, and opens a pull request with the workflow files; merge it to switch them on. Or install the app, add the secret and copy a workflow file yourself.

Can I use my Claude subscription with Claude Code GitHub Actions?

Yes. Run claude setup-token locally to get a long-lived OAuth token, available on Pro, Max, Ultra, Team and Enterprise plans, save it as CLAUDE_CODE_OAUTH_TOKEN, and pass it to the claude_code_oauth_token input. For a secret shared across an organization, use an API key, since the token is tied to one person's subscription.

Who can trigger Claude in GitHub Actions?

On issue and pull request events, only users with write access to the repository, unless you list others in allowed_non_write_users and pass your own github_token. Bots are refused on every event unless listed in allowed_bots, which stops trigger loops. Scheduled runs skip the write-access check but not the bot check.

What permissions does the Claude GitHub App need?

The action uses three: Contents, Issues and Pull requests, each read and write. The official app asks for a wider set because Code Review and other Claude features share it, and GitHub doesn't let you accept part of it. An organization that wants only the three can create a custom GitHub App for the action.

How much does Claude Code GitHub Actions cost?

Each run uses GitHub Actions minutes on GitHub-hosted runners, plus Claude usage: API tokens with an API key, or your subscription with an OAuth token. Keep both down with specific requests, a short CLAUDE.md, the max-turns flag in claude_args, workflow timeouts and concurrency limits.

Can Claude Code GitHub Actions run on a schedule?

Yes. Give the action a prompt input and trigger the workflow with a cron schedule. Grant the tools the prompt needs with allowedTools in claude_args or a permission rule, since a plain-text prompt starts with no shell or GitHub API access. GitHub runs schedules only from the default branch.

Give every run the same rules

A workflow run starts fresh each time, and the one thing it reads on every run is your repository's CLAUDE.md: Anthropic's docs point there for code style, review criteria and project rules. Keeping that file short and adding a rule each time a run goes wrong is the method in our guide to compound engineering for Claude Code. For guardrails that fire on every tool call, see our hooks guide.

#claude-code#GitHub Actions#Automation#ai-agents#CI
Free assessment

Stop guessing. Score your first workflow.

Score one workflow in about five minutes. Nine questions, a grade, and the specific gap holding it back - no call required.