97671e28d5
Three handbook pages carried sections an operator never reads, named after source paths and build internals. They move to pages under 4-implementation, and each handbook page keeps a short pointer. - forge.md: the notification poller (what it polls, how it formats, de-duplicates and marks notifications read) is now agent-tools/forge-notify.md. The forge page keeps a short Notifications section. - matrix.md: the retired hive-side matrix code, the evaluation assertions and the fluffychat-web build fixes are now networking/matrix-homeserver.md. - github.md: the Implementation section (how `gh` and `git push` authenticate, and the GitHub poller) is now agent-tools/github.md. docs/README.md and the agent-tools README list the new pages, and AGENTS.md's note on mixed operator and implementation docs now says to move the detail and leave a pointer.
3 KiB
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: link a PAT to the agent in the swarm UI and it works. No per-agent nix declaration, no rebuild — the agent fetches the token from the swarm secret store itself.
Enabling
The integration is on by default for every agent (services.hyperhive.agent.github.enable = true), inert until the operator provisions a PAT. No per-agent declaration is
needed — an agent gains GitHub by having a PAT stored for it.
To turn it off for the whole swarm, set the swarm option:
services.hyperhive.swarm.github.enable = false;
hive-c0re's meta-flake renderer then injects services.hyperhive.agent.github.enable = false
into every agent, so no agent ships the gh wrapper, the credential helper
or the token fetch.
(services.hyperhive.agent.github.enable also exists per-agent for completeness, but the
swarm-wide switch is the intended control.)
github.com only. The token value never touches nix — the agent writes it
to <state>/github-token at runtime (see Provisioning).
Provisioning
The PAT is operator-supplied. In the swarm UI,
open the agent on /agents, choose link github account and paste the PAT
(PUT /api/hives/{hive}/agents/{agent}/github-account). swarm-controller
stores it at swarm/agents/<agent>/github-token in the swarm secret store;
no hive writes it. One token per agent: swarm-controller refuses to link
another until you delete the stored one, and no route hands it back.
The agent's hive-agent-github-token unit reads that path under the
agent's own store certificate and writes <state>/github-token (0600,
owned by the agent), on boot and every two minutes, replacing the file only
when the token changed. It needs a store identity
(services.hyperhive.agent.bao.addr); an agent without one gets no token.
The unit never deletes the file: a github-token already in place stays
when the store holds none or doesn't answer. Where the token lives and who
reads it: credentials-reference.md.
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.
How it works
How the agent's gh and git push authenticate, and how its GitHub
notification poller works, is in
the implementation page.