docs(#1970): rewrite for UI-driven shape (github.enable + host switch), purge githubAccount refs, regen hivectl-cli.md
This commit is contained in:
damocles
mara
parent
18965ff7bd
commit
cef9e633f7
7 changed files with 61 additions and 52 deletions
|
|
@ -1,47 +1,51 @@
|
|||
# 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`.
|
||||
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`.
|
||||
|
||||
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.
|
||||
Provisioning is UI-driven, mirroring the dashboard side of the
|
||||
[matrix account](matrix.md) flow: paste a PAT into the agent's credentials
|
||||
tab and it works. No per-agent nix declaration, no rebuild — the token is
|
||||
injected into the agent's state dir out of band.
|
||||
|
||||
## Config option
|
||||
## Enabling
|
||||
|
||||
Declare `hyperhive.githubAccount` in the agent's `agent.nix`:
|
||||
The integration is **on by default** for every agent (`hyperhive.github.enable
|
||||
= true`), inert until a PAT is provisioned. There is nothing per-agent to
|
||||
declare — an agent gains GitHub simply by having a PAT written to its token
|
||||
file.
|
||||
|
||||
To turn it off for the whole hive, set the host option:
|
||||
|
||||
```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
|
||||
};
|
||||
services.hyperhive.github.enable = false;
|
||||
```
|
||||
|
||||
`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".
|
||||
hive-c0re's meta-flake renderer then injects `hyperhive.github.enable = false`
|
||||
into every agent, so no agent ships the `gh` wrapper or credential helper.
|
||||
(`hyperhive.github.enable` also exists per-agent for completeness, but the
|
||||
hive-wide host switch is the intended control.)
|
||||
|
||||
The token **value** is never in nix. `tokenFile` only names the path; the
|
||||
PAT is written there separately (see [Provisioning](#provisioning)).
|
||||
github.com only. The token **value** never touches nix — it is written to
|
||||
`<state>/github-token` separately (see [Provisioning](#provisioning)).
|
||||
|
||||
## How the agent uses it
|
||||
|
||||
When `githubAccount` is set, the container gets:
|
||||
When enabled, 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.
|
||||
`gh pr create`, `gh api …`, etc. just work — `gh` derives the identity
|
||||
from the token.
|
||||
- **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 `/etc/gitconfig` entry for `https://github.com`, so
|
||||
`git push https://github.com/<owner>/<repo>` authenticates as
|
||||
`x-access-token` + the PAT (GitHub ignores the username for PAT auth).
|
||||
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`.
|
||||
- **Env**: `HIVE_GITHUB_TOKEN_FILE` (the token path — never the secret).
|
||||
|
||||
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
|
||||
|
|
@ -50,16 +54,19 @@ exists, `gh` / `git push` simply fail unauthenticated.
|
|||
|
||||
## Provisioning
|
||||
|
||||
The PAT is operator-supplied. Write it into the agent's token file with:
|
||||
The PAT is operator-supplied. The primary path is the **dashboard
|
||||
credentials tab** (github sub-tab): paste the PAT for an agent and submit
|
||||
(`POST /api/github-account`). There is also a CLI path for
|
||||
recovery/scripting:
|
||||
|
||||
```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
|
||||
Either path has hive-c0re delegate 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue