Claude Code GitHub Actions: setup with an API key or plan

Claude Code GitHub Actions setup is one command, /install-github-app, run inside a claude session in the repository. Claude Code installs the Claude GitHub App, saves an API key or a Claude plan token as a repository secret, pushes a branch with the workflow and opens the pull request in your browser. Merge it and @claude starts answering in issues and pull requests.

That route and the manual one both need admin access to the repository. Commands, inputs and error causes on this page are from Anthropic's GitHub Actions page, first read on 23 October 2026 and checked again on 25 October, and from the action's own docs in anthropics/claude-code-action.

Quick setup with /install-github-app#

1. gh auth login. Claude Code looks for the GitHub CLI and warns when gh is missing.
2. claude in the repository, then /install-github-app. The Claude GitHub App install is the first screen.
3. The secret.
   • An API key Claude Code already has gets reused, and an existing ANTHROPIC_API_KEY secret can stay.
   • With no key, the choice is a long-lived subscription token or a pasted API key.
   • Secret names: ANTHROPIC_API_KEY for a key, CLAUDE_CODE_OAUTH_TOKEN for a subscription token.
4. The workflow files.
   • claude.yml answers @claude.
   • claude-code-review.yml posts review findings on the pull request.
   • Both land on a new branch, already reading that secret, and GitHub opens with the pull request ready to create. Merging it is the last step.

Edge cases on the same page:

• Remote on gitlab.com or bitbucket.org: a notice, then exit. The command is github.com only.
• Esc mid-way: the running step finishes and nothing after it starts. The closing message lists what already happened, a pushed branch or a saved secret for example.
• Skip for now, offered after the app install, stops with only the app in place.
• A repository that already has claude.yml: Update workflow file with latest version.

Manual setup#

/install-github-app does three things, and each can be done by hand.

1. The Claude GitHub App, github.com/apps/claude, on the repository.
   • Permissions the action uses: Contents, Issues and Pull requests, each read and write.
   • Permissions GitHub asks for: all 13, Workflows and Repository hooks included, because Anthropic's Code Review and pull request auto-fix run on the same app.
   • Only the three: an organisation registers its own GitHub App (the action ships github-app-manifest.json for it) and stores APP_ID and APP_PRIVATE_KEY as secrets. That app covers the action and nothing else.
2. A repository secret, under Settings › Secrets and variables › Actions › New repository secret.
   • ANTHROPIC_API_KEY: a Claude Console key, starting sk-ant-.
   • CLAUDE_CODE_OAUTH_TOKEN: what claude setup-token prints.
   • Workflow input names: anthropic_api_key and claude_code_oauth_token.
3. examples/claude.yml, copied into .github/workflows/ as committed. It is a working workflow, not a sketch.

The @claude workflow, line by line#

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

• if: keeps a runner from starting for comments that don't mention @claude.
• id-token: write is needed for the action's default sign-in as the GitHub App. Without it the run fails with an OIDC authentication error.
• actions: read lets Claude read CI results on the pull request.
• actions/checkout gives Claude a copy of the repository to work in.

With no prompt input, the action waits for @claude in a comment, a review, or the title or body of a new issue. A comment such as @claude implement this feature based on the issue description is enough. What GitHub then shows:

• One comment from claude[bot], edited as Claude works, with checkboxes ticking off its tasks.
• On an open pull request, commits on that pull request's branch.
• On an issue or a closed pull request, a new branch (default prefix claude/) and a link to a pre-filled pull request page. Claude doesn't open the pull request itself.

Give it a prompt and it runs on its own on any GitHub event, a schedule included; results then go to the workflow log unless the prompt has Claude post them.

Use your Claude plan instead of an API key#

On Pro, Max, Team and Enterprise plans, a workflow can run on your subscription:

1. claude setup-token on your own computer. It prints the token without saving it (what that token can and can't do).
2. A repository secret named CLAUDE_CODE_OAUTH_TOKEN holding it.
3. In the Claude step, claude_code_oauth_token reading secrets.CLAUDE_CODE_OAUTH_TOKEN in place of the anthropic_api_key line.

Runs then count against that subscription instead of API billing. The token belongs to the person who ran claude setup-token, so for a secret shared across an organisation Anthropic recommends an API key. The other route is workload identity federation: the action swaps the workflow's GitHub OIDC token for access through a Console service account, and no long-lived secret is stored at all. Bedrock, Google Cloud's Agent Platform and Microsoft Foundry also work, with use_bedrock, use_vertex or use_foundry and OIDC.

Inputs worth knowing#

A plain-text prompt starts with no shell and no GitHub API access. Anthropic's daily-report example grants two GitHub MCP tools with --allowedTools "mcp__github__list_commits,mcp__github__list_issues" in claude_args; a permissions.allow rule in settings does the same job (permission rule syntax). A skill as the prompt gets the tools its own allowed-tools frontmatter lists. Under the hood every run is a claude -p call, the headless mode of the CLI.

Workflows written for @beta need four edits for @v1:

1. anthropics/claude-code-action@beta becomes @v1.
2. The mode input goes.
3. direct_prompt is renamed prompt.
4. max_turns, model and similar options move into claude_args.

Why runs fail#

Claude doesn't answer @claude. Anthropic's list, in order:

1. Claude GitHub App not installed on this repository.
2. Actions workflows disabled for the repository.
3. No secret called ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN.
4. @claude not a whole word. The match uses word boundaries, so /claude, @claude-bot and @claude! don't count.
5. Commenter without write access. The action checks it on issue and pull request events, and lets others in only through allowed_non_write_users plus your own github_token. Bot actors are refused unless listed in allowed_bots, so two bots can't set each other off in a loop.

CI doesn't run on Claude's commits.

• GitHub starts no workflow for a push made with the default GITHUB_TOKEN.
• github_token: ${{ secrets.GITHUB_TOKEN }} on the Claude step is the usual cause. Without it, pushes come from the Claude GitHub App.
• A token from an app of your own works as well.
• Your CI's on: block still has to list the events those pushes produce, push or pull_request.

Authentication errors. Run claude on your own computer with the same key or token before you debug the workflow.

A scheduled run never starts.

• schedule runs only from the default branch.
• In a public repository GitHub switches it off after 60 days without activity.
• GitHub attributes the run to a repository user, usually whoever last changed the cron line. A bot there is refused until it's in allowed_bots.

Opening the pull request from Shuriken#

Shuriken sits at the other end of these pull requests. Every chat but a project's Main chat works on its own branch. With GitHub connected, Create PR in the git menu at the top of the chat opens a pull request for it. Before anything is pushed, Shuriken scans what the branch adds for things that look like secrets; if it finds one, it stops and shows you the file. On GitHub the workflows above run on that pull request as on any other, and an @claude comment works the same.

Auto merge, in the same menu, asks GitHub to merge it (squash, merge or rebase) once the required reviews and checks pass. The repository has to allow auto-merge. A solo repository with no CI can skip GitHub: Finish runs the checks listed in shuriken.json on your computer, then rebases and squash-merges (parallel agents).