diff --git a/docs/integrations/github.md b/docs/integrations/github.md index a6242c0f..88fccf27 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -5,9 +5,9 @@ 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: paste a PAT into the agent's credentials tab -and it works. No per-agent nix declaration, no rebuild — hive-c0re -injects the token into the agent's state dir out of band. +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 @@ -15,8 +15,7 @@ injects the token into the agent's state dir out of band. 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 written to its token -file. +needed — an agent gains GitHub by having a PAT stored for it. @@ -27,29 +26,31 @@ services.hyperhive.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 or credential helper. +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 hive-wide host switch is the intended control.) -github.com only. The token **value** never touches nix — it's written to -`/github-token` separately (see [Provisioning](#provisioning)). +github.com only. The token **value** never touches nix — the agent writes it +to `/github-token` at runtime (see [Provisioning](#provisioning)). ## Provisioning -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`). A CLI path also exists for -recovery/scripting: +The PAT is operator-supplied. In the [swarm 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//github-token` in the swarm secret store; +no hive writes it. One token per agent: linking again replaces it, +and no route hands it back. -```sh -hivectl github set-token --token-stdin # paste the PAT on stdin (preferred) -hivectl github set-token --token # inline (visible in shell history) -``` - -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). +The agent's `hive-agent-github-token` unit reads that path under the +agent's own store certificate and writes `/github-token` (`0600`, +owned by the agent), on boot 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. +The unit never deletes the file: a `github-token` already in place stays +when the store holds none or doesn't answer. Where the token lives and who +reads it: [credentials.md](../swarm/credentials.md). ## Security diff --git a/docs/swarm/credentials.md b/docs/swarm/credentials.md index 8a216831..5f5650a8 100644 --- a/docs/swarm/credentials.md +++ b/docs/swarm/credentials.md @@ -69,6 +69,7 @@ of the cell says how. | `swarm/agents//queue` | `swarm-controller`, at agent creation | `hive-agent` in the agent container, under the agent's own certificate, held in memory — the identity it presents to the swarm queue, naming that one agent rather than its hive | ✅ `swarm-controller`'s five-minute pass re-mints a live agent's secret once it's 45 days old by `minted_at` on the stored object; a secret with no `minted_at` gets one stamped, value unchanged. The pass skips agents declared `Destroyed` — declaring an agent destroyed deletes every version of the path instead, the undo of the mint rather than another one | ✅ `hive-agent` reads the path before its first connect and again on every reconnect attempt, so a reconnect after a re-mint presents the new secret. An open connection keeps the secret it connected with; after a revocation the agent keeps retrying under the queue client's backoff | | `swarm/agents//forge-token` | `swarm-controller`, at agent creation and in a pass every 5 minutes over every agent with a store identity | the agent container itself, under its own certificate, fetched to `/run/hive-agent-forge-token/token` | ✅ the controller re-mints when the stored token is missing or no longer matches the forge (last eight characters and scopes) | ✅ the agent re-fetches on a 10-minute timer | | `swarm/agents//forge/