Claude Code GitHub Actions

Who this is for

This guide is for developers and maintainers who host code on GitHub and want Claude Code to help inside the repository: answering @claude mentions on issues and pull requests, running a scheduled task, or posting reviews. After reading it you should be able to connect a repository, write a first workflow, decide between interactive and automation mode, and understand who can trigger Claude and what each run costs.

What the action is

Claude Code GitHub Actions is a GitHub Action, anthropics/claude-code-action, that runs Claude Code inside your repository's workflows. Mention @claude in a pull request or issue comment and Claude can analyze code, implement features, fix bugs and turn issues into pull requests^[1].

For a team, the appeal is that Claude joins the pull request and issue flow you already use. Requests are written as comments, and results come back as pull request comments or in the workflow run log, so you do not need a separate entry point outside the repository.

Several products share the Claude Code name, so check which one you need. This page covers the workflow integration, which is configured with files in your repository. Code Review is different: it reviews every pull request automatically without a workflow file. The Agent SDK is the foundation for custom automation outside GitHub Actions^[1].

Prepare

You need admin access to the repository, whichever setup path you take^[1]. The quick path also needs the GitHub CLI, which you install and sign in to with gh auth login. Claude Code checks for it and warns you if it is missing^[1]. The quick path works only with github.com repositories. If your remote is on gitlab.com or bitbucket.org, the command prints a notice and stops^[1].

For the credential, you have two options. An API key from the Claude Console is stored as the ANTHROPIC_API_KEY secret. A subscription token, created with claude setup-token, is stored as CLAUDE_CODE_OAUTH_TOKEN. The token is available on Pro, Max, Ultra, Team and Enterprise plans^[1].

Quick setup

Open claude in the repository and run /install-github-app. Claude Code installs the Claude GitHub App, sets up the authentication secret, pushes a branch with the workflow files you chose, and opens GitHub in the browser with a pull request ready to create. Merge that pull request and @claude works in the repository^[1].

Manual setup

Manual setup has three steps. First, install the Claude GitHub App, which needs read and write access to Contents, Issues and Pull requests^[1]. Second, add the secret. Third, copy the example workflow file into .github/workflows/^[1].

In the workflow, pass the secret to the matching input: anthropic_api_key for an API key, or claude_code_oauth_token for an OAuth token^[1]. The first workflow below responds to @claude mentions:

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

Once the workflow is in place, a comment such as @claude fix the TypeError in the user dashboard component asks Claude to fix that bug^[1].

Read the workflow file

The workflow is an ordinary GitHub Actions file. The on block lists the events that start it; in the example they are comments on issues and on pull request reviews. Under jobs, each job holds a list of steps, and each step either runs a command or uses an action. The permissions block sets what the job's token may do. The example opens write access to contents, pull requests and issues, and you should keep only the permissions your use case needs.

Interactive or automation mode

The action picks its mode from the workflow. With no prompt input, it is in interactive mode and waits for the trigger phrase, @claude by default. That phrase can appear in an issue or pull request comment, a pull request review, or the title or body of a newly opened issue^[1]. With a prompt input, it is in automation mode. It runs without waiting for a mention, and by default its results appear in the workflow run log^[1].

The prompt input also accepts a skill. For a skill in the repository's .claude/skills/ directory, run actions/checkout before the action step so the skill files exist on the runner^[1]. A review workflow adds the --comment argument so Claude posts its findings on the pull request. Without that argument, Claude posts nothing^[1]. A prompt-based workflow can also run on a schedule, for example a daily report in the run log^[1].

Who can trigger Claude

Before Claude starts, the action checks the person who triggered the run. On issue and pull request events, that person needs write access to the repository. You can allow specific users without write access by setting allowed_non_write_users and passing your own github_token^[1]. The action also rejects bot actors unless they are listed in allowed_bots^[1].

The two checks in the previous section decide who can start a run, not what Claude does once it starts. Read them together with the workflow's own triggers: a workflow that listens only to issue comments will not run for other events.

Keep cost and risk in check

Each run uses GitHub Actions minutes, because the action runs on GitHub-hosted runners, and it also uses API tokens^[1]. --max-turns in claude_args caps the number of iterations, and workflow-level timeouts and concurrency controls help avoid runaway jobs^[1].

Keep API keys and OAuth tokens out of the repository and store them as GitHub Secrets. A CLAUDE.md file in the repository root tells Claude your style rules and review criteria, and Claude follows them when it creates pull requests^[1].

Parameters you will use most

Because the parameters live in the workflow file, they are versioned and reviewed together with the rest of the code.

The prompt input holds instructions, and claude_args takes CLI arguments such as --max-turns, --model, --mcp-config, --allowedTools (comma-separated) and --debug^[1]. trigger_phrase changes the phrase Claude responds to, and its default is @claude^[1].

Cloud providers

To use your own cloud account, set use_bedrock: "true" for Amazon Bedrock, use_vertex: "true" for Google Cloud's Agent Platform, or use_foundry: "true" for Microsoft Foundry. These providers authenticate through OIDC identity federation, so no static cloud credentials are stored in the repository^[1]. Credentials stay out of the repository, and you choose the destination of each run by setting one provider input.

Common problems

GitHub does not start workflows for commits made with the default GITHUB_TOKEN. If you pass github_token: ${{ secrets.GITHUB_TOKEN }} to the action, remove it, so the commits Claude pushes can start your CI^[1]. If @claude gets no reply, check that the GitHub App is installed, that workflows are enabled, that the secret is set, that the mention is a complete word rather than /claude or @claude-bot, and that the commenter has write access^[1].

When something breaks, work through the checks from the one closest to you: repository setup, secrets, trigger phrase, then permissions, rather than editing the workflow again and again^[1].

When a run fails, start with the workflow run log. Automation mode writes its results there by default, and that is also where you can see what the run did^[1].

To move from the beta, change @beta to @v1, remove the mode input and replace direct_prompt with prompt^[1].

Next steps

For an organization, install the Claude GitHub App once at the organization level, store the secret as an organization-level Actions secret, then add the workflow to each repository or define it once as a reusable workflow^[1]. More inputs and provider details are on the official page^[1].