72 lines
2.9 KiB
Markdown
72 lines
2.9 KiB
Markdown
# 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).
|