Claude Code GitHub Actions: setup, workflows and @claude mentions

Claude Code GitHub Actions is Anthropic's official GitHub Action, anthropics/claude-code-action, which runs Claude Code inside your repository's workflows. You set it up with /install-github-app or by copying a workflow file, store a Claude credential as a secret, and then mention @claude in an issue or pull request to have Claude answer, change code and push commits.

It can also run with a fixed prompt on any GitHub event, such as every new pull request or a daily schedule. This guide covers setup, the workflow YAML, how @claude mentions work, secrets, costs and the problems people hit most often. Everything here comes from the Claude Code GitHub Actions docs, read on 24 October 2026.

What is Claude Code GitHub Actions?

Anthropic's docs describe it as "a GitHub Action that runs Claude Code inside your repository's workflows." It is built on the Claude Agent SDK and runs on your own GitHub Actions runners, so Claude gets a checkout of your repo, reads your CLAUDE.md, and works with the tools you allow.

Several products share the Claude Code name, so it helps to separate them:

If all you want is automatic pull request reviews, see the Claude Code review guide, which compares those options. If you want Claude to act on requests in issues and PRs, or to run your own automation, the action is the right tool.

How do you set up Claude Code GitHub Actions?

There are two paths. Both need admin access to the repository.

Quick setup with /install-github-app

1. Install the GitHub CLI and run gh auth login.
2. Open claude in the repository you want to connect.
3. Run /install-github-app and follow the prompts.

Claude Code installs the Claude GitHub App, then sets up a credential. If it already has an API key it reuses it; otherwise you choose between a long-lived token tied to your Claude subscription and pasting an API key. It saves the credential as a repository secret, pushes a branch with the workflow files you picked, and opens GitHub with a pull request ready to create. Merge that pull request and @claude works in the repo.

The command works only with github.com repositories. On gitlab.com or bitbucket.org remotes it prints a notice and exits. Quick setup supports the Claude API and Claude subscriptions; Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry use a separate cloud provider setup.

Manual setup

Use this when you don't run Claude Code locally, when the command fails, or when you want full control of the files.

1. Install the Claude GitHub App on the repository. The action relies on its Contents, Issues and Pull requests permissions (read and write). The app also requests other permissions that features like Code Review use, and GitHub doesn't let you accept only a subset.
2. Add one secret: ANTHROPIC_API_KEY (an API key from the Claude Console) or CLAUDE_CODE_OAUTH_TOKEN (generate it with claude setup-token).
3. Copy examples/claude.yml into .github/workflows/. The docs say it "is a working workflow, not just an example."

Then test it by commenting @claude on an issue or pull request.

What does the workflow YAML look like?

This is the workflow from the docs that answers @claude mentions in comments:

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

The lines that matter:

• id-token: write is required for the action's default GitHub App authentication.
• actions: read lets Claude read CI results on pull requests.
• actions/checkout gives Claude a local copy of the repo to work in.
• The if line stops runners from starting on comments that don't mention @claude.

If you authenticate with a subscription token, replace the anthropic_api_key line with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

The most used inputs

The full list is in the action's configuration reference.

How do @claude mentions work?

The action picks a mode from your workflow. With no prompt input it runs in interactive mode: Claude waits for @claude in an issue or PR comment, a PR review, or the title or body of a new issue, then replies in a comment and updates it as it works. Examples from the docs:

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

With a prompt input it runs in automation mode: Claude runs on the event without waiting for a mention, and results go to the workflow run log by default. You can point prompt at a skill, such as /skill-name for a skill in .claude/skills/ (check out the repo first so the files exist on the runner), or /plugin-name:skill-name for a plugin skill.

Two checks run before Claude starts. On issue and PR events, the person who triggered the run must have write access (to allow specific users without it, set allowed_non_write_users and pass your own github_token). On every event, bot actors are rejected unless listed in allowed_bots, which prevents loops.

Scheduled runs

A prompt plus a cron trigger gives you a recurring job. This docs example writes a daily 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: |
            --model claude-opus-5-5
            --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 tools with --allowedTools or a permissions.allow rule. GitHub runs schedules only from the default branch.

How should you handle secrets and permissions?

The docs are blunt: "Never commit API keys or OAuth tokens directly to your repository." Store them as GitHub Actions secrets and reference them as ${{ secrets.NAME }}.

A few practical rules from the docs:

• Grant the workflow only the permissions it needs, and review Claude's changes before merging.
• For an organization, install the app once at the org level and store the credential as an organization secret. Use a Console API key there, not an OAuth token, because an OAuth token is tied to the subscription of whoever ran claude setup-token.
• To avoid a long-lived secret entirely, use workload identity federation, which exchanges the workflow's GitHub OIDC token for Claude API access through a Claude Console service account.
• If your organization only allows the three permissions the action uses, create a custom GitHub App with Contents, Issues and Pull requests. A custom app covers only the action; Code Review still needs the official app.

Put your project rules in a CLAUDE.md file at the repo root. Claude follows it when it opens PRs and answers requests.

How much does it cost to run?

Each run uses two things, per the docs:

• GitHub Actions minutes on GitHub-hosted runners, billed under GitHub's Actions billing.
• Claude usage: API tokens with an API key (rates on Claude's API pricing page), or your Claude subscription if you use an OAuth token.

Ways to keep both down:

• Write specific @claude requests so Claude needs fewer turns.
• Use issue templates so context is there up front.
• Keep CLAUDE.md concise, since Claude reads it on every run.
• Set --max-turns in claude_args, add a workflow-level timeout, and use GitHub's concurrency controls.

What are the common problems and fixes?

Claude doesn't respond to @claude. Check the app is installed, workflows are enabled and the secret exists. The comment must contain @claude as a whole word, and the commenter needs write access.

CI doesn't run on Claude's commits. GitHub doesn't trigger workflows on commits made with the default GITHUB_TOKEN. Remove github_token: ${{ secrets.GITHUB_TOKEN }} so the action uses the Claude GitHub App, or pass a custom app token.

Authentication errors. Test the key or token locally with claude before debugging the workflow.

Old workflows on @beta. Change @beta to @v1, remove mode, rename direct_prompt to prompt, and move options like max_turns and model into claude_args. The migration guide has the full mapping.

Can the action run your own skills?

Yes, and this is where shared skills pay off. Any skill committed under .claude/skills/ can run as the prompt, and plugin skills install through the plugins input. See the Claude Code skills guide for the format and the plugins guide for packaging.

If you keep your skills in Kipt, they already live as SKILL.md folders in a private GitHub repo you own. You can install them locally with npx skills add https://github.com/<you>/<repo>.git --all -g, then commit the ones a project's workflows need into that project's .claude/skills/ folder.