A practical guide to the Claude Code GitHub integration

Start by choosing the GitHub integration that fits the job

“Claude Code GitHub integration” is a label for more than one setup. Picking the wrong one creates a confusing security review and a workflow nobody owns.

In the current Action v1, a workflow uses anthropics/claude-code-action@v1; it can respond to @claude comments or run immediately when the workflow supplies a prompt. It consumes GitHub Actions capacity plus the configured provider's usage; an OAuth token uses the linked Claude subscription instead of direct API billing. Keep its trigger narrow and review its permissions before enabling it.

Set up the GitHub Action

Repository admin access is required. With the GitHub CLI installed and authenticated, open Claude Code in the chosen repository and run /install-github-app. The guided setup installs the App, configures an authentication secret, and prepares workflow files on a branch. Review and merge the resulting workflow PR before testing an @claude mention. The setup itself changes repository configuration; it is not a diagnostic command.

For manual setup, install the App only for the required repositories, store the credential in Actions secrets, and adapt the official workflow example. An API key uses the anthropic_api_key input with ANTHROPIC_API_KEY; a supported subscription token uses claude_code_oauth_token with CLAUDE_CODE_OAUTH_TOKEN. Do not paste either credential into the workflow file. Cloud-provider and workload-federation routes have separate documented setup.

Two checks normally restrict who starts a run: the triggering user needs repository write access on issue/PR events, and bot actors are rejected unless explicitly allowed. A scheduled event skips the user write-access check but still has the bot check. Do not widen those exceptions without reviewing the trust boundary. The official App also requests permissions for other Claude features, so inspect its full installation permissions rather than treating a short workflow permission list as the whole grant.

Keep concise coding standards and test commands in the repository's CLAUDE.md. They help Claude follow the project, but are instructions, not a security boundary. Check both the workflow log and any posted review: a run with a prompt does not automatically post its findings as a PR comment.

Routines are a different model. They are currently a research preview and run as autonomous cloud sessions. A saved routine has a prompt, one or more repositories, an environment, connectors, and one or more triggers. It can be useful for a focused PR review or a documentation-drift check after a release, but it cannot stop mid-run to ask somebody whether it may use a connector or write a file. That is why configuration matters more than a sentence in the prompt.

Configure a GitHub-triggered routine with a small blast radius

For a cloud routine, create and edit the GitHub trigger at claude.ai/code/routines. Claude Code v2.1.225 or later can also attach GitHub triggers through the CLI after the App is installed. API-trigger token creation remains a web operation. The routine documentation calls out an easy-to-miss distinction: /web-setup grants repository access for cloning; it does not install the Claude GitHub App or turn on webhook delivery. Web trigger setup prompts you to install that App for the repository you selected.

GitHub triggers currently support pull-request and release event categories. A matching event starts a fresh session. There is no session reuse, so two PR updates can yield two separate investigations. For PRs, filters can restrict the author, title, body, base or head branch, labels, draft status, and merged state. Prefer a condition a maintainer controls, such as a needs-claude-review label and a protected base branch, over every pull request in an organization.

Set the routine’s access deliberately:

• Add only the repository it must read. A routine clones each selected repository at the start of every run.
• Use a new claude/ branch for proposed changes. Current routine rules also check requested pushes to other branches, rejecting protected branches, another person's open-PR branch, or a branch with another author's commits. Maintain GitHub branch protections instead of assuming the prefix is the only safeguard.
• Use a cloud environment with the minimum network access and only the variables needed for this job. A secret available in the environment is available to the autonomous session.
• Remove connectors the routine does not need. Connected MCP connectors are included by default, and a routine can use every included tool, including write tools, without a permission prompt.

This is more concrete than asking the routine to “only review.” Repository scope, branch permission, environment configuration, connector selection, GitHub protection rules, and code review are the controls. The prompt explains the desired work; it does not enforce it.

A GitHub issue can be the evidence handoff, not the customer answer

Here is a narrow example that connects engineering work to support without pretending that GitHub is a help desk. A support lead receives several reports that a CSV audit export contains a duplicate row after an import is retried. They open a GitHub issue with:

• the visible symptom and product area;
• a sanitized, fictional reproduction sequence, not a customer export or credentials;
• the expected behavior: retrying the same import must not add the same audit entry twice;
• the uncertainty: no claim that customer data was changed, lost, or repaired;
• the requested evidence: identify the deduplication key, add a regression test, and show the focused test output.

That issue gives Claude Code a useful investigation boundary. A maintainer can invoke a repository Action through its chosen, documented event flow, or trigger a routine only after applying its maintainer-controlled label. The task should say to inspect the existing import and audit paths, propose the smallest change, add a test for a repeated import, and open a claude/ branch or draft PR for review. It should also say what it must not do: change production data, merge, deploy, contact a customer, or announce a fix.

The reviewer then checks the part a code agent cannot decide: does the diff use the active import path, does the test recreate the original duplicate-row condition, and does the changed behavior preserve distinct audit events? Three useful checks are:

1. A fictional import creates its expected audit entry once.
2. Retrying the same import does not create a second identical entry.
3. A different import still creates its own entry rather than being suppressed as a duplicate.

Run the relevant test and inspect the diff. A green check is evidence about the test, not proof that every customer export is repaired. The accountable owner decides whether to merge and deploy, then observes the release through the team’s normal process.

Keep GitHub identities, secrets, and approvals separate

Claude Code working in GitHub does not inherit a safe default just because it has a good prompt. In a GitHub Action, start with the workflow event and the token’s permissions. Give it only the repository permissions needed for the intended comment, issue, or pull request behavior. Store the model credential in GitHub Secrets rather than in the prompt or repository. Pin the action version as your organization requires, set a timeout, and use concurrency controls where duplicate jobs would be harmful.

For a routine, the GitHub identity and included connectors act as you. Its commits and pull requests use your connected GitHub identity; Slack, Linear, or other connector actions use the linked account for that service. That makes an unattended routine a reason to reduce scope, not a reason to assume it is harmless. Review the run session, its branch, and its proposed PR before accepting the change.

Be especially careful with comment-triggered workflows. The Claude Code web documentation notes that replies made on your behalf can trigger other comment-driven systems such as custom GitHub Actions. Avoid a loop in which one automation’s comment silently starts another privileged automation. Restrict who can trigger the workflow, require a maintainer label or approval, and test the event chain in a non-production repository first.

Use eesel CLI to test the support wording after the code review

An engineering or support owner can use eesel CLI from a terminal, script, or coding agent such as Claude Code, Codex, or Cursor to bring the reviewed finding into the same support workspace used in the dashboard. The issue, PR, tests, and release decision tell that owner which explanation can be approved. Merging a PR does not itself update a teammate's instructions or send a reply.

The eesel CLI is an agent-friendly way to operate the same workspace and helpdesk teammate visible in the dashboard. It returns JSON, and a person, script, or coding agent can use it. With npx, it requires Node.js 18.17 or newer. login opens a browser and authenticates, so it is not a read-only preflight.

The owner first chooses a non-production teammate and keeps consequential actions Disabled in its Actions settings. Disabled is the enforcement boundary; a chat prompt that says “do not send” is not. Then inspect the target before spending money on a chat test:

npx @eesel/cli login
npx @eesel/cli whoami
npx @eesel/cli agents
SUPPORT_REVIEW_AGENT="REPLACE_WITH_OWNER_APPROVED_NONPRODUCTION_AGENT"
npx @eesel/cli status --agent "$SUPPORT_REVIEW_AGENT"
npx @eesel/cli instructions --agent "$SUPPORT_REVIEW_AGENT"
npx @eesel/cli integrations --agent "$SUPPORT_REVIEW_AGENT"
npx @eesel/cli billing --agent "$SUPPORT_REVIEW_AGENT"

Check whoami before continuing, and replace the placeholder with the actual approved teammate. Explicit --agent selects that teammate rather than a remembered default. For unattended runs, EESEL_API_URL and EESEL_API_TOKEN override stored login credentials; verify those point to the intended workspace too. Observing setup is free; the owner must approve chat spend before testing. Held actions can be inspected with npx @eesel/cli approvals --agent "$SUPPORT_REVIEW_AGENT"; listing them does not approve them.

Now test only the wording that the support owner approved. This fictional case deliberately contains no customer records, export files, or lookup tool:

npx @eesel/cli new --name "Audit-export duplicate-row guidance" --agent "$SUPPORT_REVIEW_AGENT"
npx @eesel/cli chat "Fictional approved guidance: We are investigating reports of duplicate rows in audit exports after an import retry. Do not say a customer’s export is corrected, that data was lost, or that any record was checked. Ask for the export time and import reference, then direct the user to the authorized support team. No account data or lookup tool is available in this test. Draft a reply only; do not send or change anything. Customer question: My export repeats a row after I retried an import. Is my data damaged?" --agent "$SUPPORT_REVIEW_AGENT"
npx @eesel/cli activity --agent "$SUPPORT_REVIEW_AGENT"
npx @eesel/cli approvals --agent "$SUPPORT_REVIEW_AGENT"

Use separate fresh conversations for three cases: a duplicate-row report, a report of a missing row, and a request to delete an audit record. Repeat the same full approved guidance in each conversation, followed by that case's customer question. The first may use the investigation wording; the second must not force the duplicate-row explanation; the third should recommend the authorized support route, not perform a transfer or promise deletion. Inspect each actual reply, activity, and held approvals before continuing. These are proposed tests, not reported results. Supplying the note tests response behavior; it does not show the teammate retrieved a saved source, verified the PR, or inspected an export.

When an owner wants to make a real configuration change later, inspect the supported write command with --help and use --dry-run where supported. A dry run previews an eligible write; it does not prove reply quality. Review the exact request, have the owner approve the live change, read the resulting state back, and rerun the cases. That sequence keeps a useful GitHub finding connected to support work without making code automation the boss of customer operations.

The dashboard is the same support workspace the eesel CLI targets; it is an illustration, not evidence that the fictional test ran.

Use eesel CLI when reviewed GitHub findings need a support-safe handoff

GitHub is excellent for issues, diffs, tests, and code review. eesel’s helpdesk teammate is where a support owner can connect approved knowledge, evaluate replies, and control customer-facing actions. Use the eesel CLI to inspect the exact teammate from a terminal or coding agent, target a non-production evaluation, and make the support handoff reviewable before any live change.

Try eesel to evaluate that support workflow with your own approved guidance.