diff --git a/docs/content/workspaces/ai-tools.md b/docs/content/workspaces/ai-tools.md index 27aa09e..9c9f01f 100644 --- a/docs/content/workspaces/ai-tools.md +++ b/docs/content/workspaces/ai-tools.md @@ -120,6 +120,31 @@ 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 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 + +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 | + +- **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. + +### Who can use the runner + +**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 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 7169646..86ca76b 100644 --- a/freeform/modules/claude-self-hosted-runner/files/README.md +++ b/freeform/modules/claude-self-hosted-runner/files/README.md @@ -35,6 +35,42 @@ 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 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. A +session started without a repository gets no clone and no GitHub MCP tools. + +`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 +in every session. The workspace adds GitHub's host keys to +`~/.ssh/known_hosts` on start. + +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 + +- 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` 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 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..120bc4a 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 (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. The MCP tools reach only +the repositories attached to the session. + +`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 `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 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. - 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. 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/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 7169646..86ca76b 100644 --- a/modules/claude-self-hosted-runner/files/README.md +++ b/modules/claude-self-hosted-runner/files/README.md @@ -35,6 +35,42 @@ 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 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. A +session started without a repository gets no clone and no GitHub MCP tools. + +`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 +in every session. The workspace adds GitHub's host keys to +`~/.ssh/known_hosts` on start. + +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 + +- 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` 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 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..120bc4a 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 (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. The MCP tools reach only +the repositories attached to the session. + +`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 `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 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. - 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. 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/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