11. From a Labeled Issue to a Pull Request Without Your Laptop
Summary
An issue that becomes a pull request
The Claude Code GitHub Action runs Claude Code inside a GitHub Actions job. A label on an issue, or an "@claude" comment from someone with write access, starts a GitHub-owned machine. Claude works on a new branch, runs the project's checks, pushes, and posts a link to a pre-filled pull request page. You open the pull request, review it, and merge or ask for changes. It is distinct from chat, from Claude Code on the web, and from code written against the API or Agent SDK. The Claude Code GitHub Actions documentation covers the action.
Installing it
The install-github-app slash command installs the GitHub App, stores a credential as a repository secret, and opens a pull request adding the workflow files. It needs a github.com repository and a signed-in gh tool. The manual route covers the same three steps: the App with read and write access to Contents, Issues and Pull requests, a secret (ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN), and the example workflow file. The setup guide walks through it.
The workflow file
The example listens for comments and runs only when they contain "@claude". For labels, the label_trigger input starts a run, and assignee_trigger does the same for assignment. The chapter assembled its label workflow from the documented inputs, so compare it with the usage page. The permissions block includes id-token write; without it, runs fail early with an OpenID Connect error. Leaving out prompt gives interactive mode, while setting it gives automation mode, where tools must be granted. Other options go through claude_args.
A database on the runner
The chapter adds a Postgres service container with a health check and a port mapping, then runs checkout, Node setup, npm ci and migrations before Claude's step. A test report is uploaded afterward even on failure. The GitHub guide to PostgreSQL service containers covers the setup.
A failed run, then a good one
In the illustrated example, a missing ports line causes "connection refused", fixed with one narrow commit. The rerun passes, and Claude comments with the pull request link. Review is against the three acceptance criteria, followed by running the app yourself. A pull request comment with "@claude" pushes fixes to the same branch.
Limits and security
Only write-access users can trigger runs. allowed_non_write_users is a significant security risk. Issue text is data, not orders, and stripping hidden instructions is not a guarantee. Claude cannot change workflow files, force push, or open pull requests itself. The documents describe no timeout or spending cap, so set GitHub's job timeout. See the security documentation.
Claude Code releases after 2.1.310
Per the changelog:
- 2.1.327: install-github-app asks for confirmation; a headless startup hang is fixed; mcp add-json can read settings from standard input.
- 2.1.326: hook "block" decisions now stop more calls, so check hooks that always print one.
- 2.1.325: self-hosted runners refuse symlinked session paths, except checkout-hook checkouts.
- 2.1.323: auto mode refuses gateway models with "haiku" in the name, except claude-haiku-5-5.
An issue that turns into a pull request on its own
The Claude Code GitHub Action runs Claude Code inside a GitHub Actions job. When an issue gets a label you choose, or when someone with write access comments "@claude", GitHub starts a machine, checks out your repository, and runs Claude Code there. Claude reads the issue, works on a new branch, runs the checks you have set up, and pushes that branch. Then it posts a link to a pull request page that is already filled in. You open the pull request yourself, read it, and merge it or ask for changes. Your laptop can be closed the whole time, because the work happens on a machine GitHub owns.
Be clear about which interface this is. It is not chat. It is not last chapter's Claude Code on the web session, which Anthropic hosts and which you start from a browser or phone. It is not code you write against the Claude API or the Agent SDK either. It is the same Claude Code program we have used all along, started by a workflow file in your repository. The action that does this is published as anthropics slash claude-code-action, and the current major version is called v1.
In the course so far we have built a working routine on the laptop, then moved single jobs off it with cloud sessions and headless runs. What we have not had is a way for the work to start by itself from the place where work is described, which is the issue tracker. This chapter adds that start.
A few GitHub Actions words come up, so here they are in plain terms. A workflow is a file of instructions that lives in your repository, in a folder called dot github slash workflows. A trigger, or event, is the thing that starts it, such as "an issue was labeled" or "a comment was posted". A job is one unit of work inside the workflow. A runner is the machine the job runs on; GitHub lends you one, a fresh Linux machine that is thrown away afterward. A step is one command or one action inside a job, run in order. A secret is a value, such as a key, that you store in the repository's settings so the workflow can use it without anyone seeing it in the file.
The example issue
Issue thirteen, the item count, is still waiting on an unmerged branch from last chapter, so this chapter uses a fresh, small request in the shared-list app. As an illustration, say the issue reads: trim and collapse spaces in list names. Its acceptance criteria are three. First, a name typed as two spaces, "Weekly", three spaces, "shop", and a trailing space is saved as "Weekly shop" with one space in the middle. Second, a name made only of spaces is still rejected. Third, after a reload, the list shows the cleaned name. Each of those can be checked by a test and by a click. That matters, because the action will produce a diff, and you will judge that diff against these three sentences.
Installing it the quick way
Open Claude Code in the repository and type the slash command install-github-app. It walks you through three things. It installs the Claude GitHub App on the repository. It stores a credential as a repository secret. And it pushes a branch that adds the workflow files, which comes to you as a pull request. When you merge that pull request, the workflow becomes active and "@claude" starts working.
Two conditions apply. It works only for repositories on github.com, not GitHub Enterprise Server. And it needs the GitHub command-line tool, gh, installed and signed in on your laptop, because that is how it talks to GitHub on your behalf.
The secret it stores has one of two names, depending on how you pay. If you use an Anthropic API key, the secret is called ANTHROPIC_API_KEY. If you use your Claude subscription, it stores a subscription token in a secret called CLAUDE_CODE_OAUTH_TOKEN.
Installing it by hand
If you would rather see each piece, do it in three moves. First, install the Claude GitHub App on the repository and check that it asks for read and write access to Contents, Issues and Pull requests. Contents lets it push a branch, Issues lets it read and comment on the issue, and Pull requests lets it comment on pull requests. Second, add the secret in the repository's settings, under secrets for Actions. For a subscription token, run claude setup-token on your laptop and paste what it prints into a secret named CLAUDE_CODE_OAUTH_TOKEN. If the secret will be shared across an organization, the documentation recommends an API key instead, so one person's subscription is not carrying everyone's work. Third, copy the example workflow from the action's repository, the file called claude dot yml in its examples folder, into your own dot github slash workflows folder, and commit it. To test, open any issue and comment "@claude, what does this repository do?" A run should appear in your repository's Actions tab within a minute.
What the workflow file says
The official example workflow listens for two events: a new issue comment, and a new review comment on a pull request. A condition at the top of the job says to go ahead only if the comment contains "@claude". That way, every ordinary comment on your repository does not start a paid run.
For the label path, the action has an input called label_trigger. You set it to a label name, say "claude", and the workflow listens to the issues event with the types opened, assigned and labeled. When someone puts the "claude" label on an issue, the job runs. There is also assignee_trigger, which takes a username, so assigning an issue to that user starts the run instead. The action's documentation shows these inputs but no complete label workflow, so the one in this example is put together from the documented inputs. Before you rely on it, compare yours with the current usage page in the action's repository.
Next comes the permissions block. It is the list of what this job's GitHub token may do, and it is enforced by GitHub, not requested politely. For this workflow it says contents write, issues write and pull-requests write, so Claude can push a branch and comment. It also says id-token write, which the default GitHub App sign-in needs. Leave it out and the run fails early with an error about OpenID Connect, the system GitHub uses to prove which workflow is asking. Finally it says actions read, which lets Claude see the results of your other checks.
Then there is the prompt input, and it changes how the action behaves. If you leave prompt out, the action runs in interactive mode: it waits for the trigger phrase and treats the comment or issue as the request. If you set a prompt, the action runs in automation mode and does exactly what the prompt says, which suits a scheduled job or a fixed task. One difference catches people out. In automation mode Claude has no shell access and no GitHub API access until you grant the tools. So an automation prompt that says "run the tests" will not run anything unless the tools are allowed.
Anything else you would pass to Claude Code on the command line goes through one input called claude_args. That is where you set a turn limit, with two dashes max-turns followed by a number, and where you choose a model. Older inputs with names like max_turns, model and allowed_tools are deprecated, and you will still see them in old blog posts. If you name a model, check the current model names in Anthropic's documentation, because example files go out of date fast. Our project default, Sonnet at medium effort, came from the evals baseline. Our rule sending database work to Opus at high effort lives in CLAUDE.md, and the runner reads CLAUDE.md like any other session.
Giving the runner a database
Our app stores lists in PostgreSQL, and last chapter taught a lesson that still applies here: a run with no database can report success with nothing tested. The runner starts empty, so the workflow has to supply one.
GitHub Actions does this with a service container. In the job you declare a service called postgres using the official postgres image. Set an environment value, POSTGRES_PASSWORD, so the database will start. Give it health options: a health command of pg_isready, plus an interval, a timeout and a number of retries. The health options make the job's steps wait until the database actually accepts connections. Finally, map port five four three two on the service to five four three two on the runner, so the job can reach it at localhost.
That port mapping applies to a job running directly on the runner, which is what we use. If you ran the job itself inside a container, you would skip the mapping and use the service's name, postgres, as the host, because the job and the service would share a private network.
Before Claude's step, the job runs four ordinary steps in order: check out the code, set up Node, install packages with npm ci, and run the project's migrations. The migration command is whatever your CLAUDE.md already lists; the workflow just calls it. Give the migrations and the tests the same DATABASE_URL, pointing at localhost with the password you set, so the tests hit the database the migrations just built.
After Claude's step, add one more: upload the test report as an artifact, which is a file the run keeps so you can download it later. Mark that step with the condition "if always", so it uploads even when the tests fail. A failed run is when you most want the report. The upload action also takes a setting for what to do if no files are found, either warn, error or ignore. Check the current version of GitHub's upload-artifact action before you pin one.
The first run fails, as an illustration
Here is how the example plays out. This is an illustration, not a measured result. You put the "claude" label on the trim-spaces issue and close the laptop. Later, on your phone, the Actions tab shows a red cross.
Open the failed job and expand the step that failed. GitHub shows each step's log there. If you are back at the desk, gh run view with two dashes log-failed prints only the failed steps' logs in your terminal. In this case the migration step reports "connection refused" on port five four three two. That message usually points to one of three things: a missing port mapping, the wrong host, or a database that never became healthy. Here the workflow file declared the postgres service but forgot the ports line, so nothing on the runner's localhost was listening.
Make one narrow fix: add the port mapping, commit it on its own with a message saying the test database is now reachable, and rerun. Do not change three things at once. If the rerun still fails, you want to know which change mattered.
A different first failure is just as common: a run that stops before Claude starts, with an error about OpenID Connect or the ID token. That is the missing id-token write permission, and the fix is that one line. A run that fails because the person who commented has no write access is not a bug; that is a limit, and we come to it shortly.
The second run
On the rerun, the log reads in order. Postgres becomes healthy, migrations apply, and Claude's step starts. Because the run came from an issue, Claude makes a new branch; from an issue it always does. Our skill and subagent files load from the checkout, and CLAUDE.md tells Claude where validation lives: the shared validation module. Claude adds a test with the spaced-out "Weekly shop" name, which fails, then changes the function that cleans names before they are measured. The repository's type-check hook runs after the edit. The full suite passes, the report uploads, and Claude comments on the issue with a link to a pre-filled pull request page.
Notice that Claude did not open the pull request. By default it pushes commits and hands you the link. Click it, and GitHub's form already has the title and description. You press the button.
One trap belongs here. If your workflow passes GitHub's default token, GITHUB_TOKEN, as the action's github_token input, your continuous integration will not run on Claude's commits, because GitHub does not start workflows from that token. The default App authentication avoids this, which is one more reason to keep id-token write.
Reviewing what came back
Open the pull request and read it against the three criteria, one at a time. For the first, find the new test and confirm it uses the spaced name and expects "Weekly shop". For the second, find the test that a name of only spaces is still rejected, and make sure the change trims before the empty check, not after. For the third, the reload, read the diff to confirm the cleaned name is what gets stored, not just what is shown. Then download the test report from the run and confirm those tests actually ran.
Then do what no log can do: check out the branch on your machine, start the app, type the spaced name, add it and reload. We learned in an earlier chapter that a passing suite and a working journey are different facts, and that still holds when a runner wrote the code.
If everything holds, merge. If one criterion falls short, comment on the pull request with "@claude" and a specific request, such as: the all-spaces name now saves as an empty list; restore the rejection and add a test for it. A pull request comment pushes to that same open pull request's branch, so the fix lands where you are reviewing.
Who can start it, and what it cannot do
These limits decide how far you can trust the setup. Only users with write access to the repository can trigger a run. Bots are blocked by default unless named in an input called allowed_bots. An input called allowed_non_write_users skips the write-access check; its own documentation calls it a significant security risk, and it works only with a supplied token and minimal permissions. For a repository where strangers can open issues, leave it out.
Treat issue text as data, not orders. Anyone who can write in an issue can try to slip instructions to Claude. The action strips many hidden instructions, but new tricks appear, so stripping is a help, not a guarantee. On pull requests, the action restores the dot claude folder, CLAUDE.md and the MCP file from the base branch, so a pull request cannot quietly rewrite your agent's own rules.
Some limits are enforced by the action itself. The App's token is short-lived and covers only this repository. Claude cannot change workflow files, cannot rebase or force push, and does not open pull requests on its own. Its commits are unsigned by default. If a run uses auto permission mode, remember that it reviews each action; it is not a wall around it. A turn limit through claude_args caps how long a run can wander. The action's documents do not describe a timeout or a spending cap of their own, so set GitHub's job timeout and watch your Anthropic usage page until you have run history to trust.
Try it on your own repository
Pick one of your own repositories on github.com. Run install-github-app inside Claude Code there, or follow the manual setup, and merge the workflow pull request it creates. Open a small issue with two criteria you could test, and comment "@claude" asking it to do the issue. It has worked when the Actions tab shows a finished run you can read step by step, and Claude has posted a branch with a pre-filled pull request link whose diff you can check against both criteria.
What this workflow still lacks is the reviewer and a clear stopping point. Our criteria-reviewer subagent checks diffs on the laptop. The next step is to make it part of this job, with a bounded number of repair attempts and a plain report when the run gives up.
Claude Code releases since version 2.1.310
That workflow touches the GitHub app installer, hooks and runners, and between them four recent releases touch all three.
Start with version 2.1.327, because it changes the command at the center of this chapter. The install-github-app command now asks you to confirm before it changes a repository. If you ran it before and it just went ahead, expect a question now, and read what it says it will change before saying yes. The same release fixed a hang in headless runs before the first request, which matters if a claude dash p job seemed to freeze at the very start. And claude mcp add-json can now read the server's settings from standard input. That keeps a token out of your command line, so it does not end up in your shell history or in the process list. When we added the GitHub MCP server, we single-quoted a placeholder to keep the shell from expanding it. If you add a server with a real token in its settings, piping the settings in is now the cleaner route.
Version 2.1.326 makes a hook's block decision hold in more cases. A hook that returns a decision of "block" now stops more of the calls it was meant to stop. The catch is a hook that always prints that decision, even when it means to allow the action, perhaps from copied sample code. Until now some of those prints were ignored. Now they may start blocking calls. The smallest useful action: open each hook script in your project's dot claude hooks folder and confirm that "block" is printed only on the path where you actually want to stop the agent. Our type-check hook signals failure with an exit code of two rather than a block decision, but check anything else you have added.
Version 2.1.325 changed self-hosted runners. They now refuse a session whose folder or repository path is a symbolic link, a file-system shortcut pointing somewhere else. The exception is a checkout made by a checkout hook. This chapter used GitHub's own runners, so it does not affect our workflow. If you run jobs on your own machine and your pipeline checks out into a linked folder, those jobs will now stop. The fix is to point the job at the real path.
Version 2.1.323 tightened auto mode for models reached through a gateway, a service that sits between Claude Code and the model. Auto mode now refuses gateway models whose names contain "haiku", except claude-haiku-5-5. If a cheap headless job runs an older Haiku model through a gateway in auto mode, it will be refused. Either move it to claude-haiku-5-5 or run it in a permission mode you chose on purpose.
Want a book of your own?
Gnothi wrote and narrated this chapter. Name a subject and it writes you a course, or a story that teaches it, one chapter at a time, delivered to your podcast app.
Get started free