# GitHub accounts

Give an agent a managed GitHub identity — a `gh` CLI and `git push` over
HTTPS, both authenticated as a configured bot account — so it can run
GitHub API calls and push commits without any manual `gh auth login`.

This mirrors the [matrix account](matrix.md) pattern: nix carries the
login + host, never the secret; an operator-supplied personal access
token (PAT) is injected out of band into the agent's state dir.

## Config option

Declare `hyperhive.githubAccount` in the agent's `agent.nix`:

```nix
hyperhive.githubAccount = {
  username = "the-sword-above";                       # the bot login
  tokenFile = "/agents/<name>/state/github-token";    # where the PAT lives
  # host = "github.com";                              # default; set for GHE
};
```

`null` (the default) leaves GitHub off entirely — no `gh` wrapper, no
credential helper, no env. Single account per agent by design (unlike
`matrixAccounts`, which is multi-account): the workflow is "this agent is
this one bot".

The token **value** is never in nix. `tokenFile` only names the path; the
PAT is written there separately (see [Provisioning](#provisioning)).

## How the agent uses it

When `githubAccount` is set, the container gets:

- **A `gh` wrapper** on `PATH` (shadowing the raw `gh`) that exports
  `GH_TOKEN` from the token file at invocation, then execs real `gh`. So
  `gh pr create`, `gh api …`, etc. just work as the bot.
- **A git credential helper** (`git-credential-hive-github`), wired via a
  host-scoped `/etc/gitconfig` entry for `https://<host>`, so
  `git push https://github.com/<owner>/<repo>` authenticates as the bot.
  Host-scoped, so it never touches the forge (`localhost:3000`) or any
  other remote.
- **Env**: `HIVE_GITHUB_USER`, `HIVE_GITHUB_HOST`,
  `HIVE_GITHUB_TOKEN_FILE`, and `GH_HOST`.

Both the wrapper and the credential helper read the token from the file
**at invocation time**, so a PAT written (or rotated) mid-session takes
effect immediately — no container rebuild or restart. Until the file
exists, `gh` / `git push` simply fail unauthenticated.

## Provisioning

The PAT is operator-supplied. Write it into the agent's token file with:

```sh
hivectl github set-token <agent> --token-stdin   # paste the PAT on stdin (preferred)
hivectl github set-token <agent> --token <pat>    # inline (visible in shell history)
```

hive-c0re delegates the write to hive-priv, which stores the file `0600`
owned by the agent (so the container can read it) — the same credential
injection path as forge/matrix tokens. See
[hivectl → GitHub](tools/hivectl.md#github).

## 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](security.md).