vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs/github.md

2.9 KiB
Raw Blame History

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 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:

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).

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:

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.

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.