80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# GitHub accounts
|
|
|
|
Give an agent a managed GitHub identity — a `gh` CLI and `git push` over
|
|
HTTPS, both authenticated by an operator-supplied personal access token
|
|
(PAT) — so it can run GitHub API calls and push commits without any manual
|
|
`gh auth login`.
|
|
|
|
Provisioning is UI-driven, mirroring the dashboard side of the
|
|
[matrix account](matrix.md) flow: paste a PAT into the agent's credentials
|
|
tab and it works. No per-agent nix declaration, no rebuild — the token is
|
|
injected into the agent's state dir out of band.
|
|
|
|
## Enabling
|
|
|
|
The integration is **on by default** for every agent (`hyperhive.github.enable
|
|
= true`), inert until a PAT is provisioned. There is nothing per-agent to
|
|
declare — an agent gains GitHub simply by having a PAT written to its token
|
|
file.
|
|
|
|
To turn it off for the whole hive, set the host option:
|
|
|
|
```nix
|
|
services.hyperhive.github.enable = false;
|
|
```
|
|
|
|
hive-c0re's meta-flake renderer then injects `hyperhive.github.enable = false`
|
|
into every agent, so no agent ships the `gh` wrapper or credential helper.
|
|
(`hyperhive.github.enable` also exists per-agent for completeness, but the
|
|
hive-wide host switch is the intended control.)
|
|
|
|
github.com only. The token **value** never touches nix — it is written to
|
|
`<state>/github-token` separately (see [Provisioning](#provisioning)).
|
|
|
|
## How the agent uses it
|
|
|
|
When enabled, the container gets:
|
|
|
|
- **A `gh` wrapper** on `PATH` (shadowing the raw `gh`) that exports
|
|
`GH_TOKEN` from the token file at invocation, then execs real `gh`. So
|
|
`gh pr create`, `gh api …`, etc. just work — `gh` derives the identity
|
|
from the token.
|
|
- **A git credential helper** (`git-credential-hive-github`), wired via a
|
|
host-scoped `/etc/gitconfig` entry for `https://github.com`, so
|
|
`git push https://github.com/<owner>/<repo>` authenticates as
|
|
`x-access-token` + the PAT (GitHub ignores the username for PAT auth).
|
|
Host-scoped, so it never touches the forge (`localhost:3000`) or any
|
|
other remote.
|
|
|
|
Both scripts read the token from `<state>/github-token` **at invocation
|
|
time**, so a PAT written (or rotated) mid-session takes effect immediately
|
|
— no container rebuild or restart. Until the file exists, `gh` / `git push`
|
|
simply fail unauthenticated. The token path is baked into the scripts at
|
|
build time (not read from an env var), because claude's Bash tool runs in a
|
|
minimal environment that wouldn't carry one.
|
|
|
|
## Provisioning
|
|
|
|
The PAT is operator-supplied. The primary path is the **dashboard
|
|
credentials tab** (github sub-tab): paste the PAT for an agent and submit
|
|
(`POST /api/github-account`). There is also a CLI path for
|
|
recovery/scripting:
|
|
|
|
```sh
|
|
hivectl github set-token <agent> --token-stdin # paste the PAT on stdin (preferred)
|
|
hivectl github set-token <agent> --token <pat> # inline (visible in shell history)
|
|
```
|
|
|
|
Either path has hive-c0re delegate the write to hive-priv, which stores the
|
|
file `0600` owned by the agent (so the container can read it) — the same
|
|
credential-injection path as forge/matrix tokens. See
|
|
[hivectl → GitHub](tools/hivectl.md#github).
|
|
|
|
## Security
|
|
|
|
- Use a **dedicated bot account**, never a human's.
|
|
- Mint a **minimally-scoped PAT** — only the repos/scopes the agent's
|
|
workflow needs. Agents have passwordless sudo, so a compromised or
|
|
hallucinating agent can act as the account within the token's scopes;
|
|
scope is the real blast-radius limiter, and the container boundary is
|
|
the enforcement. See [security.md](security.md).
|