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.
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](../../4-implementation/web-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](../../4-implementation/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).
|