Skip to content

fix(runner): document who acts on GitHub, add GitHub SSH host keys - #246

Merged
rfay merged 6 commits into
mainfrom
20261112_rfay_runner_multiuser
Nov 17, 2026
Merged

rfay merged 6 commits into
mainfrom
20261112_rfay_runner_multiuser

Conversation

@rfay

@rfay rfay commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

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 gh does 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 with Host key verification failed, because ~/.ssh/known_hosts didn't exist.

How This PR Solves The Issue

File Change
docs/content/workspaces/ai-tools.md New "Who acts on GitHub" section. HTTPS git and the GitHub MCP tools act as the session's connected account. gh and SSH act as the workspace owner. It covers the reconnect error, logging in to gh once in the workspace, and telling Claude to use gh in ~/.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) "GitHub access" and "Troubleshooting" sections for ~/.claude-runner/README.md, with the same gh advice and that the runner is personal.
files/SKILL.md (both module copies) New "GitHub and gh" section: check gh auth status, use gh when 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) Runner startup adds GitHub's published host keys to ~/.ssh/known_hosts when github.com isn't there yet.

In a runner session, gh is the workspace's own /usr/bin/gh. The runner log reports gh_path_shim=true, but the shim isn't on the session shell's PATH. So gh acts as whoever logged it in, and on a clean workspace it doesn't work. A gh login 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 use gh only when the user's own instructions name it, which is why the docs suggest the ~/.claude/CLAUDE.md line.

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 gitssh or 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:

ssh-keygen -F github.com
# Expect GitHub's host keys
grep -A3 '## GitHub and `gh`' ~/.claude/skills/coder-shared-workspace/SKILL.md
# Expect the section about the workspace's own gh

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 tool get_me, and expect your GitHub login.

Then run gh auth login in the workspace, and add "Use gh for 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 use gh pr list.

Automated Testing Overview

A new assertion in freeform/tests/validate.tftest.hcl checks that the startup script installs GitHub's host keys. It fails without the outputs.tf change. Claude Code ran make validate, make test-templates, make fmt-check, the Zensical strict build, markdownlint and scripts/check-doc-params.sh on 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.com then greeted the workspace owner through the Coder key. A session started by a second claude.ai account in the same environment returned that account from get_me, and ls-remote origin worked over HTTPS, while ssh -T greeted the workspace owner. On a workspace with a gh login, sessions' gh acted 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

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Previews

The start.coder.ddev.com landing-page preview has been removed. Read the Docs keeps or removes its own docs preview.

@read-the-docs-community

read-the-docs-community Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

## 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
rfay force-pushed the 20261112_rfay_runner_multiuser branch from bc39b91 to 850246e Compare November 17, 2026 03:20
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
@rfay rfay changed the title docs(runner): explain who acts on GitHub and who can use a runner fix(runner): document who acts on GitHub, add GitHub SSH host keys Nov 17, 2026
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
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
@rfay
rfay merged commit 812c23d into main Nov 17, 2026
21 checks passed
@rfay
rfay deleted the 20261112_rfay_runner_multiuser branch November 17, 2026 18:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants