From 850246e45eaa2bd3f7684ee46cfc27ebb6b9ef3d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Nov 2026 22:27:01 +0000 Subject: [PATCH 1/6] docs(runner): explain who acts on GitHub and who can use a runner MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 Claude-Session: https://claude.ai/code/session_01T3Cc2H45aXoSFUfZTwQYjX --- docs/content/workspaces/ai-tools.md | 27 ++++++++++++++-- .../claude-self-hosted-runner/files/README.md | 25 +++++++++++++++ .../claude-self-hosted-runner/files/SKILL.md | 31 ++++++++++++++++--- .../claude-self-hosted-runner/files/README.md | 25 +++++++++++++++ .../claude-self-hosted-runner/files/SKILL.md | 31 ++++++++++++++++--- 5 files changed, 127 insertions(+), 12 deletions(-) diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index 27aa09e..3bbd9a2 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -120,6 +120,29 @@ One-time setup: On every start, the runner runs in the `tmux` session `claude-runner` (`tmux attach -t claude-runner`), logging to `/tmp/claude-runner-.log`. Sessions clone their repositories under `~/workspace/runner-`. Run `claude-sessions` to list live sessions with their checkout, branch and number of unpushed commits. - **Use a workspace only for the runner.** The runner rewrites `~/.gitconfig` and `~/.config/git` before every session. It can't be turned on together with remote control. -- **Concurrent sessions** (1 to 4) sets how many sessions run at once. They share the workspace's Docker daemon and DDEV, and a skill installed in `~/.claude/skills/coder-shared-workspace` tells them how to stay out of each other's way. For full isolation, use several workspaces with one session each; the same environment secret works in all of them. +- **Concurrent sessions** (1 to 4) sets how many sessions run at once. They share the workspace's Docker daemon and DDEV, and a skill installed in `~/.claude/skills/coder-shared-workspace` tells them how to stay out of each other's way. For full isolation, use several workspaces with one session each; the same environment secret works in all of them (see [Who can use the runner](#who-can-use-the-runner)). - **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-`. When a session ends, including when the runner releases it after 30 idle minutes, `claude-runner-sweep` cleans that runner's directory, and it runs again before each runner start. Uncommitted changes become `runner-rescue` stashes in the clone (`git stash list`). Worktrees are removed. Extra clones a session made are deleted if everything in them is pushed, and otherwise moved to `~/.local/state/claude-runner-rescue/`. Everything the sweep does is logged in `~/.local/state/claude-runner-rescue/log`, and rescues are kept for 30 days. If a checkout is still dirty when a session starts, a hook tells Claude to stash the leftovers rather than work around them. -- **Pushing to your fork.** Runner and remote-control sessions use the workspace SSH agent: your own agent when you have one forwarded (VS Code, `coder ssh -A`), otherwise the Coder workspace key. Add your fork as an SSH remote, such as `git@github.com:/`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account. +- **Pushing to your fork.** Runner and remote-control sessions use the workspace SSH agent: your own agent when you have one forwarded (VS Code, `coder ssh -A`), otherwise the Coder workspace key. Add your fork as an SSH remote, such as `git@github.com:/`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account. SSH pushes act as the workspace owner, whoever started the session; see [Who acts on GitHub](#who-acts-on-github). + +### Who acts on GitHub + +The runner uses Anthropic-managed git. A session reaches GitHub in three ways, and only two of them follow the person who started it: + +| Path | Acts as | +|---|---| +| HTTPS git: the clone, fetch, and pushes to `origin` | The GitHub account connected to the claude.ai account that started the session | +| `gh` inside a session | The same connected account, through Anthropic's proxy | +| SSH remotes (`git@github.com:…`) | Every key in the workspace SSH agent: the workspace owner's forwarded agent, or the Coder workspace key | + +- **Everyone who starts sessions must connect GitHub** in claude.ai, under **Settings → Connectors → GitHub**. Nothing in the workspace stands in for it. When the connection is missing or has expired, the session fails before Claude starts, and `/tmp/claude-runner-.log` shows `Repository access validation failed` with `GitHub authentication required. Please reconnect your GitHub account.` Reconnect, then start the session again. Until then the runner exits and restarts after each attempt, and the session may be retried on other runners. +- **`gh` in a session is REST-only.** A per-session wrapper sends `gh` through the proxy with a placeholder token, `GH_TOKEN=proxy-injected`. `gh api …` works. Commands that use GitHub's GraphQL API, such as `gh pr list`, `gh pr view` and `gh pr create`, fail with HTTP 403. `gh auth status` always reports the token as invalid, because it checks it over GraphQL; use `gh api user --jq .login` to see which account a session acts as. +- **`gh` in your own terminal is different.** It uses the login in `~/.config/gh`, if you made one. A session that calls `/usr/bin/gh` directly, or that has a real `GH_TOKEN` or `GITHUB_TOKEN` set, uses that login or token instead of the session's own account. Don't run `gh auth login` or set those variables in a workspace that other people's sessions use. +- **SSH offers every key the agent holds.** With an agent forwarded from your computer, sessions can sign with all of its keys, not only your GitHub key, for as long as you stay connected. + +### Who can use the runner + +An environment is a pool. Every runner that uses its secret, in this workspace or any other, takes the next session from anyone who can start sessions in that environment, such as other members of your claude.ai organization. The runner's label decides nothing. + +- A session from another person can land in your workspace. It then runs as your Unix user, with your SSH agent and any `gh` login or credentials stored in the workspace. +- Share an environment only with people you would trust with those credentials. Otherwise, give each person their own environment and their own runner workspace. Their SSH pushes then use their own Coder key. +- Use a separate environment for each kind of runner you want to choose between, for example one per operating system. Sessions go to whichever runner is free, with no routing by label or platform. diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md index 7169646..44df8fa 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -35,6 +35,31 @@ directory. The workspace rewrites this README on every start. `~/.local/state/claude-runner-rescue/`, and its `log` lists every change. Both are kept for 30 days. +## GitHub access + +Sessions reach GitHub over HTTPS and `gh` as the GitHub account connected +to the claude.ai account that started them, under Settings → Connectors on +claude.ai. Every person who starts sessions here needs that connection. +SSH remotes are different: they use this workspace's SSH agent, so they act +as the workspace owner for every session. + +Every runner that uses this environment secret takes sessions from anyone +who can start sessions in the environment, and runs them as this +workspace's user, with its SSH agent. Share the environment only with +people you trust with those keys. + +## Troubleshooting + +- A session fails before Claude starts, and the log shows + `Repository access validation failed` and `GitHub authentication + required. Please reconnect your GitHub account.`: the person who started + the session must reconnect GitHub on claude.ai, then start the session + again. Until then each runner that picks it up exits and restarts, which + is expected. +- `gh auth status` in a session says the token in `GH_TOKEN` is invalid: + expected. Sessions send `gh` through a REST-only proxy with a placeholder + token. `gh api user --jq .login` shows the account a session uses. + ## Stop the runner Turn the setting off and restart the workspace. To stop it until the next diff --git a/freeform/modules/claude-self-hosted-runner/files/SKILL.md b/freeform/modules/claude-self-hosted-runner/files/SKILL.md index 2686984..46ca951 100644 --- a/freeform/modules/claude-self-hosted-runner/files/SKILL.md +++ b/freeform/modules/claude-self-hosted-runner/files/SKILL.md @@ -127,19 +127,40 @@ only what you created (build output, your worktrees, your `~/tmp` directory, your test projects). Never delete another session's files, and never prune Docker images or volumes another session may use. +## GitHub and `gh` + +HTTPS git and `gh` act as the GitHub account connected to the claude.ai +account that started this session, through Anthropic's proxy. + +- `gh` here is a per-session wrapper that sets a placeholder token, + `GH_TOKEN=proxy-injected`. `gh auth status` therefore always reports the + token as invalid. Don't report that as a problem. Check access with + `gh api user --jq .login`. +- The proxy serves only GitHub's REST API. `gh pr list`, `gh pr view`, + `gh pr create` and other GraphQL commands fail with HTTP 403. Use + `gh api repos///...` or the GitHub MCP tools. +- Don't call `/usr/bin/gh` directly, and don't set `GH_TOKEN` or + `GITHUB_TOKEN`. Either makes `gh` skip the proxy and act as the login or + token the workspace holds, not as this session's account. +- Don't run `gh auth login`. It stores a login for the whole workspace, + which every later session could use. + ## Pushing over SSH `SSH_AUTH_SOCK` points at the workspace SSH agent relay, -`~/.ssh-agent-relay/agent.sock`. The relay uses the user's own agent when -one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses the Coder -workspace key, which GitHub accepts once the user adds it to their account -(`coder publickey` prints it). +`~/.ssh-agent-relay/agent.sock`. The relay uses the workspace owner's own +agent when one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses +the Coder workspace key, which GitHub accepts once the owner adds it to +their account (`coder publickey` prints it). SSH pushes act as the +workspace owner, who may not be the person who started this session. - When you add a remote, such as the user's fork, use its SSH URL: `git remote add git@github.com:/`. HTTPS pushes go through the session's git proxy, which reaches only the repositories attached to the session. - Leave `origin` as the runner cloned it. -- `ssh -T git@github.com` greets the user by name when SSH works. +- `ssh -T git@github.com` greets the account SSH pushes act as. If it + differs from `gh api user --jq .login`, ask the user before pushing over + SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys. diff --git a/modules/claude-self-hosted-runner/files/README.md b/modules/claude-self-hosted-runner/files/README.md index 7169646..44df8fa 100644 --- a/modules/claude-self-hosted-runner/files/README.md +++ b/modules/claude-self-hosted-runner/files/README.md @@ -35,6 +35,31 @@ directory. The workspace rewrites this README on every start. `~/.local/state/claude-runner-rescue/`, and its `log` lists every change. Both are kept for 30 days. +## GitHub access + +Sessions reach GitHub over HTTPS and `gh` as the GitHub account connected +to the claude.ai account that started them, under Settings → Connectors on +claude.ai. Every person who starts sessions here needs that connection. +SSH remotes are different: they use this workspace's SSH agent, so they act +as the workspace owner for every session. + +Every runner that uses this environment secret takes sessions from anyone +who can start sessions in the environment, and runs them as this +workspace's user, with its SSH agent. Share the environment only with +people you trust with those keys. + +## Troubleshooting + +- A session fails before Claude starts, and the log shows + `Repository access validation failed` and `GitHub authentication + required. Please reconnect your GitHub account.`: the person who started + the session must reconnect GitHub on claude.ai, then start the session + again. Until then each runner that picks it up exits and restarts, which + is expected. +- `gh auth status` in a session says the token in `GH_TOKEN` is invalid: + expected. Sessions send `gh` through a REST-only proxy with a placeholder + token. `gh api user --jq .login` shows the account a session uses. + ## Stop the runner Turn the setting off and restart the workspace. To stop it until the next diff --git a/modules/claude-self-hosted-runner/files/SKILL.md b/modules/claude-self-hosted-runner/files/SKILL.md index 2686984..46ca951 100644 --- a/modules/claude-self-hosted-runner/files/SKILL.md +++ b/modules/claude-self-hosted-runner/files/SKILL.md @@ -127,19 +127,40 @@ only what you created (build output, your worktrees, your `~/tmp` directory, your test projects). Never delete another session's files, and never prune Docker images or volumes another session may use. +## GitHub and `gh` + +HTTPS git and `gh` act as the GitHub account connected to the claude.ai +account that started this session, through Anthropic's proxy. + +- `gh` here is a per-session wrapper that sets a placeholder token, + `GH_TOKEN=proxy-injected`. `gh auth status` therefore always reports the + token as invalid. Don't report that as a problem. Check access with + `gh api user --jq .login`. +- The proxy serves only GitHub's REST API. `gh pr list`, `gh pr view`, + `gh pr create` and other GraphQL commands fail with HTTP 403. Use + `gh api repos///...` or the GitHub MCP tools. +- Don't call `/usr/bin/gh` directly, and don't set `GH_TOKEN` or + `GITHUB_TOKEN`. Either makes `gh` skip the proxy and act as the login or + token the workspace holds, not as this session's account. +- Don't run `gh auth login`. It stores a login for the whole workspace, + which every later session could use. + ## Pushing over SSH `SSH_AUTH_SOCK` points at the workspace SSH agent relay, -`~/.ssh-agent-relay/agent.sock`. The relay uses the user's own agent when -one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses the Coder -workspace key, which GitHub accepts once the user adds it to their account -(`coder publickey` prints it). +`~/.ssh-agent-relay/agent.sock`. The relay uses the workspace owner's own +agent when one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses +the Coder workspace key, which GitHub accepts once the owner adds it to +their account (`coder publickey` prints it). SSH pushes act as the +workspace owner, who may not be the person who started this session. - When you add a remote, such as the user's fork, use its SSH URL: `git remote add git@github.com:/`. HTTPS pushes go through the session's git proxy, which reaches only the repositories attached to the session. - Leave `origin` as the runner cloned it. -- `ssh -T git@github.com` greets the user by name when SSH works. +- `ssh -T git@github.com` greets the account SSH pushes act as. If it + differs from `gh api user --jq .login`, ask the user before pushing over + SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys. From 2d543faa639115d305cc911e586b1b5a6f7b1378 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 15:30:34 +0000 Subject: [PATCH 2/6] fix(runner): correct gh behavior in runner docs, add GitHub host keys 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 Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp --- docs/content/workspaces/ai-tools.md | 12 +++---- .../claude-self-hosted-runner/files/README.md | 24 +++++++++----- .../claude-self-hosted-runner/files/SKILL.md | 31 ++++++++----------- .../files/github_known_hosts | 3 ++ .../claude-self-hosted-runner/outputs.tf | 7 +++++ freeform/tests/validate.tftest.hcl | 4 +++ .../claude-self-hosted-runner/files/README.md | 24 +++++++++----- .../claude-self-hosted-runner/files/SKILL.md | 31 ++++++++----------- .../files/github_known_hosts | 3 ++ modules/claude-self-hosted-runner/outputs.tf | 7 +++++ 10 files changed, 88 insertions(+), 58 deletions(-) create mode 100644 freeform/modules/claude-self-hosted-runner/files/github_known_hosts create mode 100644 modules/claude-self-hosted-runner/files/github_known_hosts diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index 3bbd9a2..cf687ad 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -122,7 +122,7 @@ On every start, the runner runs in the `tmux` session `claude-runner` (`tmux att - **Use a workspace only for the runner.** The runner rewrites `~/.gitconfig` and `~/.config/git` before every session. It can't be turned on together with remote control. - **Concurrent sessions** (1 to 4) sets how many sessions run at once. They share the workspace's Docker daemon and DDEV, and a skill installed in `~/.claude/skills/coder-shared-workspace` tells them how to stay out of each other's way. For full isolation, use several workspaces with one session each; the same environment secret works in all of them (see [Who can use the runner](#who-can-use-the-runner)). - **Checkouts are cleaned between sessions.** A runner keeps its clones under `~/workspace/runner-`. When a session ends, including when the runner releases it after 30 idle minutes, `claude-runner-sweep` cleans that runner's directory, and it runs again before each runner start. Uncommitted changes become `runner-rescue` stashes in the clone (`git stash list`). Worktrees are removed. Extra clones a session made are deleted if everything in them is pushed, and otherwise moved to `~/.local/state/claude-runner-rescue/`. Everything the sweep does is logged in `~/.local/state/claude-runner-rescue/log`, and rescues are kept for 30 days. If a checkout is still dirty when a session starts, a hook tells Claude to stash the leftovers rather than work around them. -- **Pushing to your fork.** Runner and remote-control sessions use the workspace SSH agent: your own agent when you have one forwarded (VS Code, `coder ssh -A`), otherwise the Coder workspace key. Add your fork as an SSH remote, such as `git@github.com:/`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account. SSH pushes act as the workspace owner, whoever started the session; see [Who acts on GitHub](#who-acts-on-github). +- **Pushing to your fork.** Runner and remote-control sessions use the workspace SSH agent: your own agent when you have one forwarded (VS Code, `coder ssh -A`), otherwise your Coder key. Add your fork as an SSH remote, such as `git@github.com:/`. If you don't forward an agent, add the key that `coder publickey` prints to your GitHub account. The runner adds GitHub's host keys to `~/.ssh/known_hosts`. SSH pushes act as the workspace owner, whoever started the session; see [Who acts on GitHub](#who-acts-on-github). ### Who acts on GitHub @@ -131,18 +131,18 @@ The runner uses Anthropic-managed git. A session reaches GitHub in three ways, a | Path | Acts as | |---|---| | HTTPS git: the clone, fetch, and pushes to `origin` | The GitHub account connected to the claude.ai account that started the session | -| `gh` inside a session | The same connected account, through Anthropic's proxy | -| SSH remotes (`git@github.com:…`) | Every key in the workspace SSH agent: the workspace owner's forwarded agent, or the Coder workspace key | +| The GitHub MCP tools in a session | The same connected account, through Anthropic's proxy | +| SSH remotes (`git@github.com:…`) | Every key in the workspace SSH agent: the workspace owner's forwarded agent, or the owner's Coder key | - **Everyone who starts sessions must connect GitHub** in claude.ai, under **Settings → Connectors → GitHub**. Nothing in the workspace stands in for it. When the connection is missing or has expired, the session fails before Claude starts, and `/tmp/claude-runner-.log` shows `Repository access validation failed` with `GitHub authentication required. Please reconnect your GitHub account.` Reconnect, then start the session again. Until then the runner exits and restarts after each attempt, and the session may be retried on other runners. -- **`gh` in a session is REST-only.** A per-session wrapper sends `gh` through the proxy with a placeholder token, `GH_TOKEN=proxy-injected`. `gh api …` works. Commands that use GitHub's GraphQL API, such as `gh pr list`, `gh pr view` and `gh pr create`, fail with HTTP 403. `gh auth status` always reports the token as invalid, because it checks it over GraphQL; use `gh api user --jq .login` to see which account a session acts as. -- **`gh` in your own terminal is different.** It uses the login in `~/.config/gh`, if you made one. A session that calls `/usr/bin/gh` directly, or that has a real `GH_TOKEN` or `GITHUB_TOKEN` set, uses that login or token instead of the session's own account. Don't run `gh auth login` or set those variables in a workspace that other people's sessions use. +- **`gh` in a session is the workspace's own `gh`.** Sessions don't get a `gh` that acts as their own account; they use the GitHub MCP tools instead. On a runner workspace with no `gh` login, `gh` reports that it isn't logged in, which is expected. If you run `gh auth login`, or store a `GH_TOKEN` or `GITHUB_TOKEN`, in the workspace, every session uses that login, whoever started it. Don't do that in a workspace that other people's sessions use. +- **Your Coder key is the same in all your workspaces.** `coder publickey` prints one key per Coder user, so adding it to GitHub lets SSH push as you from every runner workspace you own, for every session on it. - **SSH offers every key the agent holds.** With an agent forwarded from your computer, sessions can sign with all of its keys, not only your GitHub key, for as long as you stay connected. ### Who can use the runner An environment is a pool. Every runner that uses its secret, in this workspace or any other, takes the next session from anyone who can start sessions in that environment, such as other members of your claude.ai organization. The runner's label decides nothing. -- A session from another person can land in your workspace. It then runs as your Unix user, with your SSH agent and any `gh` login or credentials stored in the workspace. +- A session from another person can land in your workspace. It then runs as your Unix user, with your SSH agent, your Coder key, and any `gh` login or credentials stored in the workspace. - Share an environment only with people you would trust with those credentials. Otherwise, give each person their own environment and their own runner workspace. Their SSH pushes then use their own Coder key. - Use a separate environment for each kind of runner you want to choose between, for example one per operating system. Sessions go to whichever runner is free, with no routing by label or platform. diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md index 44df8fa..4ffafb2 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -37,11 +37,20 @@ directory. The workspace rewrites this README on every start. ## GitHub access -Sessions reach GitHub over HTTPS and `gh` as the GitHub account connected -to the claude.ai account that started them, under Settings → Connectors on -claude.ai. Every person who starts sessions here needs that connection. -SSH remotes are different: they use this workspace's SSH agent, so they act -as the workspace owner for every session. +Sessions clone, fetch and push to `origin` over HTTPS as the GitHub account +connected to the claude.ai account that started them, under Settings → +Connectors on claude.ai. Every person who starts sessions here needs that +connection. The GitHub MCP tools in a session use the same account. + +`gh` in a session is this workspace's own `/usr/bin/gh`. It isn't logged in, +so it doesn't work, and sessions use the GitHub MCP tools instead. Don't run +`gh auth login` or store a `GH_TOKEN` here: every session, whoever started +it, would then act on GitHub as you. + +SSH remotes use this workspace's SSH agent: your forwarded agent, or your +Coder key, which is the same in all your workspaces. SSH pushes act as you +in every session. The workspace adds GitHub's host keys to +`~/.ssh/known_hosts` on start. Every runner that uses this environment secret takes sessions from anyone who can start sessions in the environment, and runs them as this @@ -56,9 +65,8 @@ people you trust with those keys. the session must reconnect GitHub on claude.ai, then start the session again. Until then each runner that picks it up exits and restarts, which is expected. -- `gh auth status` in a session says the token in `GH_TOKEN` is invalid: - expected. Sessions send `gh` through a REST-only proxy with a placeholder - token. `gh api user --jq .login` shows the account a session uses. +- `gh` in a session says it isn't logged in: expected. Sessions use the + GitHub MCP tools. ## Stop the runner diff --git a/freeform/modules/claude-self-hosted-runner/files/SKILL.md b/freeform/modules/claude-self-hosted-runner/files/SKILL.md index 46ca951..51c59ba 100644 --- a/freeform/modules/claude-self-hosted-runner/files/SKILL.md +++ b/freeform/modules/claude-self-hosted-runner/files/SKILL.md @@ -129,28 +129,23 @@ never prune Docker images or volumes another session may use. ## GitHub and `gh` -HTTPS git and `gh` act as the GitHub account connected to the claude.ai -account that started this session, through Anthropic's proxy. - -- `gh` here is a per-session wrapper that sets a placeholder token, - `GH_TOKEN=proxy-injected`. `gh auth status` therefore always reports the - token as invalid. Don't report that as a problem. Check access with - `gh api user --jq .login`. -- The proxy serves only GitHub's REST API. `gh pr list`, `gh pr view`, - `gh pr create` and other GraphQL commands fail with HTTP 403. Use - `gh api repos///...` or the GitHub MCP tools. -- Don't call `/usr/bin/gh` directly, and don't set `GH_TOKEN` or - `GITHUB_TOKEN`. Either makes `gh` skip the proxy and act as the login or - token the workspace holds, not as this session's account. -- Don't run `gh auth login`. It stores a login for the whole workspace, - which every later session could use. +HTTPS git (the clone, fetch, and pushes to `origin`) and the GitHub MCP +tools act as the GitHub account connected to the claude.ai account that +started this session, through Anthropic's proxy. + +- `gh` here is the workspace's own `/usr/bin/gh`, which isn't logged in. + Use the GitHub MCP tools for pull requests, issues and the API. Don't + report the missing `gh` login as a problem. +- Don't run `gh auth login`, and don't store or export `GH_TOKEN` or + `GITHUB_TOKEN`. A login or token in this workspace would make every later + session act as that account, whoever started it. ## Pushing over SSH `SSH_AUTH_SOCK` points at the workspace SSH agent relay, `~/.ssh-agent-relay/agent.sock`. The relay uses the workspace owner's own agent when one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses -the Coder workspace key, which GitHub accepts once the owner adds it to +the owner's Coder key, which GitHub accepts once the owner adds it to their account (`coder publickey` prints it). SSH pushes act as the workspace owner, who may not be the person who started this session. @@ -160,7 +155,7 @@ workspace owner, who may not be the person who started this session. attached to the session. - Leave `origin` as the runner cloned it. - `ssh -T git@github.com` greets the account SSH pushes act as. If it - differs from `gh api user --jq .login`, ask the user before pushing over - SSH. + differs from the GitHub account the MCP tools report (`get_me`), ask the + user before pushing over SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys. diff --git a/freeform/modules/claude-self-hosted-runner/files/github_known_hosts b/freeform/modules/claude-self-hosted-runner/files/github_known_hosts new file mode 100644 index 0000000..f4c560e --- /dev/null +++ b/freeform/modules/claude-self-hosted-runner/files/github_known_hosts @@ -0,0 +1,3 @@ +github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl +github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg= +github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk= diff --git a/freeform/modules/claude-self-hosted-runner/outputs.tf b/freeform/modules/claude-self-hosted-runner/outputs.tf index 02f3e71..a688eb1 100644 --- a/freeform/modules/claude-self-hosted-runner/outputs.tf +++ b/freeform/modules/claude-self-hosted-runner/outputs.tf @@ -26,6 +26,13 @@ output "startup_script" { # The runner copies ~/.claude into each session when it starts. mkdir -p ~/.claude/skills/coder-shared-workspace ~/.cache "${var.base_dir}" echo '${base64encode(file("${path.module}/files/SKILL.md"))}' | base64 -d > ~/.claude/skills/coder-shared-workspace/SKILL.md + # Without github.com in known_hosts, SSH pushes from sessions fail with + # "Host key verification failed". These are GitHub's published keys. + mkdir -p ~/.ssh + chmod 700 ~/.ssh + if ! ssh-keygen -F github.com >/dev/null 2>&1; then + echo '${base64encode(file("${path.module}/files/github_known_hosts"))}' | base64 -d >> ~/.ssh/known_hosts + fi mkdir -p ~/.local/bin echo '${base64encode(local.loop_script)}' | base64 -d > ~/.local/bin/claude-runner-loop chmod +x ~/.local/bin/claude-runner-loop diff --git a/freeform/tests/validate.tftest.hcl b/freeform/tests/validate.tftest.hcl index 648d75b..ce6a3c2 100644 --- a/freeform/tests/validate.tftest.hcl +++ b/freeform/tests/validate.tftest.hcl @@ -293,6 +293,10 @@ run "claude_runner_enabled" { condition = strcontains(base64decode(regex("echo '([A-Za-z0-9+/=]+)' \\| base64 -d > ~/.local/bin/claude-runner-loop", coder_agent.main.startup_script)[0]), "--capacity 1") error_message = "each runner must use --capacity 1, which --use-anthropic-git-proxy requires" } + assert { + condition = strcontains(base64decode(regex("echo '([A-Za-z0-9+/=]+)' \\| base64 -d >> ~/.ssh/known_hosts", coder_agent.main.startup_script)[0]), "github.com ssh-ed25519 ") + error_message = "startup script must add GitHub's host keys to known_hosts, or SSH pushes from sessions fail host key verification" + } assert { condition = strcontains(base64decode(regex("echo '([A-Za-z0-9+/=]+)' \\| base64 -d \\| sudo tee /etc/claude-code/managed-settings.d/coder-runner.json", coder_agent.main.startup_script)[0]), "claude-checkout-check /home/coder/workspace") error_message = "startup script must install the SessionStart hook that reports a checkout left dirty by an earlier session" diff --git a/modules/claude-self-hosted-runner/files/README.md b/modules/claude-self-hosted-runner/files/README.md index 44df8fa..4ffafb2 100644 --- a/modules/claude-self-hosted-runner/files/README.md +++ b/modules/claude-self-hosted-runner/files/README.md @@ -37,11 +37,20 @@ directory. The workspace rewrites this README on every start. ## GitHub access -Sessions reach GitHub over HTTPS and `gh` as the GitHub account connected -to the claude.ai account that started them, under Settings → Connectors on -claude.ai. Every person who starts sessions here needs that connection. -SSH remotes are different: they use this workspace's SSH agent, so they act -as the workspace owner for every session. +Sessions clone, fetch and push to `origin` over HTTPS as the GitHub account +connected to the claude.ai account that started them, under Settings → +Connectors on claude.ai. Every person who starts sessions here needs that +connection. The GitHub MCP tools in a session use the same account. + +`gh` in a session is this workspace's own `/usr/bin/gh`. It isn't logged in, +so it doesn't work, and sessions use the GitHub MCP tools instead. Don't run +`gh auth login` or store a `GH_TOKEN` here: every session, whoever started +it, would then act on GitHub as you. + +SSH remotes use this workspace's SSH agent: your forwarded agent, or your +Coder key, which is the same in all your workspaces. SSH pushes act as you +in every session. The workspace adds GitHub's host keys to +`~/.ssh/known_hosts` on start. Every runner that uses this environment secret takes sessions from anyone who can start sessions in the environment, and runs them as this @@ -56,9 +65,8 @@ people you trust with those keys. the session must reconnect GitHub on claude.ai, then start the session again. Until then each runner that picks it up exits and restarts, which is expected. -- `gh auth status` in a session says the token in `GH_TOKEN` is invalid: - expected. Sessions send `gh` through a REST-only proxy with a placeholder - token. `gh api user --jq .login` shows the account a session uses. +- `gh` in a session says it isn't logged in: expected. Sessions use the + GitHub MCP tools. ## Stop the runner diff --git a/modules/claude-self-hosted-runner/files/SKILL.md b/modules/claude-self-hosted-runner/files/SKILL.md index 46ca951..51c59ba 100644 --- a/modules/claude-self-hosted-runner/files/SKILL.md +++ b/modules/claude-self-hosted-runner/files/SKILL.md @@ -129,28 +129,23 @@ never prune Docker images or volumes another session may use. ## GitHub and `gh` -HTTPS git and `gh` act as the GitHub account connected to the claude.ai -account that started this session, through Anthropic's proxy. - -- `gh` here is a per-session wrapper that sets a placeholder token, - `GH_TOKEN=proxy-injected`. `gh auth status` therefore always reports the - token as invalid. Don't report that as a problem. Check access with - `gh api user --jq .login`. -- The proxy serves only GitHub's REST API. `gh pr list`, `gh pr view`, - `gh pr create` and other GraphQL commands fail with HTTP 403. Use - `gh api repos///...` or the GitHub MCP tools. -- Don't call `/usr/bin/gh` directly, and don't set `GH_TOKEN` or - `GITHUB_TOKEN`. Either makes `gh` skip the proxy and act as the login or - token the workspace holds, not as this session's account. -- Don't run `gh auth login`. It stores a login for the whole workspace, - which every later session could use. +HTTPS git (the clone, fetch, and pushes to `origin`) and the GitHub MCP +tools act as the GitHub account connected to the claude.ai account that +started this session, through Anthropic's proxy. + +- `gh` here is the workspace's own `/usr/bin/gh`, which isn't logged in. + Use the GitHub MCP tools for pull requests, issues and the API. Don't + report the missing `gh` login as a problem. +- Don't run `gh auth login`, and don't store or export `GH_TOKEN` or + `GITHUB_TOKEN`. A login or token in this workspace would make every later + session act as that account, whoever started it. ## Pushing over SSH `SSH_AUTH_SOCK` points at the workspace SSH agent relay, `~/.ssh-agent-relay/agent.sock`. The relay uses the workspace owner's own agent when one is forwarded (VS Code, `coder ssh -A`). Otherwise it uses -the Coder workspace key, which GitHub accepts once the owner adds it to +the owner's Coder key, which GitHub accepts once the owner adds it to their account (`coder publickey` prints it). SSH pushes act as the workspace owner, who may not be the person who started this session. @@ -160,7 +155,7 @@ workspace owner, who may not be the person who started this session. attached to the session. - Leave `origin` as the runner cloned it. - `ssh -T git@github.com` greets the account SSH pushes act as. If it - differs from `gh api user --jq .login`, ask the user before pushing over - SSH. + differs from the GitHub account the MCP tools report (`get_me`), ask the + user before pushing over SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys. diff --git a/modules/claude-self-hosted-runner/files/github_known_hosts b/modules/claude-self-hosted-runner/files/github_known_hosts new file mode 100644 index 0000000..f4c560e --- /dev/null +++ b/modules/claude-self-hosted-runner/files/github_known_hosts @@ -0,0 +1,3 @@ +github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl +github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg= +github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk= diff --git a/modules/claude-self-hosted-runner/outputs.tf b/modules/claude-self-hosted-runner/outputs.tf index 02f3e71..a688eb1 100644 --- a/modules/claude-self-hosted-runner/outputs.tf +++ b/modules/claude-self-hosted-runner/outputs.tf @@ -26,6 +26,13 @@ output "startup_script" { # The runner copies ~/.claude into each session when it starts. mkdir -p ~/.claude/skills/coder-shared-workspace ~/.cache "${var.base_dir}" echo '${base64encode(file("${path.module}/files/SKILL.md"))}' | base64 -d > ~/.claude/skills/coder-shared-workspace/SKILL.md + # Without github.com in known_hosts, SSH pushes from sessions fail with + # "Host key verification failed". These are GitHub's published keys. + mkdir -p ~/.ssh + chmod 700 ~/.ssh + if ! ssh-keygen -F github.com >/dev/null 2>&1; then + echo '${base64encode(file("${path.module}/files/github_known_hosts"))}' | base64 -d >> ~/.ssh/known_hosts + fi mkdir -p ~/.local/bin echo '${base64encode(local.loop_script)}' | base64 -d > ~/.local/bin/claude-runner-loop chmod +x ~/.local/bin/claude-runner-loop From 571a2a0c10c6abe19c5f8ae12159462731d40efe Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 15:37:48 +0000 Subject: [PATCH 3/6] fix(runner): ask before SSH pushes when a session has no GitHub tools 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 Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp --- freeform/modules/claude-self-hosted-runner/files/README.md | 3 ++- freeform/modules/claude-self-hosted-runner/files/SKILL.md | 4 ++-- modules/claude-self-hosted-runner/files/README.md | 3 ++- modules/claude-self-hosted-runner/files/SKILL.md | 4 ++-- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md index 4ffafb2..96f2ac0 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -40,7 +40,8 @@ directory. The workspace rewrites this README on every start. Sessions clone, fetch and push to `origin` over HTTPS as the GitHub account connected to the claude.ai account that started them, under Settings → Connectors on claude.ai. Every person who starts sessions here needs that -connection. The GitHub MCP tools in a session use the same account. +connection. The GitHub MCP tools in a session use the same account. A +session started without a repository gets no clone and no GitHub MCP tools. `gh` in a session is this workspace's own `/usr/bin/gh`. It isn't logged in, so it doesn't work, and sessions use the GitHub MCP tools instead. Don't run diff --git a/freeform/modules/claude-self-hosted-runner/files/SKILL.md b/freeform/modules/claude-self-hosted-runner/files/SKILL.md index 51c59ba..03f16b0 100644 --- a/freeform/modules/claude-self-hosted-runner/files/SKILL.md +++ b/freeform/modules/claude-self-hosted-runner/files/SKILL.md @@ -155,7 +155,7 @@ workspace owner, who may not be the person who started this session. attached to the session. - Leave `origin` as the runner cloned it. - `ssh -T git@github.com` greets the account SSH pushes act as. If it - differs from the GitHub account the MCP tools report (`get_me`), ask the - user before pushing over SSH. + differs from the GitHub account the MCP tools report (`get_me`), or the + session has no GitHub MCP tools, ask the user before pushing over SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys. diff --git a/modules/claude-self-hosted-runner/files/README.md b/modules/claude-self-hosted-runner/files/README.md index 4ffafb2..96f2ac0 100644 --- a/modules/claude-self-hosted-runner/files/README.md +++ b/modules/claude-self-hosted-runner/files/README.md @@ -40,7 +40,8 @@ directory. The workspace rewrites this README on every start. Sessions clone, fetch and push to `origin` over HTTPS as the GitHub account connected to the claude.ai account that started them, under Settings → Connectors on claude.ai. Every person who starts sessions here needs that -connection. The GitHub MCP tools in a session use the same account. +connection. The GitHub MCP tools in a session use the same account. A +session started without a repository gets no clone and no GitHub MCP tools. `gh` in a session is this workspace's own `/usr/bin/gh`. It isn't logged in, so it doesn't work, and sessions use the GitHub MCP tools instead. Don't run diff --git a/modules/claude-self-hosted-runner/files/SKILL.md b/modules/claude-self-hosted-runner/files/SKILL.md index 51c59ba..03f16b0 100644 --- a/modules/claude-self-hosted-runner/files/SKILL.md +++ b/modules/claude-self-hosted-runner/files/SKILL.md @@ -155,7 +155,7 @@ workspace owner, who may not be the person who started this session. attached to the session. - Leave `origin` as the runner cloned it. - `ssh -T git@github.com` greets the account SSH pushes act as. If it - differs from the GitHub account the MCP tools report (`get_me`), ask the - user before pushing over SSH. + differs from the GitHub account the MCP tools report (`get_me`), or the + session has no GitHub MCP tools, ask the user before pushing over SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys. From b296a93ab80bdf06644154dd07167d0c0d70edbb Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 15:55:17 +0000 Subject: [PATCH 4/6] docs(runner): recommend a dedicated Coder user for shared runners 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 Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp --- docs/content/workspaces/ai-tools.md | 2 ++ freeform/modules/claude-self-hosted-runner/files/README.md | 5 +++++ modules/claude-self-hosted-runner/files/README.md | 5 +++++ 3 files changed, 12 insertions(+) diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index cf687ad..c22239f 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -145,4 +145,6 @@ An environment is a pool. Every runner that uses its secret, in this workspace o - A session from another person can land in your workspace. It then runs as your Unix user, with your SSH agent, your Coder key, and any `gh` login or credentials stored in the workspace. - Share an environment only with people you would trust with those credentials. Otherwise, give each person their own environment and their own runner workspace. Their SSH pushes then use their own Coder key. +- **For a runner your whole organization shares, let a dedicated Coder user own the workspace,** such as `ddev-runner`, and don't add that user's Coder key to anyone's GitHub account. Even among trusted people, a session that pushes over SSH as the workspace owner is easy to miss. Without that key on GitHub, sessions push only over HTTPS, as the person who started them. To push to a fork, a session attaches the fork with push access. A template setting can't prevent this: any process in a workspace can use the owner's Coder key, through `coder gitssh` or the workspace agent. +- **Don't connect to a shared runner workspace with a forwarded SSH agent.** Sessions could then sign with every key on your computer while you stay connected. - Use a separate environment for each kind of runner you want to choose between, for example one per operating system. Sessions go to whichever runner is free, with no routing by label or platform. diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md index 96f2ac0..245ac14 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -58,6 +58,11 @@ who can start sessions in the environment, and runs them as this workspace's user, with its SSH agent. Share the environment only with people you trust with those keys. +For a runner your whole organization shares, let a dedicated Coder user own +the workspace, and don't add its Coder key to anyone's GitHub account. +Sessions then push only over HTTPS, as the person who started them. Don't +connect to a shared runner workspace with a forwarded SSH agent. + ## Troubleshooting - A session fails before Claude starts, and the log shows diff --git a/modules/claude-self-hosted-runner/files/README.md b/modules/claude-self-hosted-runner/files/README.md index 96f2ac0..245ac14 100644 --- a/modules/claude-self-hosted-runner/files/README.md +++ b/modules/claude-self-hosted-runner/files/README.md @@ -58,6 +58,11 @@ who can start sessions in the environment, and runs them as this workspace's user, with its SSH agent. Share the environment only with people you trust with those keys. +For a runner your whole organization shares, let a dedicated Coder user own +the workspace, and don't add its Coder key to anyone's GitHub account. +Sessions then push only over HTTPS, as the person who started them. Don't +connect to a shared runner workspace with a forwarded SSH agent. + ## Troubleshooting - A session fails before Claude starts, and the log shows From 8943c5c67e8cd2ce5170e4fa77353d5014374a62 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 15:59:57 +0000 Subject: [PATCH 5/6] docs(runner): say a runner workspace is personal 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 Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp --- docs/content/workspaces/ai-tools.md | 8 +++----- .../claude-self-hosted-runner/files/README.md | 13 ++++--------- modules/claude-self-hosted-runner/files/README.md | 13 ++++--------- 3 files changed, 11 insertions(+), 23 deletions(-) diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index c22239f..1a5cb47 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -141,10 +141,8 @@ The runner uses Anthropic-managed git. A session reaches GitHub in three ways, a ### Who can use the runner -An environment is a pool. Every runner that uses its secret, in this workspace or any other, takes the next session from anyone who can start sessions in that environment, such as other members of your claude.ai organization. The runner's label decides nothing. +**A runner workspace is personal. Don't share its environment.** An environment is a pool: every runner that uses its secret, in this workspace or any other, takes the next session from anyone who can start sessions in that environment. The runner's label decides nothing. -- A session from another person can land in your workspace. It then runs as your Unix user, with your SSH agent, your Coder key, and any `gh` login or credentials stored in the workspace. -- Share an environment only with people you would trust with those credentials. Otherwise, give each person their own environment and their own runner workspace. Their SSH pushes then use their own Coder key. -- **For a runner your whole organization shares, let a dedicated Coder user own the workspace,** such as `ddev-runner`, and don't add that user's Coder key to anyone's GitHub account. Even among trusted people, a session that pushes over SSH as the workspace owner is easy to miss. Without that key on GitHub, sessions push only over HTTPS, as the person who started them. To push to a fork, a session attaches the fork with push access. A template setting can't prevent this: any process in a workspace can use the owner's Coder key, through `coder gitssh` or the workspace agent. -- **Don't connect to a shared runner workspace with a forwarded SSH agent.** Sessions could then sign with every key on your computer while you stay connected. +- A session from another person would run as your Unix user, with your SSH agent, your Coder key, and any credentials stored in the workspace. Its SSH pushes would act as you, and no template setting can prevent that: any process in a workspace can use the owner's Coder key, through `coder gitssh` or the workspace agent. +- Each person who wants a runner creates their own environment and their own runner workspace. - Use a separate environment for each kind of runner you want to choose between, for example one per operating system. Sessions go to whichever runner is free, with no routing by label or platform. diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md index 245ac14..a5151fe 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -53,15 +53,10 @@ Coder key, which is the same in all your workspaces. SSH pushes act as you in every session. The workspace adds GitHub's host keys to `~/.ssh/known_hosts` on start. -Every runner that uses this environment secret takes sessions from anyone -who can start sessions in the environment, and runs them as this -workspace's user, with its SSH agent. Share the environment only with -people you trust with those keys. - -For a runner your whole organization shares, let a dedicated Coder user own -the workspace, and don't add its Coder key to anyone's GitHub account. -Sessions then push only over HTTPS, as the person who started them. Don't -connect to a shared runner workspace with a forwarded SSH agent. +This runner is personal. Every runner that uses this environment secret +takes sessions from anyone who can start sessions in the environment, and +runs them as you, with your SSH agent and Coder key. Don't share the +environment with other people. ## Troubleshooting diff --git a/modules/claude-self-hosted-runner/files/README.md b/modules/claude-self-hosted-runner/files/README.md index 245ac14..a5151fe 100644 --- a/modules/claude-self-hosted-runner/files/README.md +++ b/modules/claude-self-hosted-runner/files/README.md @@ -53,15 +53,10 @@ Coder key, which is the same in all your workspaces. SSH pushes act as you in every session. The workspace adds GitHub's host keys to `~/.ssh/known_hosts` on start. -Every runner that uses this environment secret takes sessions from anyone -who can start sessions in the environment, and runs them as this -workspace's user, with its SSH agent. Share the environment only with -people you trust with those keys. - -For a runner your whole organization shares, let a dedicated Coder user own -the workspace, and don't add its Coder key to anyone's GitHub account. -Sessions then push only over HTTPS, as the person who started them. Don't -connect to a shared runner workspace with a forwarded SSH agent. +This runner is personal. Every runner that uses this environment secret +takes sessions from anyone who can start sessions in the environment, and +runs them as you, with your SSH agent and Coder key. Don't share the +environment with other people. ## Troubleshooting From 45ed4ba68f9536731c15e0f5bcf697001fdcb48d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 16:21:07 +0000 Subject: [PATCH 6/6] docs(runner): recommend a gh login on a personal runner 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 Claude-Session: https://claude.ai/code/session_01T3Cc2FfNKgEMqAZMMRVvjp --- docs/content/workspaces/ai-tools.md | 8 +++--- .../claude-self-hosted-runner/files/README.md | 14 ++++++----- .../claude-self-hosted-runner/files/SKILL.md | 25 +++++++++++-------- .../claude-self-hosted-runner/files/README.md | 14 ++++++----- .../claude-self-hosted-runner/files/SKILL.md | 25 +++++++++++-------- 5 files changed, 51 insertions(+), 35 deletions(-) diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index 1a5cb47..9c9f01f 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -126,16 +126,18 @@ On every start, the runner runs in the `tmux` session `claude-runner` (`tmux att ### Who acts on GitHub -The runner uses Anthropic-managed git. A session reaches GitHub in three ways, and only two of them follow the person who started it: +The runner uses Anthropic-managed git. A session reaches GitHub in four ways. Two of them act as the account that started the session, and two act as you, the workspace owner: | Path | Acts as | |---|---| | HTTPS git: the clone, fetch, and pushes to `origin` | The GitHub account connected to the claude.ai account that started the session | | The GitHub MCP tools in a session | The same connected account, through Anthropic's proxy | +| `gh` | Whoever is logged in to `gh` in the workspace: you, after `gh auth login`. Without a login, `gh` doesn't work. | | SSH remotes (`git@github.com:…`) | Every key in the workspace SSH agent: the workspace owner's forwarded agent, or the owner's Coder key | -- **Everyone who starts sessions must connect GitHub** in claude.ai, under **Settings → Connectors → GitHub**. Nothing in the workspace stands in for it. When the connection is missing or has expired, the session fails before Claude starts, and `/tmp/claude-runner-.log` shows `Repository access validation failed` with `GitHub authentication required. Please reconnect your GitHub account.` Reconnect, then start the session again. Until then the runner exits and restarts after each attempt, and the session may be retried on other runners. -- **`gh` in a session is the workspace's own `gh`.** Sessions don't get a `gh` that acts as their own account; they use the GitHub MCP tools instead. On a runner workspace with no `gh` login, `gh` reports that it isn't logged in, which is expected. If you run `gh auth login`, or store a `GH_TOKEN` or `GITHUB_TOKEN`, in the workspace, every session uses that login, whoever started it. Don't do that in a workspace that other people's sessions use. +- **Connect GitHub** in claude.ai, under **Settings → Connectors → GitHub**. Nothing in the workspace stands in for it. When the connection is missing or has expired, the session fails before Claude starts, and `/tmp/claude-runner-.log` shows `Repository access validation failed` with `GitHub authentication required. Please reconnect your GitHub account.` Reconnect, then start the session again. Until then the runner exits and restarts after each attempt, and the session may be retried on other runners. +- **Log in to `gh` once in the workspace** with `gh auth login`. Sessions then use your login for `gh`, with GraphQL and every repository you can reach. Without a login, sessions use the GitHub MCP tools, which reach only the repositories attached to the session. +- **Tell Claude to use `gh`.** Claude's built-in instructions in a runner session prefer the GitHub MCP tools, and use `gh` only when your own instructions name it. Add a line such as "Use `gh` for GitHub operations; it is logged in as me." to `~/.claude/CLAUDE.md`. The runner copies `~/.claude` into every session. - **Your Coder key is the same in all your workspaces.** `coder publickey` prints one key per Coder user, so adding it to GitHub lets SSH push as you from every runner workspace you own, for every session on it. - **SSH offers every key the agent holds.** With an agent forwarded from your computer, sessions can sign with all of its keys, not only your GitHub key, for as long as you stay connected. diff --git a/freeform/modules/claude-self-hosted-runner/files/README.md b/freeform/modules/claude-self-hosted-runner/files/README.md index a5151fe..86ca76b 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -43,10 +43,12 @@ Connectors on claude.ai. Every person who starts sessions here needs that connection. The GitHub MCP tools in a session use the same account. A session started without a repository gets no clone and no GitHub MCP tools. -`gh` in a session is this workspace's own `/usr/bin/gh`. It isn't logged in, -so it doesn't work, and sessions use the GitHub MCP tools instead. Don't run -`gh auth login` or store a `GH_TOKEN` here: every session, whoever started -it, would then act on GitHub as you. +`gh` in a session is this workspace's own `gh`. Run `gh auth login` here +once, and sessions use your login, with GraphQL and every repository you +can reach. Then add a line such as "Use `gh` for GitHub operations; it is +logged in as me." to `~/.claude/CLAUDE.md`, because sessions use `gh` only +when your instructions say so. Without a login, sessions use the GitHub MCP +tools, which reach only the repositories attached to the session. SSH remotes use this workspace's SSH agent: your forwarded agent, or your Coder key, which is the same in all your workspaces. SSH pushes act as you @@ -66,8 +68,8 @@ environment with other people. the session must reconnect GitHub on claude.ai, then start the session again. Until then each runner that picks it up exits and restarts, which is expected. -- `gh` in a session says it isn't logged in: expected. Sessions use the - GitHub MCP tools. +- `gh` in a session says it isn't logged in: run `gh auth login` in the + workspace, or let sessions use the GitHub MCP tools. ## Stop the runner diff --git a/freeform/modules/claude-self-hosted-runner/files/SKILL.md b/freeform/modules/claude-self-hosted-runner/files/SKILL.md index 03f16b0..120bc4a 100644 --- a/freeform/modules/claude-self-hosted-runner/files/SKILL.md +++ b/freeform/modules/claude-self-hosted-runner/files/SKILL.md @@ -131,14 +131,18 @@ never prune Docker images or volumes another session may use. HTTPS git (the clone, fetch, and pushes to `origin`) and the GitHub MCP tools act as the GitHub account connected to the claude.ai account that -started this session, through Anthropic's proxy. +started this session, through Anthropic's proxy. The MCP tools reach only +the repositories attached to the session. -- `gh` here is the workspace's own `/usr/bin/gh`, which isn't logged in. - Use the GitHub MCP tools for pull requests, issues and the API. Don't - report the missing `gh` login as a problem. -- Don't run `gh auth login`, and don't store or export `GH_TOKEN` or - `GITHUB_TOKEN`. A login or token in this workspace would make every later - session act as that account, whoever started it. +`gh` here is the workspace's own `gh`, and acts as whoever logged it in, +normally the workspace owner. + +- Run `gh auth status`. With a login, `gh` works fully, GraphQL included, + for every repository that account can reach. Use it when the user's + instructions say to. +- Without a login, use the GitHub MCP tools. Don't report the missing + login as a problem, and don't run `gh auth login` or set `GH_TOKEN` + yourself; that is the user's decision. ## Pushing over SSH @@ -154,8 +158,9 @@ workspace owner, who may not be the person who started this session. through the session's git proxy, which reaches only the repositories attached to the session. - Leave `origin` as the runner cloned it. -- `ssh -T git@github.com` greets the account SSH pushes act as. If it - differs from the GitHub account the MCP tools report (`get_me`), or the - session has no GitHub MCP tools, ask the user before pushing over SSH. +- `ssh -T git@github.com` greets the account SSH pushes act as. Compare it + with the account the MCP tools report (`get_me`), or with + `gh api user --jq .login` when `gh` has a login. If they differ, or you + have neither to compare, ask the user before pushing over SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys. diff --git a/modules/claude-self-hosted-runner/files/README.md b/modules/claude-self-hosted-runner/files/README.md index a5151fe..86ca76b 100644 --- a/modules/claude-self-hosted-runner/files/README.md +++ b/modules/claude-self-hosted-runner/files/README.md @@ -43,10 +43,12 @@ Connectors on claude.ai. Every person who starts sessions here needs that connection. The GitHub MCP tools in a session use the same account. A session started without a repository gets no clone and no GitHub MCP tools. -`gh` in a session is this workspace's own `/usr/bin/gh`. It isn't logged in, -so it doesn't work, and sessions use the GitHub MCP tools instead. Don't run -`gh auth login` or store a `GH_TOKEN` here: every session, whoever started -it, would then act on GitHub as you. +`gh` in a session is this workspace's own `gh`. Run `gh auth login` here +once, and sessions use your login, with GraphQL and every repository you +can reach. Then add a line such as "Use `gh` for GitHub operations; it is +logged in as me." to `~/.claude/CLAUDE.md`, because sessions use `gh` only +when your instructions say so. Without a login, sessions use the GitHub MCP +tools, which reach only the repositories attached to the session. SSH remotes use this workspace's SSH agent: your forwarded agent, or your Coder key, which is the same in all your workspaces. SSH pushes act as you @@ -66,8 +68,8 @@ environment with other people. the session must reconnect GitHub on claude.ai, then start the session again. Until then each runner that picks it up exits and restarts, which is expected. -- `gh` in a session says it isn't logged in: expected. Sessions use the - GitHub MCP tools. +- `gh` in a session says it isn't logged in: run `gh auth login` in the + workspace, or let sessions use the GitHub MCP tools. ## Stop the runner diff --git a/modules/claude-self-hosted-runner/files/SKILL.md b/modules/claude-self-hosted-runner/files/SKILL.md index 03f16b0..120bc4a 100644 --- a/modules/claude-self-hosted-runner/files/SKILL.md +++ b/modules/claude-self-hosted-runner/files/SKILL.md @@ -131,14 +131,18 @@ never prune Docker images or volumes another session may use. HTTPS git (the clone, fetch, and pushes to `origin`) and the GitHub MCP tools act as the GitHub account connected to the claude.ai account that -started this session, through Anthropic's proxy. +started this session, through Anthropic's proxy. The MCP tools reach only +the repositories attached to the session. -- `gh` here is the workspace's own `/usr/bin/gh`, which isn't logged in. - Use the GitHub MCP tools for pull requests, issues and the API. Don't - report the missing `gh` login as a problem. -- Don't run `gh auth login`, and don't store or export `GH_TOKEN` or - `GITHUB_TOKEN`. A login or token in this workspace would make every later - session act as that account, whoever started it. +`gh` here is the workspace's own `gh`, and acts as whoever logged it in, +normally the workspace owner. + +- Run `gh auth status`. With a login, `gh` works fully, GraphQL included, + for every repository that account can reach. Use it when the user's + instructions say to. +- Without a login, use the GitHub MCP tools. Don't report the missing + login as a problem, and don't run `gh auth login` or set `GH_TOKEN` + yourself; that is the user's decision. ## Pushing over SSH @@ -154,8 +158,9 @@ workspace owner, who may not be the person who started this session. through the session's git proxy, which reaches only the repositories attached to the session. - Leave `origin` as the runner cloned it. -- `ssh -T git@github.com` greets the account SSH pushes act as. If it - differs from the GitHub account the MCP tools report (`get_me`), or the - session has no GitHub MCP tools, ask the user before pushing over SSH. +- `ssh -T git@github.com` greets the account SSH pushes act as. Compare it + with the account the MCP tools report (`get_me`), or with + `gh api user --jq .login` when `gh` has a login. If they differ, or you + have neither to compare, ask the user before pushing over SSH. - On `Permission denied (publickey)`, ask the user to forward an agent or add the Coder key to GitHub. Never create, copy or print keys.