Hands Off Development

Wiring GitHub Issues to Claude Code Without Writing Infrastructure Glue Code

Set up a GitHub-native Claude Code runner that turns issues into reviewable pull requests.

· 9 min read
Cover illustration for “Wiring GitHub Issues to Claude Code Without Writing Infrastructure Glue Code”
Cloud Agent Environments · November 20, 2026 · 9 min read · 1,936 words

GitHub Actions and anthropics/claude-code-action can turn a GitHub Issue into a Claude Code session that opens a reviewable pull request without custom infrastructure. For teams that want a bring-your-own API key cloud coding agent runner, this GitHub-native path keeps the workflow separate from inference, which can use the Claude API directly or a cloud provider through OIDC. The essential design is durable GitHub state, disposable agent sessions, and a merge gate outside the agent’s control.

Why GitHub Issues, left unconnected, force a manual loop that agents can't escape

An issue records work, but it does not start an agent. Without a trigger mechanism, a developer must launch Claude Code, copy in the issue context, and manage the handoff to a pull request. Every session begins with a fresh context window. Someone must therefore recover any decision left only in the last conversation.

A capable agent remains disconnected from the place where tasks originate, and its work depends on someone being at the keyboard. That dependency also obstructs parallel, scheduled, and event-driven execution. What does the loop look like when GitHub itself is the trigger?

The mental model that makes the rest of the setup make sense

GitHub is the system of record. The Claude Code session is ephemeral working memory. Durable state has three distinct homes, which are CLAUDE.md and repository documentation for codebase knowledge, GitHub Issues for the task and its rationale, and pull requests and commits for completed work. The conversation context disappears when the session ends, so it cannot serve as a reliable handoff between runs.

Each durable home serves a different retrieval purpose. CLAUDE.md supplies conventions that are automatically injected into each session, while gh issue view N loads the relevant task on demand. Pull requests and commits preserve the implementation and link it back to the issue. A new session can therefore reconstruct its assignment without recovering an earlier conversation. The workflow configuration is built around that reconstruction.

The practical discipline is to write decisions into the issue thread and have the agent reread it at the start of each session. This includes both the task’s original description and changes to it. Otherwise, the next run may get the first request without the reasons for the changes that later narrowed it.

The three things required before any workflow file runs

The setup requires a GitHub App with the appropriate permissions, stored credentials, and an authenticated GitHub CLI. These serve different purposes and are not interchangeable. The app supplies the GitHub identity and access needed for the work, while credential storage keeps long-lived secrets out of workflow YAML. Teams seeking a narrower permission footprint can register a custom GitHub App with webhooks disabled and the required permission set.

The App ID and the downloaded .pem private key must be kept in repository secrets. Their presence does not replace GitHub CLI authentication. Without authenticated CLI access, Claude can fall back to unauthenticated GitHub API requests, whose much lower rate limit can interrupt a substantial task midway through execution. Authentication must work for the tools the agent uses as well as for the first connection.

Repository authorization is a separate diagnostic boundary. GitHub issue #110901, filed Nov 18, 2026, reports that new cloud sessions get a 403 on push even though the GitHub App is installed and repository status shows as OK. The reported cause was that the repository was not in the session’s authorized repository set. If push fails unexpectedly after installation, the session’s repository authorization is therefore worth checking rather than treating the installation status as conclusive.

How the claude-code-action step converts a GitHub event into an agent session

GitHub Actions receives the event and starts the workflow. The anthropics/claude-code-action step then interprets the event and starts the agent session. The v1 action can start from a comment that mentions @claude, an issue assignment through assignee_trigger, or an issue label through label_trigger. Assignment has no default and must be configured, while the default label is claude. Assignment and label triggers apply only to issues.

The official Claude Code GitHub Actions documentation has a job condition that checks whether a comment contains @claude, so runners stay off for comments that do not mention it. This is user-written configuration, even though it requires no custom service. The distinction is important to the infrastructure claim. GitHub handles the events and runs the work, but the workflow still says which events should start a run.

Human gestures use interactive behavior, with the agent reading event context and responding without a prompt in the YAML. Supplying a prompt instead enables automation behavior on the event that fires the workflow. Output then goes to the workflow log by default. Posting a review or other response to a pull request requires an instruction in that prompt, rather than an assumption that every automated run publishes a comment.

The action also rejects actors whose GitHub account type is Bot unless they appear in allowed_bots. That guard prevents self-generated comment loops. For an implementation task, the agent explores the repository, plans the change, implements it, and commits, checking tests, build, and lint as it proceeds. It then opens a pull request with Closes #N linking the work to its originating issue. Entry is through GitHub primitives, and merge authority remains outside the session.

Routing inference through a cloud provider instead of the Claude API directly

Teams with Claude access through AWS Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry can route inference through that account. This path uses OIDC, eliminating the need for a stored long-lived cloud credential. The workflow presents a short-lived GitHub OIDC token to a cloud identity configuration that trusts the specific repository. GitHub App credentials and cloud inference credentials remain separate concerns.

The action-side selection is a single input. Bedrock uses use_bedrock set to "true", Google Cloud uses use_vertex set to "true", and Foundry uses use_foundry set to "true". That small switch depends on cloud-side setup. It does not create the trust relationship or grant model access on its own.

For Bedrock, the setup uses an IAM role trusted through a GitHub OIDC provider, with scoped model invocation, inference-profile, and Marketplace subscription permissions. Cross-region inference profiles need access in every region in their region group. Google Cloud uses a Workload Identity Pool and a service account with the Vertex AI User role, while Foundry uses a federated identity credential and the Foundry User role. Repository-scoped trust is central to each path. The cloud-providers page in the documentation provides complete workflow examples, including the provider-specific input and the identifiers stored as secrets.

The four workflow patterns and when each one fits

The interactive comment pattern starts when a developer mentions @claude on an issue or pull request. Claude reads the thread and examines the codebase, then returns findings or opens a pull request. The human directs the task. This fits work where a person needs to say what to do instead of leaving it to a standing automation rule, including a question that may need analysis but no code change.

Automated pull request review starts on an opened or updated pull request and uses a supplied prompt. The prompt must ask for a structured review comment so that it is ready before human review. Review scope can be specialized. Parallel security and performance reviewers can examine different concerns, with the security reviewer focusing on authentication, authorization, and injection issues. Findings can use the severity ratings CRITICAL, HIGH, MEDIUM, and LOW.

CI failure auto-fix uses a workflow_run trigger and an automation prompt to respond to a failed test suite. With bash access, Claude diagnoses the failure, patches the code, creates a fix branch, and opens a pull request. This pattern needs an additional identity constraint. GITHUB_TOKEN is insufficient because commits made with it do not trigger CI workflows, so the workflow requires the GitHub App or a custom app. It also needs an auto-fix branch exclusion to prevent a failed repair from repeatedly requesting another repair.

For structured JSON output, a workflow-selected event launches an automation prompt that asks the agent for a JSON payload. A downstream step or system consumes that payload for routing or gating decisions. The trigger belongs to the surrounding workflow, while the agent’s output becomes an input to the next stage.

How do you run Claude Code in the cloud without managing your own infrastructure?

When the loop runs in isolated cloud VMs, the work runs off developer laptops. Sessions can work across many issues in parallel, and credentials need not touch a developer’s local machine. Each session reconstructs its context from durable GitHub records. That removes a session-state dependency between simultaneous runs. It does not make an incomplete task description more complete, so the durable-state discipline remains necessary.

GitHub Actions also supplies execution triggers that do not require an active developer. workflow_run can respond to CI failures, schedule can start recurring work, and webhooks can provide external signals. The agent becomes part of a workflow.

The relevant selection criteria are execution isolation, inference authentication, and the system where work originates. Isolated cloud execution addresses where the session runs, while direct API access or provider OIDC addresses how inference is authorized. For GitHub-native work, Actions links task events to the runs they start without a separate orchestration service.

The gap the GitHub-native loop does not close: Linear and other issue trackers

This GitHub-native connection does not extend to an external issue tracker on its own. The Linear integration feature request filed in December 2025 is still open and describes how developers start Claude Code sessions by hand, copy in issue context, and manage the workflow. Its proposed integration would make Claude Code an assignable Linear agent. Assigning an issue or mentioning @claude would start a cloud session with issue context, post progress in Linear comments, and create a pull request on completion.

The request describes a desired capability. It signals demand without establishing a delivery commitment. The unofficial linear-claude-bridge provides a community workaround by registering an OAuth app as a Linear agent and receiving AgentSessionEvent webhooks. It runs sessions through the Claude Agent SDK, with cwd pointed at a local directory so CLAUDE.md and MCP servers load automatically. Follow-up prompts resume the same SDK session.

That bridge restores the task-to-agent connection, but it changes the execution model. Sessions run on the delegating person’s machine and account. It therefore does not supply the cloud isolation or parallelism described for the GitHub Actions path.

Practical decisions that determine whether the loop holds up past the first PR

The issue thread must remain the task record, CLAUDE.md the source of repository conventions, and the session a temporary workspace. For production use, the lesson is to put architectural decisions, task specifications, and acceptance criteria in those durable records. A successful first pull request does not test whether the next session can recover the reasoning behind it.

Authentication and recursion guards need the same operational attention. GitHub CLI authentication supports sustained repository work, while app identity lets auto-fix commits participate in CI. Neither substitutes for a branch guard. Before an auto-fix workflow runs, it must exclude branches whose names start with the auto-fix prefix, and its instructions must keep the agent from working on those branches. The bot-actor filter addresses comment loops.

The final boundary is the merge gate. The agent produces a proposed change with a record of the work, and that change enters the codebase only after it passes CI gates and receives human approval. This division makes the loop auditable and reversible without granting the session authority over its own acceptance. GitHub supplies the plumbing, but the agent opens the pull request and does not merge it.

Sources

  1. [GitHub integration] · Issue #110901 · anthropics/claude-code · GitHub
  2. Linear Integration: Assign issues to Claude Code to trigger cloud agent sessions · Issue #12925 · anthropics/claude-code · GitHub

More in Cloud Agent Environments