3.4 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 a file under /run 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 /run/hive-agent-github-token/token
(0400, owned by the agent), on every start 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.
/run starts empty on every start, so the unit fetches the token anew each
time: an agent whose token you removed from the store has none after its next
start. When the
store doesn't answer at start, the agent boots and runs without a GitHub
token (gh and git push run unauthenticated, the unit logs one warning),
and the unit asks again until the store answers. Nothing reads the
<state>/github-token file an earlier version kept, and nothing deletes it;
it stays on disk, unused. 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.