4adbc939f2
The page-by-page and control-by-control description of the swarm UI moves to 4-implementation/web-ui/swarm-ui.md, with the quick-links wiring. The handbook page keeps the route table, how to reach the UI, who may and what the browser keeps. Links to the moved sections point at the new page.
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.