Repository navigation
fix(runner): document who acts on GitHub, add GitHub SSH host keys - #246
Merged
Merged
Conversation
PreviewsThe start.coder.ddev.com landing-page preview has been removed. Read the Docs keeps or removes its own docs preview. |
Documentation build overview
|
## Short Summary (TL;DR) The self-hosted runner docs now say which GitHub account each path uses, what the "reconnect your GitHub account" failure means, why `gh auth status` reports an invalid token, and that every runner on an environment serves anyone who can start sessions there. ## The Issue A second claude.ai account in the same organization could not use a working runner workspace. Every session failed at setup with `GitHub authentication required. Please reconnect your GitHub account.`, and the runners exited and restarted after each attempt. Nothing in the docs explained that the runner's Anthropic-managed git uses the GitHub connection of the claude.ai account that started the session. Sessions also report `gh auth status` as broken, although `gh api` works. The docs did not say that SSH pushes from every session use the workspace owner's agent, or that a session from another person can land in the workspace. ## How This PR Solves The Issue | File | Change | | --- | --- | | `docs/content/workspaces/ai-tools.md` | New "Who acts on GitHub" section, with a table of HTTPS git, `gh` and SSH, the reconnect error, the REST-only `gh` and its placeholder token, and the `/usr/bin/gh` and `GH_TOKEN` bypass. New "Who can use the runner" section: an environment is a pool with no routing by label or platform, so share it only with people you trust with the workspace's credentials. | | `files/README.md` (both module copies) | "GitHub access" and "Troubleshooting" sections for `~/.claude-runner/README.md`. | | `files/SKILL.md` (both module copies) | New "GitHub and `gh`" section, so sessions stop reporting the placeholder token as a fault, use `gh api` or MCP instead of GraphQL commands, and don't call `/usr/bin/gh`. "Pushing over SSH" now says SSH acts as the workspace owner, and asks Claude to check with the user when that differs from the session's account. | The behavior described comes from runner logs and from checks in a runner session: the `gh` wrapper in the session's `ccr/bin`, `GH_DEBUG=api gh auth status` calling GraphQL, `gh api user`, and `ssh -T git@github.com`. ## Manual Testing Instructions Read the new sections in the Read the Docs preview for this PR, at `workspaces/ai-tools/#who-acts-on-github` and `#who-can-use-the-runner`. In a freeform workspace with the runner on, restart it, then check the installed copies: ```bash grep -A3 '## Troubleshooting' ~/.claude-runner/README.md # Expect the "reconnect your GitHub account" entry grep -A3 '## GitHub and `gh`' ~/.claude/skills/coder-shared-workspace/SKILL.md # Expect the gh wrapper explanation ``` In a runner session started from claude.ai, ask Claude to run these: ```bash gh auth status # Expect "The token in GH_TOKEN is invalid", as the docs now describe gh api user --jq .login # Expect the GitHub login connected to the claude.ai account that started the session ``` ## Automated Testing Overview Claude Code ran `make docs-check` (strict Zensical build, markdownlint, doc parameter check) and markdownlint on both module `files/*.md` copies on Linux. Both passed. No template behavior changed, so no Terraform tests ran. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3Cc2H45aXoSFUfZTwQYjX
rfay
force-pushed
the
20261112_rfay_runner_multiuser
branch
from
November 17, 2026 03:20
bc39b91 to
850246e
Compare
Runner sessions don't get a gh that acts as their own account. The per-session gh shim exists, but it isn't on the shell's PATH, so `gh` is the workspace's /usr/bin/gh. On a clean runner workspace that gh isn't logged in, and the session's system prompt says to use the GitHub MCP tools. The docs, README and skill now say that, and keep the warning against storing a gh login or token in a shared workspace. A clean runner workspace has no ~/.ssh/known_hosts, so `ssh -T git@github.com` and SSH pushes stopped at "Host key verification failed". The runner startup now adds GitHub's published host keys when github.com isn't known yet. The docs also say that the Coder key is one key per Coder user, shared by all of that user's workspaces. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
A runner session started without a repository gets no clone and no GitHub MCP tools, so it cannot compare the SSH account with its own. A second claude.ai account in the same environment could still push over SSH as the workspace owner. The skill now asks Claude to check with the user first in that case, and the runner README says what such a session gets. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
Any process in a runner workspace can use the owner's Coder key, so every session can push over SSH as the workspace owner, whoever started it. Even among trusted people in one organization, that push is easy to miss. The docs and runner README now recommend that a dedicated Coder user own a shared runner workspace, with its Coder key on no one's GitHub account, so sessions push only over HTTPS as the person who started them. They also say not to forward an SSH agent into a shared runner workspace. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
A runner workspace runs every session as its owner, with the owner's SSH agent and Coder key, and no template setting can change that. Sharing one between people is too easy to get wrong, so the docs and runner README now say a runner workspace is personal: don't share its environment, and each person who wants a runner sets up their own. This replaces the advice for organization-shared runners. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
This was referenced Nov 17, 2026
A runner workspace is personal, so a gh login there acts only for its owner's sessions. That login gives sessions GraphQL and every repository the owner can reach, while the GitHub MCP tools reach only the repositories attached to the session. The docs, runner README and skill no longer tell people to avoid gh auth login. They say to log in once, and to add a line to ~/.claude/CLAUDE.md telling Claude to use gh, because Claude's built-in instructions in a runner session use gh only when the user's own instructions name it. The skill checks gh auth status and falls back to the MCP tools without a login. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Short Summary (TL;DR)
The self-hosted runner docs now say which GitHub account each path uses, how to give sessions a working
gh, and that a runner workspace is personal: every runner on an environment serves anyone who can start sessions there, as the workspace owner. Runner workspaces also get GitHub's SSH host keys, so SSH pushes work on a fresh workspace.The Issue
A second claude.ai account in the same organization could not use a working runner workspace. Every session failed at setup with
GitHub authentication required. Please reconnect your GitHub account., and the runners exited and restarted after each attempt. Nothing in the docs explained that the runner's Anthropic-managed git uses the GitHub connection of the claude.ai account that started the session.The docs also didn't say what
ghdoes in a session, that SSH pushes from every session act as the workspace owner, or that a session from another person can land in the workspace. On a fresh runner workspace, SSH pushes failed withHost key verification failed, because~/.ssh/known_hostsdidn't exist.How This PR Solves The Issue
docs/content/workspaces/ai-tools.mdghand SSH act as the workspace owner. It covers the reconnect error, logging in toghonce in the workspace, and telling Claude to useghin~/.claude/CLAUDE.md. New "Who can use the runner" section: a runner workspace is personal, so don't share its environment.files/README.md(both module copies)~/.claude-runner/README.md, with the sameghadvice and that the runner is personal.files/SKILL.md(both module copies)gh" section: checkgh auth status, useghwhen it has a login and the user's instructions say to, and otherwise use the GitHub MCP tools. "Pushing over SSH" says SSH acts as the workspace owner, and asks Claude to check with the user when that differs from the session's account.outputs.tf,files/github_known_hosts(both module copies)~/.ssh/known_hostswhengithub.comisn't there yet.In a runner session,
ghis the workspace's own/usr/bin/gh. The runner log reportsgh_path_shim=true, but the shim isn't on the session shell'sPATH. Soghacts as whoever logged it in, and on a clean workspace it doesn't work. Aghlogin gives sessions GraphQL and every repository the owner can reach, while the MCP tools reach only the repositories attached to the session. Claude's built-in instructions in a runner session useghonly when the user's own instructions name it, which is why the docs suggest the~/.claude/CLAUDE.mdline.No template setting can stop SSH pushes as the owner. Any process in a Coder workspace can use the owner's Coder key, through
coder gitsshor the workspace agent API. That is why the docs say not to share a runner environment.Manual Testing Instructions
Read the new sections in the docs preview, including
#who-can-use-the-runner.Push this template version, then create a freeform workspace with the runner on and an environment secret saved. In the workspace:
Start a session in that environment from claude.ai with a repository selected, and ask Claude to run
gh auth status. Expect "You are not logged into any GitHub hosts". Ask Claude to call the GitHub MCP toolget_me, and expect your GitHub login.Then run
gh auth loginin the workspace, and add "Useghfor GitHub operations; it is logged in as me." to~/.claude/CLAUDE.md. In a new session, ask Claude to list the open pull requests of the repository. Expect it to usegh pr list.Automated Testing Overview
A new assertion in
freeform/tests/validate.tftest.hclchecks that the startup script installs GitHub's host keys. It fails without theoutputs.tfchange. Claude Code ranmake validate,make test-templates,make fmt-check, the Zensical strict build, markdownlint andscripts/check-doc-params.shon Linux, and all passed. After the later docs-only changes, only markdownlint ran again.On a clean runner workspace, Claude Code ran the known_hosts step, and
ssh -T git@github.comthen greeted the workspace owner through the Coder key. A session started by a second claude.ai account in the same environment returned that account fromget_me, andls-remote originworked over HTTPS, whilessh -Tgreeted the workspace owner. On a workspace with aghlogin, sessions'ghacted as the owner, GraphQL included. Nobody has reproduced the "reconnect your GitHub account" error on this version.🤖 Generated with Claude Code
https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp