Getting Claude Code GitHub actions right the first time

On this page#

• What the integration actually does
• The wiring
• The two things that break it
• Verifying it works
• Team considerations
• FAQ

What the integration actually does#

Claude Code GitHub Actions turns selected GitHub events into bounded agent runs inside a workflow. It does not give an autonomous developer permanent access to your repository. GitHub decides when the workflow starts, the workflow defines its permissions, and Claude Code operates within that invocation’s checked-out code and available credentials.

Claude Code is an agentic coding tool: it can inspect a codebase, reason about changes, edit files, and run permitted commands. The GitHub integration places those capabilities behind repository events such as an issue comment or pull-request review comment.

The practical model is:

| What people assume | What actually happens | |---|---| | Claude continuously watches the repository | GitHub starts a fresh workflow for a configured event | | Mentioning @claude grants repository access | The workflow’s permissions block grants access | | The agent automatically knows team conventions | It sees only the repository context and instructions available to the run | | A successful workflow means the change is correct | It means the workflow completed, not that repository invariants held | | The action replaces CI | CI remains the acceptance authority |

That last distinction matters most. A Claude Code GitHub action can propose or implement work, but your compiler, tests, linters, security checks, and review rules must still decide whether the result is acceptable.

Use the integration for bounded repository work: explaining failures, preparing a patch, addressing review feedback, or making changes that existing checks can evaluate. Do not use it as an excuse to weaken branch protection or bypass required review. The official Claude Code documentation explains the product mechanics; your repository still owns the definition of correctness.

Photo by cottonbro studio on Pexels.

The wiring#

The reliable setup has four parts: a narrow trigger, explicit permissions, a pinned execution environment, and an API credential stored as a GitHub secret. Start read-only, prove the event path, then grant write access only if the workflow must push changes or update pull requests.

1. Add an Anthropic API key as a GitHub Actions secret named ANTHROPIC_API_KEY.

2. Create .github/workflows/claude.yml with a comment-driven trigger:

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: read
      issues: write
      pull-requests: write

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

This is the minimum useful shape, not a universal policy. permissions is GitHub’s per-workflow capability boundary. Keep contents: read while validating comment handling; change it to write only when the intended task requires repository writes.

3. Add repository-specific instructions before broadening access. At minimum, state:

• Which validation commands are authoritative.
• Which directories are generated or off-limits.
• Whether schema, dependency, or infrastructure changes require human approval.
• What the agent must do when a required tool or credential is unavailable.
• Whether it may modify the current branch or must prepare a separate change.

A generic “fix this” prompt is weak engineering. The agent needs the same invariants a second developer would need. PairFoundry’s Agent Operating Kit is the relevant next step when those operating rules are currently scattered across tribal knowledge, issue templates, and reviewer comments.

4. Keep normal CI separate:

permissions:
  contents: read

Your test workflow should not inherit the agent workflow’s write permissions. Claude can run repository checks during its task, but required GitHub checks should run independently on the resulting commit. That separation prevents an agent’s own report from becoming evidence that its patch is valid.

For the underlying Claude Code behavior and supported setup paths, use the official overview. If your team is still learning how to specify bounded agent work, start with PairFoundry’s free foundations track before enabling write access.

The two things that break it#

Two failures account for most “the workflow ran but Claude did nothing” reports: the credential is unavailable, or GitHub denied the requested operation. Treat them as different layers. Authentication determines whether Claude can run; workflow permissions determine what the GitHub token can do after it runs.

1. The API key is missing or unavailable#

The run fails during authentication, or the action reports that the Anthropic credential is missing. The common mistake is assuming a repository secret is automatically available to every event.

Check these items in order:

1. The secret is named exactly ANTHROPIC_API_KEY.
2. The workflow references ${{ secrets.ANTHROPIC_API_KEY }}.
3. The secret exists in the repository or an authorized organization environment.
4. The triggering event is allowed to receive that secret.
5. The job is not waiting for environment approval.

Fork-originated pull requests deserve special caution: secrets are deliberately restricted in untrusted contexts. Do not “fix” that by exposing a production API key to arbitrary fork code. Use trusted comment-triggered workflows with strict actor and permission rules, or require a maintainer-controlled path.

The Claude Code documentation is the authority for supported authentication configuration. The safe rollback is simple: disable the workflow or return it to read-only while correcting secret scope.

2. The GitHub token lacks permission#

The characteristic failure is Resource not accessible by integration, an HTTP authorization failure, or a run that can analyze code but cannot post, update, or push. Adding the API key will not solve this; the blocked credential is GitHub’s workflow token.

Map the intended operation to the smallest permission:

permissions:
  contents: write
  issues: write
  pull-requests: write

Do not paste that block blindly. If Claude only needs to answer an issue, keep contents: read. If it must commit, contents: write may be necessary. Organization policy, branch protection, and repository settings can still reject writes even when the workflow requests them.

Disabling branch protection is the wrong repair. Have the action create or update a reviewable change that passes the same controls as human work. For broader patterns around connecting agents safely, see PairFoundry’s Wiring It In collection.

Photo by panumas nikhomkhai on Pexels.

Verifying it works#

A green action is insufficient. Verification must prove five separate claims: the correct event started the job, the mention filter selected it, Claude received repository context, the requested operation stayed within permissions, and independent CI evaluated the resulting change. Anything less only proves that some YAML executed.

Use a disposable issue or pull request and request a harmless, observable task, such as identifying the file that defines a specific script and posting the path without editing anything.

Verify the run in this order:

• An unrelated comment does not start the agent job.
• A comment containing @claude does start it.
• The run checks out the expected repository and revision.
• A read-only task succeeds with contents: read.
• An attempted write fails while write permission is absent.
• After explicitly enabling the required write permission, only the intended artifact changes.
• Independent required checks run against the resulting commit.
• The audit trail identifies the triggering user, workflow run, and produced change.

Then test one failure path: temporarily reference a nonexistent secret or request an operation outside the granted permissions. Restore the valid configuration immediately afterward. You are confirming that failure is loud and diagnosable—not silently converted into a plausible-looking comment.

The official Claude Code overview describes the agent’s capabilities, but repository acceptance remains your responsibility. “Claude said the tests pass” is not equivalent to a required GitHub check passing.

Team considerations#

The second developer will struggle where the first developer relied on invisible setup: personal credentials, undocumented prompts, implicit permissions, or conventions known only from prior conversations. A team-ready integration must be reproducible from repository configuration and must fail safely when its owner is unavailable.

Document these decisions beside the workflow:

• Who owns the API account and secret rotation.
• Which actors may trigger write-capable runs.
• Which paths and change types require human handling.
• Which checks are mandatory before merge.
• How to disable the workflow without deleting its history.
• Who reviews usage and workflow-permission changes.

Require review for .github/workflows/** and agent instruction files. A pull request that changes the action’s permissions is changing an access-control boundary, even if the diff is only one line.

Also make the escape hatch explicit: disable the workflow, revoke or rotate the secret, and continue through the normal development process. No repository should become operationally dependent on an agent being available.

If the integration exposes inconsistent team practices, fix the operating model rather than adding more prompt text. PairFoundry’s packs overview separates the available structured options; the goal is a repeatable handoff, not a heroic configuration only its author understands.

Photo by Christina Morillo on Pexels.

Related reading#

• Claude Code Neovim, including the failure mode nobody documents
• Cursor VS Code: the wiring, and the two things that break it

FAQ#

When should we not use Claude Code GitHub Actions?#

Do not use it for changes whose correctness cannot be independently checked, production operations requiring broad credentials, or repositories without enforceable review and CI boundaries. If the only safety mechanism is “the prompt tells Claude to be careful,” the repository is not ready for write-capable agent automation.

How is this different from simply running Claude Code locally?#

Local Claude Code acts with a developer’s local context and permissions. A GitHub action runs from repository events inside a controlled workflow, using declared permissions and stored credentials. The action is easier to audit and standardize, but it has less implicit context and must be configured accordingly.

How do we roll back when the action starts making bad changes?#

Disable the workflow first, then revoke or rotate its API secret if credential exposure is possible. Revert produced commits through the repository’s normal process. Preserve workflow logs for diagnosis; deleting the workflow file alone does not undo changes it already created.

Should every developer be allowed to trigger write-capable runs?#

No. Start with trusted maintainers and read-only behavior. Expand trigger access only after actor checks, permissions, branch protection, required CI, and ownership are explicit. Comment access and repository write authority are separate decisions.

Can this replace pull-request review?#

No. A Claude Code GitHub action can prepare changes and respond to feedback, but it cannot own your repository’s risk decisions. Keep human review where judgment is required, and keep independent checks as the mechanical acceptance gate.