Claude Code GitHub Actions: @claude, Reviews, and Schedules

The action decides how to run from the workflow itself:

• Interactive mode, when the workflow has no prompt input. Claude waits for the trigger phrase (@claude by default) in an issue or PR comment, a PR review, or the title or body of a newly opened issue. It replies in a comment on that issue or PR and updates it as it works.
• Automation mode, when the workflow sets prompt. Claude runs on whatever event triggered the workflow, without waiting for a mention. Results go to the workflow run log by default; Claude posts to the PR or issue only if the prompt asks it to and it has a tool that can post.

The prompt can be plain text or a skill invocation such as /release-notes. For a skill in your repository's .claude/skills/, check out the repository first so the skill files exist on the runner. For a skill from a plugin, install the plugin with the plugin_marketplaces and plugins inputs and call it as /plugin-name:skill-name.

Claude follows your repository's CLAUDE.md in both modes, so put review criteria, code style, and project rules there rather than repeating them in every workflow.

You need admin access to the repository either way.

Quick setup. Install the GitHub CLI and run gh auth login, then open claude in the repository and run /install-github-app. Claude Code installs the Claude GitHub App, saves a repository secret (ANTHROPIC_API_KEY for an API key, or CLAUDE_CODE_OAUTH_TOKEN for a token tied to your Claude subscription), pushes a branch with the workflow files you pick, and opens a pull request. Merge it and @claude works. This path is for github.com repositories with the Claude API or a Claude subscription.

Manual setup.

1. Install the Claude GitHub App on the repository. 2. Add a secret: ANTHROPIC_API_KEY from the Claude Console, or CLAUDE_CODE_OAUTH_TOKEN generated locally with claude setup-token (Pro, Max, Team, and Enterprise). 3. Copy examples/claude.yml from the action's repository into .github/workflows/.

For an organisation, install the app once at organisation level, store the secret as an organisation Actions secret, and add the workflow to each repository or define it once as a reusable workflow. Use a Console API key for a shared secret, not an OAuth token, which is tied to whoever ran claude setup-token. To avoid long-lived secrets entirely, the action supports workload identity federation: it exchanges the workflow's GitHub OIDC token for Claude API access through a Console service account (anthropic_federation_rule_id and anthropic_organization_id inputs, plus id-token: write).

This is the interactive-mode workflow from the docs:

1name: Claude Code2on:3  issue_comment:4    types: [created]5  pull_request_review_comment:6    types: [created]7jobs:8  claude:9    if: contains(github.event.comment.body, '@claude')10    runs-on: ubuntu-latest11    permissions:12      contents: write13      pull-requests: write14      issues: write15      id-token: write16      actions: read17    steps:18      - uses: actions/checkout@v619        with:20          fetch-depth: 121      - uses: anthropics/claude-code-action@v122        with:23          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

The lines that matter: if: stops a runner from starting on comments without @claude (the action checks again itself); id-token: write is needed for the action's default GitHub App authentication; actions: read lets Claude read CI results on the PR; and actions/checkout gives Claude a copy of the repository to work in.

Then comment with a specific request, such as @claude fix the TypeError in the user dashboard component. The mention must be the whole word @claude, not /claude or @claude-bot.

This automation-mode workflow installs Anthropic's code-review plugin and runs its skill whenever a pull request is opened, updated, reopened, or marked ready:

1name: Code Review2on:3  pull_request:4    types: [opened, synchronize, ready_for_review, reopened]5jobs:6  review:7    runs-on: ubuntu-latest8    permissions:9      contents: read10      pull-requests: read11      issues: read12      id-token: write13    steps:14      - uses: actions/checkout@v615        with:16          fetch-depth: 117      - uses: anthropics/claude-code-action@v118        with:19          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}20          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"21          plugins: "code-review@claude-code-plugins"22          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"23          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Two details decide where the review goes. --comment makes Claude post inline comments on each issue it finds (or one summary comment if none); without it the findings stay in the run log. And the claude_args line must stay, even though the skill names the same tool, because the action only starts the MCP server that posts inline comments when --allowedTools names it.

The skill skips draft and closed pull requests, ones it judges trivial or automated, and ones Claude has already commented on.

With a prompt, the action runs on any event, including schedule. This one writes a summary to the run log at 09:00 UTC daily, reading commits and issues through two GitHub MCP tools, so it needs no checkout:

1name: Daily Report2on:3  schedule:4    - cron: "0 9 * * *"5jobs:6  report:7    runs-on: ubuntu-latest8    permissions:9      contents: read10      issues: read11      id-token: write12    steps:13      - uses: anthropics/claude-code-action@v114        with:15          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}16          prompt: "Generate a summary of yesterday's commits and open issues"17          claude_args: |18            --model claude-opus-5-519            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

claude_args accepts any Claude Code CLI argument. The common ones are --max-turns to cap iterations, --model, --allowedTools, --mcp-config for extra MCP servers, and --debug.

Before Claude starts, the action checks the triggering actor, and the run fails if either check rejects it:

• Write access: on issue and pull request events, the user must have write access to the repository. allowed_non_write_users (with your own github_token) admits specific others.
• Human actor: on every event, bot actors are rejected unless listed in allowed_bots, which prevents bots triggering Claude in a loop.

So anyone with write access can direct Claude, and Claude acts with the permissions of the workflow and the GitHub App. That is the real boundary to think about. The Claude GitHub App is shared by every Claude GitHub feature, so installing it grants a broad set, including read and write on Actions, Checks, Contents, Issues, Pull requests, Repository hooks, and Workflows. GitHub does not allow accepting only part of it. If policy requires less, create a custom GitHub App with only Contents, Issues, and Pull requests, following the action's setup guide; it covers the action only, not Code Review or cloud auto-fix.

Grant each workflow only the permissions: it needs, never commit keys (use secrets), and review Claude's changes before merging.

Every run uses GitHub Actions minutes on GitHub-hosted runners and model tokens, billed to the API key's owner (or counted against your Claude plan with an OAuth token). Token use grows with prompt length, task complexity, and codebase size. To keep both bounded: write specific requests, provide context in issue templates, keep CLAUDE.md short, set --max-turns, set timeout-minutes on jobs, and use concurrency groups so a burst of comments does not start ten parallel runs.

The failures people hit most:

• Claude does not respond to @claude: check that the app is installed, workflows are enabled, the secret exists, the mention is the exact word @claude, and the commenter has write access.
• CI does not run on Claude's commits: GitHub does not trigger workflows on commits pushed with the default GITHUB_TOKEN. If you pass github_token: ${{ secrets.GITHUB_TOKEN }}, remove it so the action authenticates as the Claude GitHub App, or pass a custom app token.
• Authentication errors: test the key or token locally with claude before debugging the workflow.

Use a test repository where you are an admin.

1. Run /install-github-app from claude in the repository, pick the mention and review workflows, and merge the pull request it opens. 2. Open an issue describing a small bug and comment @claude fix this and open a PR. Watch the comment update and review the PR it opens. 3. Push a branch with a deliberate bug and open a PR. Confirm the review workflow posts an inline comment on it. 4. Add the daily-report workflow with on: workflow_dispatch alongside the schedule, run it manually, and read the report in the run log. 5. Add timeout-minutes: 15 to each job and --max-turns 10 to each claude_args.

Pass criterion: Claude replied to the mention and opened a PR, the review posted an inline comment, the report ran on demand, and every job now has a timeout and a turn cap.