74 lines
3.4 KiB
Markdown
74 lines
3.4 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 a file under `/run` 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 `/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](../../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).
|