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.
68 lines
3 KiB
Markdown
68 lines
3 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: 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
|
|
|
|
<!-- vale write-good.Passive = NO -->
|
|
|
|
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.
|
|
|
|
<!-- vale write-good.Passive = YES -->
|
|
|
|
To turn it off for the whole swarm, set the swarm option:
|
|
|
|
```nix
|
|
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)).
|
|
|
|
## Provisioning
|
|
|
|
The PAT is operator-supplied. In the [swarm UI](../swarm/ui.md#linking-external-accounts),
|
|
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](../swarm/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](../agents/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](../../4-implementation/agent-tools/github.md).
|