heydeer

Claude GitHub app: connect GitHub and use @claude in PRs

· · 12 min read

“The Claude GitHub app” gets used for two different things: letting Claude read a repository in a claude.ai chat, and letting Claude Code work inside the repository from GitHub itself. Both run through the same GitHub App, but they set up, cost and behave very differently.

The Claude GitHub app is Anthropic’s GitHub App at github.com/apps/claude. Connecting it to claude.ai lets Claude read files from your repositories in chats and projects. Paired with the claude-code-action workflow, set up with /install-github-app in Claude Code, it lets you mention @claude in pull requests and issues to have Claude Code answer questions, change code and push commits from a GitHub Actions runner.

What the Claude GitHub app is: one app, two products

Anthropic publishes a single GitHub App, the Claude GitHub App. Several products lean on it:

  • claude.ai’s GitHub integration reads files from repositories you add to a chat or a project. The app comes in when a repository is private and Claude needs permission to read it.
  • The Claude Code GitHub Action (anthropics/claude-code-action) runs Claude Code in your workflows, so you can write @claude fix this on a pull request and get commits back.
  • Claude Code Review and auto-fix for pull requests in Claude Code cloud sessions use the same installation.

The first is a read-only window into your code for conversation. The second is an agent with write access that runs on your CI. Most confusion about the Claude GitHub app comes from expecting one to behave like the other, so the two are covered separately below.

How to connect GitHub to Claude on claude.ai

The GitHub integration is available on every claude.ai plan, including Free, and works with public repositories and private ones you grant access to.

  1. Go to Customize > Connectors, select GitHub Integration and select Connect.
  2. In a chat, select + and then Add from GitHub, search for a repository or paste its URL, and select Add repository.
  3. In a project, open project knowledge, select + and then GitHub, pick the files and folders Claude should read and select Add files. This works in private projects only; in a shared project the option is dimmed.

If Claude says it cannot access the resource, the repository is almost certainly private. The link in that message opens the Claude GitHub App installation page, where you grant access to all repositories or selected ones, or, for an organization you don’t administer, request access and wait for an owner to approve it. On Team and Enterprise plans, an organization admin has to turn GitHub on under Organization settings > Connectors before it appears.

Be clear about what Claude sees. It reads file names, file contents and the branch content you selected. It doesn’t see commit history, pull requests, issues or repository metadata, and project content doesn’t update by itself: select Sync now on the repository before asking about recent changes. Choose files deliberately, too; everything you add has to fit in the context window, so a focused set of directories gets better answers than the whole monorepo.

This is the right tool for “explain how authentication works in this service” or “draft a migration plan for this module.” To change code, you need Claude Code.

How to set up the Claude Code GitHub Action with /install-github-app

The Claude Code GitHub Action runs Claude Code inside a GitHub Actions job whenever someone mentions @claude. The quickest setup is from Claude Code itself. You need admin access to the repository, a github.com remote (the command exits on GitLab and Bitbucket remotes) and the GitHub CLI signed in with gh auth login.

  1. Run claude in the repository and type /install-github-app.
  2. Install the Claude GitHub App in the browser tab that opens, give it the repository, and press Enter back in the terminal.
  3. Select Set up GitHub Actions workflows. You can keep the @claude mentions workflow, the pull request review workflow, or both.
  4. Choose a credential: a long-lived token from your Claude subscription, or a Claude API key. It’s saved as the repository secret CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.
  5. Confirm, and Claude Code pushes a branch with the workflow files. Create and merge the pull request it opens; the workflows are live once they’re on the default branch.

Test it by commenting @claude with a small request on an issue. If you run inference through Amazon Bedrock, Google Cloud or Microsoft Foundry, quick setup isn’t the path; those use the cloud-provider inputs and OIDC instead.

Manual setup and the workflow file

Without a local Claude Code, do the same three things by hand: install the app from github.com/apps/claude, add ANTHROPIC_API_KEY (from the Claude Console) or CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token) as a repository secret, and commit a workflow. This one is the action’s own example with two additions worth having from day one, a job timeout and a turn limit:

# .github/workflows/claude.yml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
    runs-on: ubuntu-latest
    timeout-minutes: 30
    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 }}
          # or, with a Claude subscription:
          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          claude_args: |
            --max-turns 10

The if condition keeps a runner from starting for every comment on the repository. id-token: write is needed for the action’s default GitHub App authentication, and actions: read lets Claude read CI results on the pull request. The current major version is @v1; workflows still on @beta need direct_prompt renamed to prompt and CLI options such as max_turns moved into claude_args.

Rolling out across an organization works the same way at a larger scale: install the app once for the organization, store an API key as an organization secret (an OAuth token is tied to whoever generated it), and add the workflow to each repository or call a reusable workflow. To avoid a stored key altogether, the action supports workload identity federation through a Claude Console service account.

Working with @claude mentions

With no prompt input, the action runs in interactive mode and waits for @claude in a pull request or issue comment, an inline review comment, a submitted review, or the title or body of a new issue. Requests look like this:

@claude why does this test fail only on CI?
@claude implement this feature based on the issue description
@claude fix the TypeError in the user dashboard component
@claude add a test for the empty-cart case and push it to this branch

Claude replies in a comment and updates it with a checklist as it works. On an open pull request it pushes commits to that pull request’s branch. On an issue, it pushes a new branch (named claude/issue-123-… by default) and gives you a link to a pre-filled pull request rather than opening one itself, so branch protection and the decision to open the pull request stay with you.

A few behaviors are deliberate and worth knowing before the first surprise:

  • Only people with write access can trigger it, and bot accounts are rejected unless listed in allowed_bots, which keeps two bots from triggering each other in a loop.
  • It adds commits and nothing else. Claude doesn’t merge, rebase or force-push, and only pushes to the branch it was invoked on. Rebases are yours to do locally.
  • It leaves .github/workflows/ to you. The action’s FAQ says the app doesn’t get workflow write access for security reasons, so changes to CI configuration stay with a person.
  • @claude must be a whole word. @claude-bot and /claude don’t match. Change the phrase with trigger_phrase, or trigger from issues with assignee_trigger or label_trigger.

Claude reads CLAUDE.md on every run, so the conventions you already wrote for local Claude Code sessions apply here too. Keep it short, since it’s read every time; the CLAUDE.md best practices guide covers what earns a place in it.

Give the action a prompt input instead and it runs in automation mode on any event, including a schedule or every new pull request. Automatic pull request review is the most common use, and it has its own guide: the Claude Code review skill, plugin and GitHub workflow.

Permissions, security and cost

Installing the Claude GitHub App grants its whole permission set, because every Claude feature shares one app. That includes read and write on contents, issues, pull requests, checks, actions, discussions and workflows, plus read access to items such as Dependabot alerts and members. GitHub doesn’t let you accept a subset. When your organization needs only what the action uses, create your own GitHub App with Contents, Issues and Pull requests set to read and write, using the action’s setup guide. A custom app covers the action only; Claude Code Review and web auto-fix still need Anthropic’s.

Each run costs in two places. The job uses GitHub Actions minutes on a GitHub-hosted runner, and Claude itself uses API tokens billed to your Console account, or your subscription’s usage if you authenticated with an OAuth token. Long sessions on large repositories add up on both meters. The controls that help are the ones in the workflow above, a --max-turns limit and a job timeout-minutes, along with a concurrency group so a burst of mentions doesn’t start a burst of runners, and specific requests that finish in fewer turns.

The Claude GitHub app covers two products. On claude.ai, it lets Claude read files from your repositories in chats and private projects, with no write access and no view of pull requests or issues. With the claude-code-action workflow, it lets anyone with write access mention @claude on a pull request or issue and get Claude Code’s answer or commits, paid for in GitHub Actions minutes plus Claude API or subscription usage.

GitHub coding agents you can mention or assign

The Claude Code GitHub Action is one of several agents that take work from a GitHub comment. They differ less in what they can write than in where they run, where their changes land and how you pay.

AgentHow you start itWhere it runsWhere changes goHow you pay
Claude Code GitHub Action@claude in a PR or issue comment, a review, or a new issue’s title or body; optionally an assignee or label triggerYour own GitHub Actions runnerCommits to the PR branch; on an issue, a new branch plus a link to a pre-filled pull requestGitHub Actions minutes, plus Claude API tokens or your Claude subscription
GitHub Copilot cloud agent (formerly coding agent)Assign an issue to Copilot, mention @copilot on a pull request, or use the Agents tabGitHub Actions or a cloud sandboxOpens a pull request for a task; on an existing PR, commits to its branch by defaultA paid Copilot plan; compute draws on the GitHub account allowance
Codex GitHub integration@codex review or automatic reviews on pull requests; code tasks start in Codex web, app or CLIA Codex cloud environmentYou review the task’s changes and open a pull request from CodexChatGPT plan usage (cloud tasks and code review on Plus, Pro, Business, Enterprise and Edu)
HeyDeer @heydeer@heydeer in a PR or issue comment, an inline review comment, a review summary, or a new PR or issue descriptionHeyDeer’s isolated sandboxA new pull request; its own PR’s branch; or your branch when you askWorkspace credits

GitHub Copilot coding agent

GitHub launched it as the Copilot coding agent and its docs now call it Copilot cloud agent. It is the most native of the group: you assign an issue to Copilot like a teammate, and it opens a pull request and requests your review. Mention @copilot on any pull request and it commits to that branch by default. It only responds to people with write access, sees an issue’s content at assignment time (later comments go on its pull request instead), and by default your Actions workflows don’t run on its pushes until a reviewer selects Approve and run workflows. It needs a paid Copilot plan.

Codex GitHub integration

OpenAI’s Codex GitHub integration connects a repository to a Codex cloud environment. On GitHub itself it is review-shaped: comment @codex review on a pull request, or turn on automatic reviews, and Codex posts a review limited to P0 and P1 issues, following the review rules in your AGENTS.md. Code changes run as cloud tasks you start from Codex on the web, the desktop app or the CLI, and you open the pull request from the result. The Codex code review guide goes deeper on the review side.

HeyDeer @heydeer mentions

HeyDeer is an AI code review agent for GitHub pull requests, and @heydeer mentions hand it the rest of the conversation. Ask @heydeer what does this function do? and it reads the code and replies. Ask @heydeer fix the first issue and open an issue for the second and it changes the code, opens a pull request with the fix and files the issue. It can also start a review, check documentation on the web, and resolve merge conflicts by merging the base branch into the pull request’s branch (the guide to resolving conflicts on GitHub covers the manual route too).

There’s no workflow file to maintain. HeyDeer works in its own sandbox, reads AGENTS.md before changing code, can install dependencies and run your tests, and acts with the permissions of the person who asked, so branch protection applies as usual. While a task runs, a link to it sits at the end of your comment, and every request appears under Tasks in HeyDeer with its progress and results. On a pull request with Autopilot running, mentions go to Autopilot, which works through findings, failing checks and conflicts until the pull request is ready.

HeyDeer answers @heydeer mentions in GitHub pull requests and issues: it explains code, changes it and opens a pull request, opens issues, starts a review or resolves merge conflicts, working in its own sandbox with the access of the person who asked. There is no workflow file or runner to manage, and each request appears under Tasks with its progress and results.

Which one fits comes down to where you want the work to happen. The Claude Code GitHub Action gives you Claude Code on infrastructure you control, configured in YAML. Copilot’s agent is the shortest path for a team already paying for Copilot. Codex suits teams who start work in Codex and use GitHub for review. HeyDeer fits teams that want the reviewer and the agent that acts on its findings to be the same tool, reachable from any comment.

Sources

  1. Claude Docs: GitHub integration
  2. Claude Help Center: Use the GitHub integration
  3. Claude Code Docs: Claude Code GitHub Actions
  4. anthropics/claude-code-action: README
  5. anthropics/claude-code-action: Setup guide
  6. anthropics/claude-code-action: FAQ
  7. anthropics/claude-code-action: action.yml inputs
  8. GitHub Docs: About Copilot cloud agent
  9. GitHub Docs: Use Copilot cloud agent on GitHub
  10. GitHub Changelog: GitHub Copilot coding agent in public preview
  11. OpenAI Codex docs: Codex code review in GitHub
  12. OpenAI Codex docs: Codex cloud
  13. OpenAI Codex docs: Pricing

Frequently asked questions

What is the Claude GitHub app?

The Claude GitHub app is Anthropic’s GitHub App at github.com/apps/claude. claude.ai uses it to read private repositories you add to chats and projects, and Claude Code uses it for the Claude Code GitHub Action, Claude Code Review and auto-fix in cloud sessions. One installation serves all of them, with one permission set.

How do I connect GitHub to Claude?

To connect GitHub to Claude on claude.ai, go to Customize > Connectors, select GitHub Integration and select Connect. Then use + > Add from GitHub in a chat, or + > GitHub in a private project’s knowledge. For a private repository, grant access through the Claude GitHub App when Claude asks for it.

Can Claude edit code in my GitHub repository from claude.ai?

Claude on claude.ai reads repository files you add, including file names, contents and branch content, and answers questions about them. It doesn’t see commit history, pull requests or issues. To have Claude edit code, run commands and push commits, use Claude Code, including the Claude Code GitHub Action.

What does /install-github-app do?

/install-github-app is a Claude Code command that sets up the Claude Code GitHub Action for a github.com repository. It opens the Claude GitHub App install page, saves an API key or subscription token as a repository secret, and pushes a branch with workflow files for you to merge. It needs repository admin access and a signed-in GitHub CLI.

Can I use the Claude Code GitHub Action with a Claude Pro or Max subscription?

The Claude Code GitHub Action works with a Claude subscription: run claude setup-token locally, store the token as the CLAUDE_CODE_OAUTH_TOKEN secret and pass it as claude_code_oauth_token. Runs then use your subscription instead of API billing. For a secret shared across an organization, Anthropic recommends an API key instead.

Why doesn’t Claude respond to my @claude comment?

When Claude doesn’t respond to @claude, check that the Claude GitHub App is installed on the repository, the workflow file is on the default branch and enabled, the secret is set, and the commenter has write access. The trigger must be @claude as a whole word; @claude-bot or /claude won’t match unless you change trigger_phrase.

Does the Claude Code GitHub Action trigger my CI?

The Claude Code GitHub Action triggers CI on its commits when it authenticates as the Claude GitHub App, which it does by default. If you pass github_token: ${{ secrets.GITHUB_TOKEN }}, GitHub doesn’t start workflows for those pushes; remove it or use a custom app token.

What is the difference between @claude and GitHub Copilot coding agent?

The Claude Code GitHub Action runs Claude Code on your own GitHub Actions runner when someone writes @claude, and you pay for runner minutes plus Claude usage. GitHub Copilot coding agent, now called Copilot cloud agent, is built into GitHub: you assign it an issue or mention @copilot, and it works in GitHub Actions or a cloud sandbox under a paid Copilot plan.

Start with your first PR.

Free plan. No credit card required.

Get started free