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
12
README.md
12
README.md
|
|
@ -120,17 +120,15 @@ For more details see [`docs/matrix.md`](docs/matrix.md).
|
|||
|
||||
### GitHub account
|
||||
|
||||
`hyperhive.githubAccount` gives an agent a managed GitHub identity — a `gh` CLI wrapper and `git push` over HTTPS, both authenticated as a configured bot account:
|
||||
Every agent gets a managed GitHub identity — a `gh` CLI wrapper and `git push` over HTTPS — on by default (`hyperhive.github.enable`), inert until a PAT is provisioned. There is nothing per-agent to declare: paste an operator-supplied personal access token into the agent's dashboard **credentials** tab (or `hivectl github set-token <agent> --token-stdin`) and it works. The `gh` wrapper + git credential helper read the token live (git auths as `x-access-token` + the PAT; github.com only), so a rotated PAT takes effect with no rebuild.
|
||||
|
||||
Turn the integration off for the whole hive with the host option:
|
||||
|
||||
```nix
|
||||
hyperhive.githubAccount = {
|
||||
username = "the-sword-above";
|
||||
tokenFile = "/agents/myagent/state/github-token"; # PAT provisioned out-of-band
|
||||
# host = "github.com"; # default; set for GHE
|
||||
};
|
||||
services.hyperhive.github.enable = false;
|
||||
```
|
||||
|
||||
The PAT value is never in nix; write it with `hivectl github set-token <agent> --token-stdin`. Both the `gh` wrapper and the git credential helper read the token live, so a rotated PAT takes effect with no rebuild. Single account per agent. For more details see [`docs/github.md`](docs/github.md).
|
||||
The PAT value is never in nix — only the enable flag. For more details see [`docs/github.md`](docs/github.md).
|
||||
|
||||
## Operator CLI
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
|
|||
|
||||
* `forge` — Forgejo user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (`forge::ensure_all`) — useful for recovery, ad-hoc reprovisioning, or single-agent fixes without bouncing the daemon
|
||||
* `matrix` — matrix-tuwunel user provisioning. Manual entry point to the same idempotent flow c0re runs automatically at boot (`matrix::ensure_all`) — useful when the boot-time sweep skipped an agent (e.g. matrix container wasn't up yet) or to re-register after wiping a token file
|
||||
* `github` — GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's `hyperhive.githubAccount` token file so its `gh` wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account
|
||||
* `github` — GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's `github-token` state file so its `gh` wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the integration is on by default (`hyperhive.github.enable`), so no per-agent config is needed
|
||||
* `gateway` — Gateway htpasswd user management. Add, remove, or list users in an htpasswd file used by the gateway's HTTP Basic auth (`services.hyperhive.gateway.auth`). Credentials are stored as `BCrypt` hashes — no extra service or PAM required
|
||||
* `agents` — Agent container management. Requires the hive-c0re daemon to be running (connects to the host admin socket)
|
||||
* `wg` — WireGuard inter-hive mesh setup helpers (`services.hyperhive.swarm`)
|
||||
|
|
@ -199,19 +199,19 @@ Invite a matrix user to the hive Space (default) or a specific room. Uses the hi
|
|||
|
||||
## `hivectl github`
|
||||
|
||||
GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's `hyperhive.githubAccount` token file so its `gh` wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account
|
||||
GitHub account provisioning: write an operator-supplied personal access token (PAT) into an agent's `github-token` state file so its `gh` wrapper + git credential helper can authenticate. Unlike forge/matrix there is no account creation — the operator supplies a PAT for an existing GitHub account. A CLI alternative to the dashboard credentials tab; the integration is on by default (`hyperhive.github.enable`), so no per-agent config is needed
|
||||
|
||||
**Usage:** `hivectl github <COMMAND>`
|
||||
|
||||
###### **Subcommands:**
|
||||
|
||||
* `set-token` — Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600, agent-owned) via hive-priv. The agent must declare `hyperhive.githubAccount` (its `tokenFile` pointing at this path) for the `gh` wrapper + git credential helper to pick it up. The token is read live at invocation, so no rebuild/restart is needed. Prefer `--token-stdin`: an inline `--token` is visible in shell history + process listings
|
||||
* `set-token` — Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600, agent-owned) via hive-priv. The GitHub integration is on by default (`hyperhive.github.enable`), so the `gh` wrapper + git credential helper pick the token up with no per-agent config. The token is read live at invocation, so no rebuild/restart is needed. Prefer `--token-stdin`: an inline `--token` is visible in shell history + process listings
|
||||
|
||||
|
||||
|
||||
## `hivectl github set-token`
|
||||
|
||||
Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600, agent-owned) via hive-priv. The agent must declare `hyperhive.githubAccount` (its `tokenFile` pointing at this path) for the `gh` wrapper + git credential helper to pick it up. The token is read live at invocation, so no rebuild/restart is needed. Prefer `--token-stdin`: an inline `--token` is visible in shell history + process listings
|
||||
Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600, agent-owned) via hive-priv. The GitHub integration is on by default (`hyperhive.github.enable`), so the `gh` wrapper + git credential helper pick the token up with no per-agent config. The token is read live at invocation, so no rebuild/restart is needed. Prefer `--token-stdin`: an inline `--token` is visible in shell history + process listings
|
||||
|
||||
**Usage:** `hivectl github set-token [OPTIONS] <AGENT>`
|
||||
|
||||
|
|
|
|||
|
|
@ -79,9 +79,10 @@ hivectl matrix invite @mara:server --room '#hive-chat:server' # ...or to a spec
|
|||
|
||||
Write an operator-supplied GitHub personal access token (PAT) into an
|
||||
agent's token file so its `gh` wrapper + git credential helper can act as
|
||||
the configured bot account. Unlike forge/matrix there is no account
|
||||
creation — the PAT is for an existing GitHub account. The agent must
|
||||
declare [`hyperhive.githubAccount`](../github.md).
|
||||
the bot account. Unlike forge/matrix there is no account creation — the PAT
|
||||
is for an existing GitHub account. A CLI alternative to the dashboard
|
||||
credentials tab; the [GitHub integration](../github.md) is on by default
|
||||
(`hyperhive.github.enable`), so no per-agent config is needed.
|
||||
|
||||
```bash
|
||||
hivectl github set-token damocles --token-stdin # paste the PAT on stdin (preferred)
|
||||
|
|
|
|||
|
|
@ -71,10 +71,12 @@ enum Cmd {
|
|||
cmd: MatrixCmd,
|
||||
},
|
||||
/// GitHub account provisioning: write an operator-supplied personal
|
||||
/// access token (PAT) into an agent's `hyperhive.githubAccount` token
|
||||
/// file so its `gh` wrapper + git credential helper can authenticate.
|
||||
/// Unlike forge/matrix there is no account creation — the operator
|
||||
/// supplies a PAT for an existing GitHub account.
|
||||
/// access token (PAT) into an agent's `github-token` state file so its
|
||||
/// `gh` wrapper + git credential helper can authenticate. Unlike
|
||||
/// forge/matrix there is no account creation — the operator supplies a
|
||||
/// PAT for an existing GitHub account. A CLI alternative to the dashboard
|
||||
/// credentials tab; the integration is on by default
|
||||
/// (`hyperhive.github.enable`), so no per-agent config is needed.
|
||||
Github {
|
||||
#[command(subcommand)]
|
||||
cmd: GithubCmd,
|
||||
|
|
@ -433,10 +435,10 @@ enum MatrixCmd {
|
|||
#[derive(Subcommand)]
|
||||
enum GithubCmd {
|
||||
/// Write a GitHub PAT into `<agent>`'s state dir (`github-token`, 0600,
|
||||
/// agent-owned) via hive-priv. The agent must declare
|
||||
/// `hyperhive.githubAccount` (its `tokenFile` pointing at this path) for
|
||||
/// the `gh` wrapper + git credential helper to pick it up. The token is
|
||||
/// read live at invocation, so no rebuild/restart is needed. Prefer
|
||||
/// agent-owned) via hive-priv. The GitHub integration is on by default
|
||||
/// (`hyperhive.github.enable`), so the `gh` wrapper + git credential
|
||||
/// helper pick the token up with no per-agent config. The token is read
|
||||
/// live at invocation, so no rebuild/restart is needed. Prefer
|
||||
/// `--token-stdin`: an inline `--token` is visible in shell history +
|
||||
/// process listings.
|
||||
SetToken {
|
||||
|
|
|
|||
|
|
@ -285,7 +285,7 @@ pub async fn write_agent_matrix_token(
|
|||
/// (running as root). Writes `<state>/github-token` 0600, chowned to the agent
|
||||
/// user so the `gh` wrapper / git credential helper can read it from inside the
|
||||
/// container. Single account per agent — no account suffix. The token value is
|
||||
/// operator-supplied (for the agent's `hyperhive.githubAccount`).
|
||||
/// operator-supplied (for the agent's GitHub integration, `hyperhive.github.enable`).
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
|
|
|
|||
|
|
@ -414,7 +414,8 @@ pub enum PrivRequest {
|
|||
/// Write `github-token` into `AGENT_STATE_ROOT/<agent_name>/state/github-token`.
|
||||
///
|
||||
/// The operator-supplied GitHub personal access token (PAT) for the
|
||||
/// agent's `hyperhive.githubAccount`. Same write semantics as
|
||||
/// agent's GitHub integration (`hyperhive.github.enable`). Same write
|
||||
/// semantics as
|
||||
/// `WriteAgentForgeToken` — validates `agent_name`, creates the state dir
|
||||
/// if absent, writes the file 0600, and chowns it to the agent so the
|
||||
/// `gh` wrapper / git credential helper can read it. No account suffix
|
||||
|
|
|
|||
Loading…
Reference in a new issue