GitHub Integration Best Practices

Q: Should every workflow that runs Claude Code have a timeout set?

Yes - a timeout-minutes setting is cheap insurance against a hung headless invocation consuming runner minutes indefinitely.

Proven patterns for using Claude Code safely and effectively across pull requests and CI pipelines, from opening a PR by hand to running a fully automated review bot.

How to Use This List

Treat the "A" rules as non-negotiable defaults for any Claude Code and GitHub integration; treat later groups as tuning once the basics are in place.
Apply the CI-specific rules (C and D) only once you've moved from interactive session usage into an automated GitHub Actions job.
Revisit this list whenever you add a new workflow that runs Claude Code, since secrets and permission scoping mistakes are easy to repeat across files.
Pair this with Setting Up a GitHub Actions Job That Runs Claude Code for the step-by-step build checklist.

A - Working with the gh CLI

Authenticate gh once per environment and verify it before relying on it. Run gh auth status after gh auth login, and re-check it whenever a session's GitHub commands unexpectedly fail.
Let Claude Code run the same gh and git commands you'd type yourself. There's no separate "Claude Code GitHub feature" to learn - understanding the underlying gh pr create, gh pr view, and gh pr comment commands makes it easy to verify what a session actually did.
Confirm the current branch before committing or opening a PR. A quick git status or git branch --show-current avoids committing changes to the wrong branch, especially after checking out a PR for follow-up work.
Write PR bodies with a clear Summary and Test plan. A structured body (as shown in this section's PR-creation article) is easier for a human reviewer to skim than an unstructured paragraph.

B - Opening PRs and Responding to Comments

Reference the issue a PR closes. Include Fixes #<number> or Refs #<number> in the PR body so GitHub links and auto-closes the issue on merge.
Fetch line-level review comments with gh api, not just gh pr view --comments. The API endpoint returns the file and line each comment refers to, which top-level view output doesn't always surface clearly.
Re-run tests before pushing a follow-up commit, not just after. A fix that satisfies one review comment can still break something else; confirm the suite passes before committing the follow-up.
Write follow-up commit messages that describe what changed, not just "address feedback." A specific message like "Validate rate limit window bounds per review comment" is far more useful when skimming history later.
Confirm the push actually landed before requesting another look. Check gh pr view --json commits rather than assuming a push succeeded before pinging reviewers again.

C - Running Claude Code Headlessly

Test a headless invocation locally before wiring it into CI. Run the same claude -p "..." command from a terminal first to validate the prompt and output format before putting it in a GitHub Actions workflow.
Configure permissions and tool access before the run starts, never mid-run. Headless mode has no person present to approve a tool call interactively, so an unconfigured allowlist causes the run to fail or stall.
Choose an output format that matches the consumer. Plain text for a human-readable PR comment, structured JSON when a later CI step needs to parse specific fields programmatically.
Write headless prompts with enough context to avoid ambiguity. There's no follow-up question available mid-run, so the prompt needs to carry the constraints and context a person would normally supply interactively.

D - Securing the CI Job

Store the Anthropic API key as a GitHub Actions secret, never as a plain workflow variable. Anything not stored under repository or organization secrets is visible in logs and to anyone with read access to the workflow file.
Scope the workflow's permissions block explicitly. Grant only what the job needs - typically contents: read and pull-requests: write for a review job - rather than relying on broader default token permissions.
Use pull_request, not pull_request_target, unless you specifically need and understand the trade-off. pull_request_target can expose repository secrets to code from a forked PR if not handled carefully.
Set a timeout on any job running Claude Code headlessly. A timeout-minutes setting at the job level prevents a hung invocation from tying up runner minutes indefinitely.

E - Keeping Automated Review Useful

Give the review job explicit priorities instead of a bare "review this PR" prompt. Naming specific signals - missing tests, style drift, common defect patterns - produces sharper, more actionable findings than a generic instruction.
Instruct the review to stay quiet on clean diffs. Without that explicit instruction, an automated review tends toward finding something to say on every PR, which trains reviewers to ignore its comments.
Treat automated review findings as one signal, not a gate. Automated review runs alongside required human reviewers and existing branch protection rules - it doesn't replace either by default.
Revisit review guidance when it consistently misses or over-flags something. Prompt guidance is not fixed; if a category of issue keeps slipping through (or getting over-flagged), that's a signal to refine the prompt, not a permanent limitation.
Re-trigger review on every push to a PR, not just its first open. Include synchronize in the workflow's pull_request event types so later commits get reviewed too, not just the PR's initial state.

FAQs

What's the single most important best practice on this list?

Storing the Anthropic API key as a proper GitHub Actions secret and scoping the workflow's permissions explicitly - a leaked key or an overly broad token turns a convenience feature into a real security exposure.

Do interactive session best practices matter as much as CI ones?

Yes, though the risks differ - interactive usage mistakes tend to cost time (wrong branch, unclear PR body), while CI mistakes tend to cost security exposure (leaked secrets, overly broad permissions).

Why does this list separate gh CLI habits from CI security practices?

Because they apply at different points in the workflow and carry different risks - a gh habit mistake wastes a few minutes, while a CI security mistake can expose credentials to every future run of the job.

Is pull_request_target ever the right choice?

Occasionally, when a job genuinely needs secret access even for forked-PR runs, but only with a clear understanding of the trust boundary being crossed - pull_request is the safer default absent that specific need.

How often should automated review guidance be revisited?

Whenever it consistently misses or over-flags a category of issue - treat the prompt as living guidance that improves with feedback, not a one-time setup task.

What's a common sign that a review bot has become noisy?

Reviewers start skimming past or ignoring its comments entirely, usually because it comments on every PR regardless of whether the diff is actually clean - the fix is adding an explicit "stay quiet when clean" instruction.

Should every workflow that runs Claude Code have a timeout set?

Yes - a timeout-minutes setting is cheap insurance against a hung headless invocation consuming runner minutes indefinitely.

Does automated review replace the need for required human reviewers?

No - it's designed to run alongside a team's existing review process and branch protection rules, adding a fast first-pass signal rather than replacing the human gate.

What's the risk of granting a workflow contents: write when it only reads code?

It widens the blast radius unnecessarily - if the job or its dependencies were ever compromised, a write-scoped token can do more damage than a read-scoped one that can't modify the repository.

Is testing a headless invocation locally really necessary before putting it in CI?

Yes - it's the fastest way to validate the prompt wording and output format, since debugging a misbehaving prompt is much slower once it's wrapped inside a full GitHub Actions run.

How Claude Code Fits Into Your GitHub Pull Request Workflow - the overall picture these practices sit inside.
Setting Up a GitHub Actions Job That Runs Claude Code - the step-by-step build checklist these practices harden.
Running Claude Code as an Automated Code Review Bot in CI - a full workflow implementing the CI-focused practices here.
How Claude Code Decides What to Flag in an Automated Review - the reasoning behind the review-guidance practices in group E.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.