# 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).