Claude Code GitHub Actions: set up @claude, workflows, secrets and limits

Before you start

You need a github.com repository where you have admin access, Claude Code on your machine and the GitHub CLI signed in with gh auth login. A GitLab or Bitbucket remote does not work with the quick setup. Several Anthropic products share the Claude Code name, and this lesson covers only the claude-code-action workflow integration from Anthropic's GitHub Actions page.

The action is built on the Agent SDK, and claude_args accepts the same flags as claude -p in the headless lesson. Security details come from the repository's own docs. Everything was read on 4 November 2026, and the GitHub Actions page again on 5 November.

The action ships often, so pin @v1 and let it move. These figures show how widely it is used and how fresh it was when this lesson was checked.

Install it and send your first @claude

Quick setup installs the Claude GitHub App and stores your credential as a repository secret. It then proposes the workflow in a pull request. That workflow is the one below, which the manual path copies from the repository's examples folder.

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

1. Open claude in the repository and run /install-github-app. Claude Code installs the app first. If it already has an API key it reuses it, otherwise you choose between a long-lived token from your Claude subscription and a pasted API key.
2. Claude Code saves the credential as ANTHROPIC_API_KEY for a key or CLAUDE_CODE_OAUTH_TOKEN for a subscription token. It then pushes a branch with the workflow files you select, already pointed at that secret, and opens GitHub with a pull request ready to create.
3. Create and merge the pull request. Then comment on an issue with a request, such as @claude how should I implement user authentication for this endpoint?. Claude answers in a comment on the same issue and updates it as it works.
4. Without Claude Code locally, or when the command fails, set it up by hand. Install the Claude GitHub App, add the secret, and copy the workflow into .github/workflows/. For a subscription token run claude setup-token locally and change the anthropic_api_key line to claude_code_oauth_token.

What each part of the workflow is for

Anthropic's page names the lines that are not boilerplate. Most trouble comes from one of them going missing.

• id-token: write is required for the default GitHub App authentication. Without it you get OIDC errors, and the permission stays even when you pass your own token for workload identity federation.
• actions: read lets Claude read CI results on pull requests. The FAQ adds additional_permissions: actions: read on the action step as well.
• actions/checkout gives Claude a local copy of the repository. Claude clones shallowly, 20 commits for a pull request and 1 for a new branch, so set the checkout depth yourself when you need full history.
• The if keeps runners from starting on comments with no @claude. The action also checks the trigger phrase itself before it responds.
• Contents, issues and pull requests get write access because they are the three app permissions the action relies on: Claude edits files, responds to issues and pushes changes.

Two modes and who can start a run

The action detects its mode from the workflow, and there is no mode input. With no prompt it runs interactively and waits for the trigger phrase, @claude by default, in a comment, a review or the title or body of a new issue. With a prompt it runs in automation mode on whatever event your on: block names, and the result goes to the run log unless the prompt tells Claude to post it.

A plain-text prompt gets no shell or GitHub API access until you grant tools with --allowedTools in claude_args, or with a permissions.allow rule in the settings input. A skill brings the tools its allowed-tools frontmatter names. This code review workflow from the page grants one inline comment tool and keeps the token read-only.

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      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 }}
          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: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

What Claude can touch, and the checkout trap

The action runs on your runner with a short-lived token from the Claude GitHub App. The token is scoped to the one repository the run works in. Installing the app grants its whole permission set, and GitHub does not let you accept a subset. If your organization wants only contents, issues and pull requests, the docs describe a custom GitHub App with just those three. The repository's security page lists fewer app permissions than the docs table does, so read the install screen.

By default Claude does not open the pull request. Per the security page it pushes its commits to a new branch and leaves a link to the pull request page, so a person decides and branch protection stays in the path. The FAQ says Claude never merges, rebases or force pushes, and that this lives in its system prompt, so it holds even when you allow the git tools.

On a pull request the action first restores a fixed list of Claude files from the base branch: .claude/, .mcp.json, .claude.json, .gitmodules, .ripgreprc, CLAUDE.md, CLAUDE.local.md and .husky/. The pull request's own copies are kept under .claude-pr/ for reference. Everything else stays at the head, so a hook that runs npm run format still resolves through the PR's package.json. Keep hook commands self-contained.

pull_request_target and workflow_run run with the base repository's secrets. That makes the checkout the dangerous step, and this is the pattern the security page gives when you need the PR files.

# If you need the PR's files locally, check out the base ref at the workspace
# root (this action expects a git repo there), then check out the head ref into
# a subdirectory and pass it via --add-dir.
- uses: actions/checkout@v6 # no ref input: base branch at workspace root
- uses: actions/checkout@v6
  with:
    # For workflow_run use: ${{ github.event.workflow_run.head_sha }}
    ref: ${{ github.event.pull_request.head.sha }}
    path: pr-head
- uses: anthropics/claude-code-action@v1
  with:
    claude_args: "--add-dir pr-head"

Untrusted input and the settings that widen it

• Hidden instructions can ride in HTML comments, invisible characters and hidden attributes. The action strips HTML comments, invisible characters, image alt text, hidden attributes and entities, and the docs say new bypasses may appear. Read the raw text before you tag Claude on an outsider's issue. On public repositories include_comments_by_actor limits whose comments reach Claude, and exclusion wins when an actor is in both lists.
• allowed_bots: '*' on a public repository lets any GitHub App invoke the action with a prompt it controls. Prefer a named list.
• allowed_non_write_users is marked risky. It works only with github_token, which should be secrets.GITHUB_TOKEN and never a personal access token, and the docs suggest limiting tools to the minimum. Claude scrubs secrets from subprocess environments on a best-effort basis, and CLAUDE_CODE_SCRIPT_CAPS limits calls to named scripts.
• show_full_output is off by default because it prints every tool result, including env and file reads, and public repositories show those logs to everyone. It switches on by itself when Actions debug mode is on.
• The Bash tool is off by default in the action. List commands in --allowedTools, such as Bash(npm:*). Two MCP servers, GitHub and file operations, start automatically, and their tools still need --allowedTools.
• To keep a static key out of the repository, use workload identity federation. The action trades the workflow's OIDC token for Claude API access through a Console service account, using anthropic_federation_rule_id and anthropic_organization_id.

Cost, and how to stop a runaway job

Every run uses GitHub Actions minutes on your runner and API tokens for each interaction. With an OAuth token the tokens come out of your Claude subscription, not API billing. Rates change, so the docs point you to GitHub's billing page and Claude's pricing page and print no figures.

claude_args takes any CLI flag, which is how the v1 action carries --max-turns and a system prompt addition.

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --max-turns 10
      --append-system-prompt "Focus on security"

• Write specific @claude requests and use issue templates, so Claude needs fewer turns.
• Keep CLAUDE.md short, because Claude reads it on every run. The CLAUDE.md guide covers what to put in it.
• Set --max-turns in claude_args, a workflow-level timeout and GitHub's concurrency controls to limit parallel runs.

Boris Cherny's review habit: tag @claude to update CLAUDE.md

Boris Cherny, who created Claude Code, described a review habit on X in tip 5 of a thread. During code review he often tags Claude on a coworker's pull request and asks it to add something to CLAUDE.md as part of that pull request. His team runs this through the GitHub Action, and he calls it their version of Dan Shipper's Compounding Engineering.

His post names the command /install-github-action. The command in Anthropic's docs is /install-github-app, the one this lesson uses.

To copy the habit, keep the mention workflow above with contents: write and pull-requests: write, so Claude can commit its CLAUDE.md edit to that same pull request. In review, comment @claude add a line to CLAUDE.md about the thing you just caught. The rule lands with the change that taught it. Keep each line short, since Claude reads the file on every run.

A screenshot of X's own embed of the post, taken on 5 November 2026, with the time in UTC. Select it to open the post on X.

Common mistakes

• Tagging @claude from another workflow. The github-actions user cannot trigger further workflows, which prevents loops, so the comment needs a token from a user or an app of your own.
• Passing github_token: secrets.GITHUB_TOKEN and wondering why CI skips Claude's commits. GitHub does not run workflows for commits made with that token. Remove the input so the action authenticates as the Claude GitHub App, and note that allowed_non_write_users needs your own token.
• A comment that is not the trigger phrase as a whole word. /claude and @claude-bot do nothing unless you change trigger_phrase.
• Leaving a workflow on @beta. Change it to @v1, drop the mode input, rename direct_prompt to prompt and move max_turns and model into claude_args.
• Debugging the workflow before the credential. Test the API key or OAuth token locally with claude first.

Try it yourself

• In a scratch repository, run /install-github-app, merge the pull request and comment @claude with a question about one file. Watch the single comment update as the run progresses.
• Comment /claude and then @claude-bot and confirm that no run starts. Change trigger_phrase and try again.
• Copy the review workflow, remove id-token: write and read the error in the run log. Put it back.
• Add claude_args: "--max-turns 3" to the workflow and give Claude a task that needs more turns. Compare the run with and without the cap.

Next: build your own agent with the Agent SDK

Anthropic points to the Claude Agent SDK for automation outside GitHub Actions, and the action runs on it too. The last lesson, build an agent with the Claude Agent SDK, shows the same loop as a library.

The review workflow above already installs a plugin through the plugins and plugin_marketplaces inputs. The plugins post covers what a plugin can hold.

Frequently asked questions

Sources

1. Claude Code docs: Claude Code GitHub Actions (read November 5, 2026)https://code.claude.com/docs/en/github-actions
2. claude-code-action docs: Security (read November 4, 2026)https://github.com/anthropics/claude-code-action/blob/main/docs/security.md
3. claude-code-action docs: Usage (read November 4, 2026)https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
4. claude-code-action docs: FAQ (read November 4, 2026)https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md
5. claude-code-action docs: Setup guide (read November 4, 2026)https://github.com/anthropics/claude-code-action/blob/main/docs/setup.md
6. anthropics/claude-code-action on GitHub (read November 5, 2026)https://github.com/anthropics/claude-code-action
7. claude-code-action release v1.0.268 on GitHub (read November 5, 2026)https://github.com/anthropics/claude-code-action/releases/tag/v1.0.268
8. Boris Cherny on X: tag @claude on PRs to update CLAUDE.md (read November 5, 2026)https://x.com/bcherny/status/2007179842928947333