skip to content

What does the Claude Code GitHub Action do, and what does /install-github-app set up in a repository?

level: juniorimportance: should knowfreq 30%

answer

  1. an agent inside your own workflows
  2. one command from a local session
  3. app, secret, workflow pull request
  4. ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN
  5. github.com only, admin access needed

basics

~20 s

anthropics/claude-code-action@v1 runs Claude Code inside a repository's GitHub Actions workflows, answering @claude mentions or running a set prompt. /install-github-app installs the Claude GitHub App, saves an auth secret and opens a pull request adding the workflow.

solid answer

~40 s

The Claude Code GitHub Action, `anthropics/claude-code-action@v1`, runs Claude Code on a GitHub Actions runner, so someone can comment `@claude fix the TypeError in the dashboard` on an issue or PR and Claude reads the code, pushes commits or opens a PR, and replies in a comment. Quick setup is `/install-github-app`, run from a local `claude` session in the repository: it needs admin access, a github.com remote and the GitHub CLI signed in with `gh auth login`. It installs the Claude GitHub App, saves a repository secret (`ANTHROPIC_API_KEY` for an API key, `CLAUDE_CODE_OAUTH_TOKEN` for a subscription token), then pushes a branch with the selected workflow files and opens a pull request you create and merge. Manual setup does the same three steps by hand.

go deeper

for a junior

Recall the action's name and its two jobs, answering @claude and running a set prompt, and the three things /install-github-app does: app, secret, workflow pull request.

for a middle

Explain which secret maps to which input, what claude setup-token produces, and what Esc or Skip for now leave behind in the repository.

for a senior

Show you would choose the credential for an organization, an API key or federation rather than one person's OAuth token, and know that deleting a secret does not revoke the key.

for a principal

Weigh the shared app's broad permission set against a custom app for the action alone, knowing the custom app gives up Code Review and auto-fix.

## What the action is **Claude Code GitHub Actions** is a published GitHub Action, `anthropics/claude-code-action@v1`, that runs **Claude Code** (Anthropic's terminal coding agent) as one step of a workflow in your own repository. Because it is a workflow step, it runs on a **GitHub Actions runner** and consumes your Actions minutes, plus API tokens or subscription usage for the model calls. Typical uses: - answering a comment such as `@claude implement this feature based on the issue description` by writing the change and opening a pull request; - fixing a bug named in a PR comment and pushing a commit to that branch; - running a fixed prompt on an event, such as a pull request opening or a nightly `schedule`, without anyone mentioning Claude. It is one of several products that share the name. **Code Review** is a managed service that reviews pull requests without any workflow file; cloud sessions run Claude Code on Anthropic's infrastructure; the **Agent SDK** is the library the action itself is built on. ## Quick setup with /install-github-app `/install-github-app` is a command you type inside an interactive Claude Code session opened in the repository you want to connect. It works only for **github.com** repositories: when the git remote is on gitlab.com or bitbucket.org, it prints a notice and exits instead of starting setup. Before running it, install the GitHub CLI and sign in with `gh auth login`; you also need **admin access** to the repository. The command then walks through three steps: 1. **Install the Claude GitHub App** on the repository. After this step it asks whether to continue; **Skip for now** stops with only the app installed. 2. **Save an authentication secret.** If Claude Code already has an API key it reuses it; otherwise you choose between creating a long-lived token with your Claude subscription and pasting an API key. The secret is named `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`. 3. **Prepare the workflow.** It pushes a branch with the workflow files you selected (a `claude.yml` for mentions and, optionally, a review workflow), already wired to that secret, and opens GitHub in your browser with a pull request ready to create. Once you merge it, `@claude` works. Pressing Esc stops setup: a step already running finishes, no later step starts, and the closing message lists what already happened, such as a pushed branch or a saved secret. Running the command again on a repository that already has `claude.yml` offers to update the workflow files to the latest version. ## Manual setup and the credential inputs Manual setup is the same three pieces done by hand: install the app from its GitHub page, add the secret in the repository settings, and copy the example `claude.yml` into `.github/workflows/`. Each secret is passed to a matching `with:` input of the action: | Credential | Repository secret | Action input | Where it comes from | | - | - | - | - | | Claude API key | `ANTHROPIC_API_KEY` | `anthropic_api_key` | the Claude Console | | Subscription OAuth token | `CLAUDE_CODE_OAUTH_TOKEN` | `claude_code_oauth_token` | `claude setup-token`, on Pro, Max, Team and Enterprise | An OAuth token is tied to the subscription of the person who ran `claude setup-token`, so for a secret shared across an organization the docs recommend a Console API key, or **workload identity federation**, where the action exchanges the workflow's OIDC token for API access and no long-lived secret is stored. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry are selected with `use_bedrock`, `use_vertex` or `use_foundry` instead. ## The app's permissions The Claude GitHub App is shared by every Claude feature that integrates with GitHub, including the action, Code Review and auto-fix in cloud sessions. The action relies on three of its permissions, **Contents**, **Issues** and **Pull requests**, each read and write, but installing the app grants its whole set, including write access to Actions, Checks and Workflows. GitHub does not let you accept a subset. An organization that wants only the three can create a **custom GitHub App** for the action; Code Review and web auto-fix still need the official app. ## Removing it Uninstalling is also piecewise: - delete the workflow files that use `anthropics/claude-code-action`, which stops it running; - delete the secret, remembering that **the credential stays valid** until you also delete the key in the Claude Console; - uninstall the GitHub App only if no other Claude feature, such as Code Review, still needs it. Never commit a key into a workflow file; reference it as a secret, for example `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}`.

  • Why do the docs prefer a Claude Console API key over CLAUDE_CODE_OAUTH_TOKEN for a secret shared across an organization's repositories?
    An OAuth token from `claude setup-token` is tied to the subscription of the person who generated it, so every repository's runs would bill and break with that one person. A Console API key belongs to the organization. To store no long-lived secret at all, use workload identity federation: the action trades the workflow's OIDC token for API access through a Console service account, set with inputs such as `anthropic_federation_rule_id` and `anthropic_organization_id`.
  • Your security team refuses the Claude GitHub App because it asks for write access to Actions and Workflows. What can you offer?
    A custom GitHub App that holds only Contents, Issues and Pull requests, which are the three permissions the action uses, wired in with its `APP_ID` and `APP_PRIVATE_KEY` secrets. GitHub grants an app's permission set as a whole, so the official app cannot be trimmed. The custom app covers only the action: managed Code Review and web auto-fix still require the official app.
  • What happens when you run /install-github-app in a checkout whose remote is on gitlab.com?
    It prints a notice that it is GitHub-only and exits without starting setup. GitLab has no app or packaged action: you add a job to `.gitlab-ci.yml` that installs Claude Code and runs it, with the API key in a masked CI/CD variable.

  • The action runs on Anthropic's servers, not on a GitHub Actions runner
  • /install-github-app also connects GitLab and Bitbucket repositories
  • Deleting the repository secret also revokes the API key
  • Any collaborator can run setup; admin access is not needed
  • A private repository can keep the API key in the workflow file