How to set up Claude Code GitHub Actions, with a workflow you can copy

What is Claude Code GitHub Actions?

It is a GitHub Action, anthropics/claude-code-action, that runs Claude Code on a GitHub-hosted runner as part of a workflow. It has two modes, and which one you get depends on your workflow file. The details below follow the Claude Code GitHub Actions page of the docs, checked in October 2026.

Several products share the Claude Code name, so check you are reading the right page. This guide covers the workflow integration you configure with files in your repository. Code Review (automatic review on every pull request with no workflow to write), Claude Code in the cloud, and the Agent SDK are separate things. If you only want reviews and do not want to maintain YAML, look at Code Review first.

How do you set it up with /install-github-app?

Quick setup works only for repositories on github.com. If your remote is on gitlab.com or bitbucket.org, the command prints a notice and exits. You also need admin access to the repository.

1. Install the GitHub CLI and sign in with gh auth login. Claude Code checks for it and warns you if it is missing.
2. Open Claude Code in the repository by running claude in the project folder.
3. Run /install-github-app and follow the prompts. Claude Code installs the Claude GitHub App first.
4. Choose how to authenticate. If Claude Code already has an API key it reuses it. Otherwise you pick between creating a long-lived token with your Claude subscription and pasting an API key. The credential is saved as a repository secret named ANTHROPIC_API_KEY for a key or CLAUDE_CODE_OAUTH_TOKEN for a subscription token.
5. Pick the workflow files. Claude Code pushes a branch with them, already set to use the secret, and opens GitHub in your browser with a pull request ready to create.
6. Create and merge that pull request. From then on, @claude works in the repository.

You can stop partway by pressing Esc. A step already running finishes and no later step starts. If you choose Skip for now after the app installs, you can run /install-github-app again later to finish the workflow and secret steps. If you select the review workflow, Claude posts its review on the pull request itself, as inline comments or one summary comment, and skips draft pull requests.

How do you set it up by hand?

Use the manual path when you do not run Claude Code locally, when the command fails, or when you want full control of the files.

1. Install the Claude GitHub App from github.com/apps/claude on your repository. The action relies on three of its permissions: Contents (read and write), Issues (read and write) and Pull requests (read and write).
2. Add an authentication secret under the repository's Actions secrets: ANTHROPIC_API_KEY (a key from the Claude Console) or CLAUDE_CODE_OAUTH_TOKEN (a token for your subscription, generated by running claude setup-token locally).
3. Copy the workflow file into .github/workflows/. The template below is the one from the docs.

The Claude Code API key guide explains the difference between the two credentials and what each one bills.

For a secret shared across an organization, the docs recommend an API key from the Console, because an OAuth token is tied to the subscription of the person who ran claude setup-token. If you would rather store no long-lived secret at all, the action supports workload identity federation through a Console service account, which needs the id-token: write permission.

What does a working @claude workflow look like?

This is the interactive workflow from the docs. Save it as .github/workflows/claude.yml. It responds whenever someone comments @claude on an issue or pull request.

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 parts that are not boilerplate:

• 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 repository to work in.
• The if line keeps runners from starting on comments that do not mention @claude. The action also checks the trigger phrase itself.
• Using a subscription token? Replace the anthropic_api_key line with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Then comment on any issue or pull request. The docs give these examples:

@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

Claude replies in a comment on the same issue or pull request and updates it as it works. Comments must contain @claude as a complete word. /claude and @claude-bot do not count.

How do you run Claude on a schedule or on every pull request?

Give the action a prompt input and it switches to automation mode. For a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools it needs, with --allowedTools inside claude_args or a permissions.allow rule in the settings input. GitHub runs scheduled workflows only from the default branch, and in public repositories it disables the schedule after 60 days without repository activity.

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 pull request reviews, the docs show a workflow that installs the code-review plugin and runs its skill when a pull request is opened, updated, reopened or marked ready for review. It uses the plugin_marketplaces and plugins inputs and a prompt of /code-review:code-review --comment plus the pull request reference. Two details matter. The --comment flag is what makes Claude post the review on the pull request; without it you read findings only in the run log. And the claude_args line naming mcp__github_inline_comment__create_inline_comment must stay, because the action starts the inline comment server only when --allowedTools names it. On public repositories GitHub withholds secrets from fork pull requests, so the review runs only on branches in the same repository. Copy the full file from the docs page rather than retyping it.

The models guide explains what to put after --model, and the permissions guide explains the allow rules the settings input accepts.

How can you use it to turn an idea into a pull request?

A practical loop for a solo builder: write the feature as an issue, comment @claude, and review the pull request it opens. A build prompt from the board makes a good issue body, because it already states the problem, the first version and what to leave out. Browse developer tools ideas for one, or post the idea you will not build yourself.

1. Create an issue titled with the feature and paste the build prompt as the body.
2. Comment: @claude implement this feature based on the issue description.
3. Read the pull request Claude opens. Run the app. Comment @claude again with specific fixes.
4. Merge only when you have read the diff. The docs advise reviewing Claude's changes before merging.

Keep a short CLAUDE.md in the repository root with your code style, test commands and review criteria. Claude follows it when creating pull requests, and the docs note it is read on every run, so brevity lowers cost.

Who can trigger Claude, and how do you keep it safe?

Before Claude starts, the action checks the person who triggered it, and the run fails if a check rejects them. On issue and pull request events the user must have write access to the repository. To allow specific users without write access, set allowed_non_write_users and pass your own github_token. On every event a bot actor is rejected unless you list it in allowed_bots, which keeps bots from triggering Claude in a loop.

• Never commit a key. Store ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a GitHub Secret and reference it from the workflow.
• Grant only the permissions the job needs. The read-only report above needs no write access.
• Review before merging. Claude's pull requests are proposals.
• Limit the work. Use --max-turns in claude_args, set workflow-level timeouts and use GitHub's concurrency controls.

For the full threat model, the docs point to the action's own security documentation on GitHub.

What does it cost to run?

Each run uses two resources. The first is GitHub Actions minutes, because the action runs on GitHub-hosted runners; see GitHub's billing documentation for pricing and limits. The second is API tokens, which depend on prompt and response length, task complexity and codebase size. If you authenticate with an OAuth token, runs use your Claude subscription instead of API billing. The Claude Code pricing guide covers plans.

• Write specific @claude requests so Claude needs fewer turns.
• Use issue templates to supply context up front.
• Keep CLAUDE.md concise.
• Set --max-turns and a job timeout.
• Use concurrency controls to cap parallel runs.

Why is Claude not responding, or CI not running?

If your workflows still use anthropics/claude-code-action@beta, change it to @v1, remove the mode input (the action now detects the mode), replace direct_prompt with prompt, and move CLI options such as max_turns and model into claude_args.