diff --git a/changelog.d/added-18516-remote-write-identity-settings.md b/changelog.d/added-18516-remote-write-identity-settings.md new file mode 100644 index 0000000000..c4472712a9 --- /dev/null +++ b/changelog.d/added-18516-remote-write-identity-settings.md @@ -0,0 +1 @@ +- Settings → Repos → Reference repos: owner-only "Post on other projects as" control (Hive bot, falling back to me / Hive bot only / Me) for `project.remote_write_identity`, a per-repo line saying which identity posts there and why, `PUT /api/config/reference-repos/write-identity`, and the docs (#18516). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 761668e955..c86359b209 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -6505,6 +6505,18 @@ "items": { "type": "string" } + }, + "write_identity": { + "type": "string" + }, + "write_identities": { + "type": "array", + "items": { + "type": "string" + } + }, + "bot_login": { + "type": "string" } } } @@ -6559,6 +6571,18 @@ "items": { "type": "string" } + }, + "write_identity": { + "type": "string" + }, + "write_identities": { + "type": "array", + "items": { + "type": "string" + } + }, + "bot_login": { + "type": "string" } } } @@ -6577,6 +6601,85 @@ } } }, + "/api/config/reference-repos/write-identity": { + "put": { + "tags": [ + "System" + ], + "summary": "Set the remote write identity", + "description": "Sets project.remote_write_identity: whose name the hive's writes to granted reference repos carry (bot: the App bot where the repo's owner installed the App, else the owner's connected account; bot_only: the App bot or read-only; owner: the owner's connected account). Refused when a hand-written write entry would have no credential under the new value. Re-resolves the reference repos before answering. Owner only.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "write_identity" + ], + "properties": { + "write_identity": { + "type": "string", + "enum": [ + "bot", + "bot_only", + "owner" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Current reference repos, resolved under the new value (same body as GET /api/config/reference-repos)", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "reference_repos": { + "type": "array", + "items": { + "type": "object" + } + }, + "write_kinds": { + "type": "array", + "items": { + "type": "string" + } + }, + "write_identity": { + "type": "string" + }, + "write_identities": { + "type": "array", + "items": { + "type": "string" + } + }, + "bot_login": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Unknown value, or a hand-written write entry would have no credential; nothing was stored" + }, + "403": { + "description": "Owner role required" + }, + "500": { + "description": "The config file could not be written; the setting is unchanged" + } + } + } + }, "/api/config/stat-sources": { "get": { "tags": [ diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index ce9b28d25c..d6873c748d 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -1343,6 +1343,8 @@ func (b *boot) wireBootClosures() { OwnerIdentity: b.ownerIdentityStore(), OwnerIdentityChanged: b.ownerIdentityChanged, RepoAgents: b.repoAgents, + CheckRemoteWriteIdentity: b.checkRemoteWriteIdentity, + RemoteWriteIdentityChanged: b.remoteWriteIdentityChanged, ReviewConfigApplied: func(rc config.ReviewConfig) { if b.ghClient == nil { return diff --git a/src/cmd/hive/reference_repos.go b/src/cmd/hive/reference_repos.go index d86359fa1f..c6e0a38239 100644 --- a/src/cmd/hive/reference_repos.go +++ b/src/cmd/hive/reference_repos.go @@ -312,3 +312,37 @@ func (b *boot) ownerIdentityStore() *github.OwnerIdentityStore { } return b.ownerIdentity } + +// checkRemoteWriteIdentity is the dashboard's dry run for a +// project.remote_write_identity change (hivecommons/hive#18516): the +// hand-written reference repos are resolved under setting with the live +// seams, and the error a hand-written write entry would stop the next boot +// with is returned so the change is refused instead. Nothing is installed. +func (b *boot) checkRemoteWriteIdentity(ctx context.Context, setting string) error { + if b.githubProxy == nil || b.cfg == nil { + return nil + } + if err := config.ValidateRemoteWriteIdentity(setting); err != nil { + return err + } + rt := b.referenceRepos + if rt == nil { + rt = b.newReferenceRepoRuntime() + } + deps := rt.deps + deps.writeIdentity = func() string { return setting } + _, err := buildReferenceRepoPolicies(ctx, config.HandWrittenReferenceRepos(b.cfg.Project.ReferenceRepos), deps, b.logger) + return err +} + +// remoteWriteIdentityChanged is the dashboard's hook after the setting was +// saved: one full pass (derive, resolve, install) so the next write already +// carries the new identity and the Settings page reloads the resolved state. +// It runs on the boot context, not the request's, because the pass starts +// background work (the read-only notice, the own-item follow-up). +func (b *boot) remoteWriteIdentityChanged() { + if b.referenceRepos == nil || b.ctx == nil { + return + } + b.rederiveReferenceRepos(b.ctx) +} diff --git a/src/docs/agent-configuration.md b/src/docs/agent-configuration.md index 443033a889..e3343dc6d0 100644 --- a/src/docs/agent-configuration.md +++ b/src/docs/agent-configuration.md @@ -1238,15 +1238,16 @@ project: - hivecommons/hivecommons.github.io - repo: hivecommons/hive write: [issues, prs] # opt-in tier - # write_token_file: /data/secrets/hive-ref-pat # optional: a maintainer token instead of the owner's account + # write_token_file: /data/secrets/hive-ref-pat # optional: a maintainer token instead of the bot or the owner's account + remote_write_identity: bot # bot (default), bot_only or owner: whose name the writes carry ``` | Tier | Agents may | Proxy refuses | |---|---|---| | `read-only` (string form, or no `write`) | `git clone`/fetch over HTTPS, GitHub REST/GraphQL GETs. Every request goes out without auth because the hive's App token is removed, so a private reference repo is not readable. | Every non-GET, with a 403 that names `reference_repos`. | -| `issues`, `prs` or `issues+prs` (`write:`) | The reads above, plus only: open an issue (`issues`), fork the repo into the owner's account, push a topic branch to that fork and open a PR from it (`prs`), and comment on an issue or PR the hive itself opened. | Merges, pushes to the default branch (of the repo or of the fork), labels, assignees, reviews, closing other people's items, and anything on the fork other than a push. Each refusal is logged as `reference_repo` in the violations log, so retrying cannot succeed. | +| `issues`, `prs` or `issues+prs` (`write:`) | The reads above, plus only: open an issue (`issues`), push a topic branch and open a PR from it (`prs`: as the owner, through the owner's fork; as the hive bot, to the repo itself), and comment on an issue or PR the hive itself opened. | Merges, pushes to the default branch (of the repo or of the fork), labels, assignees, reviews, closing other people's items, and anything on the fork other than a push. Each refusal is logged as `reference_repo` in the violations log, so retrying cannot succeed. | -Writes on the opt-in tier use a credential valid for *that* repo, never the hive's own installation token and never an installation of the hive's GitHub App on the target org ([#18196](https://github.com/hivecommons/hive/issues/18196)). The credential is the **hive owner's own GitHub account**, connected once on the dashboard (Settings → Repos → Reference repos → Connect GitHub account, [#18197](https://github.com/hivecommons/hive/issues/18197)); issues, PRs and comments then appear under that account, exactly as if the owner had filed them. For a hand-written entry an operator may set `write_token_file` instead (a maintainer PAT on the hive host); a derived entry never reads it. A hand-written write-mode entry with neither refuses boot with exit code 22 and a message naming both cures. These are direct POSTs. The `hive-open-issue`/`hive-open-pr` relays only act on `project.repos`, so a lane under `write_surface.enforce` cannot write to a reference repo at all ([GitHub write surface](github-write-surface.md#reference-repos)). +Writes on the opt-in tier use a credential valid for *that* repo, never the hive's own installation token. Which identity that is follows `project.remote_write_identity` ([Whose name the writes carry](#whose-name-the-writes-carry-projectremote_write_identity) below): the **hive's GitHub App bot**, only on a repo whose owner installed the App themselves, or the **hive owner's own GitHub account**, connected once on the dashboard (Settings → Repos → Reference repos → Connect GitHub account, [#18197](https://github.com/hivecommons/hive/issues/18197)), under which issues, PRs and comments appear exactly as if the owner had filed them. For a hand-written entry an operator may set `write_token_file` instead (a maintainer PAT on the hive host); a derived entry never reads it. A hand-written write-mode entry with neither refuses boot with exit code 22 and a message naming both cures. These are direct POSTs. The `hive-open-issue`/`hive-open-pr` relays only act on `project.repos`, so a lane under `write_surface.enforce` cannot write to a reference repo at all ([GitHub write surface](github-write-surface.md#reference-repos)). What agents see: every kick carries a `📚 REFERENCE REPOS` block listing each repo with its tier (`[reference · read-only]`, `[reference · issues+prs]`, …). It tells agents that an authorized-repo item whose deliverables name a reference repo is **in scope**. Findings belong in the deliverable inside the authorized repo, unless the tier allows an issue or PR. When a `prs`-tier entry has a credential, the block also names the login the writes appear under and the fork-and-PR commands ([#18198](https://github.com/hivecommons/hive/issues/18198)). On the dashboard, each reference repo is a minimal card with a `reference · ` chip and, for a write entry, the account it writes as; no stats, ACMM level or work items. Reference repos come in a separate payload field, so no queue or ACMM consumer counts them. Field-by-field defaults are in the [operator reference](operator-reference/README.md#notable-fields). @@ -1260,7 +1261,7 @@ The flow: 2. The workflow model bound to that repo declares which headings matter: `spec.intake.referenceRepoFields` lists the headings whose repositories are in scope and `spec.intake.outOfScopeFields` the headings whose repositories are excluded. A model without `intake.referenceRepoFields` derives nothing. For TechDocs that is `cncf-techdocs-assessment@curated-2026.11.2`; `curated-2026.11.1` is unchanged, so a hive bound to it must rebind. 3. A person with write access to the authorized repo applies `triage/accepted`. That label is the grant. The hive reads who applied it from the issue timeline and checks their repository permission. A label applied by a bot or App account grants nothing, so the hive can never grant itself access by moving the label. A label applied by someone without write access grants nothing either. 4. Every repository under an in-scope heading, and not under an out-of-scope heading, becomes a `write: [issues, prs]` entry. The issue's own repo, any authorized repo and any repo in `project.repos` are skipped. -5. The credential is the hive owner's connected GitHub account, exactly as for a hand-written write-tier entry. Until the owner connects one (or after the token is revoked), the entry is served read-only instead, the hive keeps running, and the request issue gets exactly one comment marked `` saying which repos the hive can read but not write and that the hive owner connects their account on the dashboard to change that; the policies flip without a restart. The comment is posted once per request issue and repo set, never again on a plain reload. A derived entry never consults `write_token_file` and never fails boot. +5. The credential follows `project.remote_write_identity`, exactly as for a hand-written write-tier entry: the hive's App bot where the requesting project installed the App, otherwise (unless the setting is `bot_only`) the hive owner's connected GitHub account. When neither applies, the entry is served read-only instead, the hive keeps running, and the request issue gets exactly one comment marked `` saying which repos the hive can read but not write and, unless the setting is `bot_only`, that the hive owner connects their account on the dashboard to change that; the policies flip without a restart. The comment never asks the project to install the App. The comment is posted once per request issue and repo set, never again on a plain reload. A derived entry never consults `write_token_file` and never fails boot. Lifecycle: the hive derives at boot, on every config reload and every `HIVE_REFERENCE_REPOS_DERIVE_INTERVAL` (default `10m`, Go duration, see [env-vars.md](env-vars.md)). Closing the request issue or removing `triage/accepted` drops the entry, its proxy policy and its kick line on the next pass. A hand-written entry for the same repo always wins over the derived one. Derived entries live in memory only: a saved overlay or runtime config never contains one, and a restart rebuilds them from the open issues. The same repo named by two accepted issues keeps the first and logs the second. @@ -1270,19 +1271,41 @@ The hive manages issues and PRs in two different ways depending on whether it is | | Linked repos (`project.repos`) | Remote repos (`project.reference_repos` at a write tier) | |---|---|---| -| Identity | The hive's GitHub App installation | The hive owner's own GitHub account, connected once in Settings | -| What the hive does | Full management: backlog scan, queue, kicks, stage engine, labels, reviews, merges | Participation only: open issues, open PRs through the owner's fork, comment on and push to its own items | +| Identity | The hive's GitHub App installation | Per `project.remote_write_identity`: the hive's App bot where the project installed the App itself (`bot`, the default, and `bot_only`), else the hive owner's own GitHub account, connected once in Settings | +| What the hive does | Full management: backlog scan, queue, kicks, stage engine, labels, reviews, merges | Participation only, whichever identity: open issues, open PRs (as the owner through the owner's fork, as the bot from a topic branch on the repo), comment on and push to its own items | | Follow-up | Webhooks and enumeration | A poll of the items the owner login opened that carry a hive marker; new comments and reviews go to the agent that opened the item | | Proxy | ACMM rules | The reference-repo gate: labels, reviews, assignees, closing others' items, merges and default-branch pushes are always refused | | The hub | Not involved | Not involved; the hub never holds the token and its login scope is unchanged | **Connecting the account.** Settings → Repos → Reference repos shows the identity in use. *Connect GitHub account* runs a GitHub device flow with the hive's own OAuth client asking for the `public_repo` scope: open the URL, enter the code, done. The token is stored on the spoke only, as an owner-only file under `/data/secrets` (`HIVE_GITHUB_OWNER_TOKEN_FILE` overrides), never in `hive.yaml` and never sent to the hub. It is re-checked every ten minutes; a revoked token drops every write-tier entry to read-only and Settings asks for a reconnect. *Disconnect* removes it from the hive; revoking it on GitHub is done under Settings → Applications on github.com. `public_repo` covers public repositories only: a private remote repo would need the `repo` scope and is not supported. +##### Whose name the writes carry (`project.remote_write_identity`) + +An issue or PR posted under the owner's own account reads as if the owner did the work, when they only commissioned it. `project.remote_write_identity` lets each hive choose ([#18516](https://github.com/hivecommons/hive/issues/18516)). In Settings → Repos → Reference repos it is the owner-only control **Post on other projects as:**, with the choices *Hive bot, falling back to me*, *Hive bot only* and *Me*. Every change is audit-logged as `config_remote_write_identity`. + +| Value | On a granted repo whose owner installed the hive's GitHub App | Everywhere else | +|---|---|---| +| `bot` (default; a missing key is `bot`) | Posts as the App bot (`hivecommons-hive[bot]` on the public fleet) | Posts as the owner's connected account; read-only if none is connected | +| `bot_only` | Posts as the App bot | Read-only. The owner's token is never used, even when it is connected | +| `owner` | Posts as the owner's connected account | Posts as the owner's connected account (the behaviour before this setting) | + +How it works and what it never does: + +- **The grant stays the same.** The setting only picks the name on writes the grant already allows. A repo gets a credential only when it is a write-tier entry, either hand-written or derived from an accepted request. An App installation by itself is never a grant. The hivecommons org, for example, installs the App for every repository and every hive, but a hive without an entry for one of those repos has no policy for it, so no token is ever minted for it. +- **Detection only.** The hive asks GitHub, with the App's JWT, whether an installation covers that exact repository (`GET /repos/{owner}/{repo}/installation`, cached for five minutes). Nothing in the hive asks a project to install the App: not Settings, not the kick, not the read-only notice. +- **One repo, minimum permissions.** The bot token is minted on that installation, scoped to that one repository. It gets `metadata: read` always, `issues: write` for the `issues` tier, and `contents: write` plus `pull_requests: write` for the `prs` tier. It is cached until shortly before it expires and is only injected by the proxy's reference-repo path for that repository. It never comes from the hive's own installation and never carries linked-repo management. +- **The same gate.** Labels, assignees, reviews, closing other people's items, merges, default-branch pushes, scanning and kicks stay refused for every identity. The App owns no fork, so as the bot a PR's topic branch is pushed to the reference repo itself, under the same default-branch guard. The kick gives agents the right flow for each repo. +- **No silent switch.** If the App lookup fails transiently, the entry is read-only for that pass (`credential_state: unresolved`) and the hive retries on the next pass. It never falls back to the owner's name. `write_token_file` on a hand-written entry still wins over every value. +- **Per-repo status.** Settings shows, on each write entry, which identity will actually post and why: `posts as hivecommons-hive[bot]: App installed on `, `posts as : App not installed on `, `read-only: connect your GitHub account`, or `read-only: bot only, App not installed on `. A change that would leave a hand-written write entry without a credential is refused before it is saved, with the error boot would stop on. +- **Upgrade.** Hives that never set the key read as `bot`. Where the App is not installed, nothing changes. A granted repo whose owner installed the App now gets posts as the bot instead of the owner. Choose *Me* to keep the previous behaviour everywhere. + +The own-item follow-up below reads under the owner token, so for now it follows only the items opened as the owner. + **Fork-and-PR.** The owner's account cannot push to a repository it does not own, so a PR against a remote repo goes through the owner's fork: `gh repo fork / --clone=false`, push the topic branch to `https:////`, then `gh pr create --repo / --head :`. The proxy allows exactly that (fork creation, pushes to the fork with its default branch protected, the PR against the remote) and refuses everything else on the fork. The kick spells the commands out, so `git push` and `gh pr create` need no agent-side special casing. **Own-item follow-up.** Remote repos send no webhooks and are not enumerated, so the hive polls them: it lists the open issues and PRs created by the owner login, keeps the ones whose body carries a hive marker (the `— hive:` attribution trailer or the `🐝 **Hive Agent**` footer), fetches new comments, review comments and reviews, and delivers them to the agent the marker names, into its live session or as a `🌐 REMOTE ITEM FOLLOW-UP` section on its next kick. State is in `/data/turn/remote-items.json` (`HIVE_REMOTE_ITEMS_FILE` overrides). Nothing else happens on the remote: no backlog scan, no queue, no stage engine ([#18199](https://github.com/hivecommons/hive/issues/18199)). -What agents see: the `📚 REFERENCE REPOS` block appends `(from owner/repo#N)` to each derived line, and `(from owner/repo#N; read-only: )` when the credential fell back. The proxy rules are the ones in the table above: a derived entry unlocks opening issues and PRs on that repo and nothing else, and the read-only fallback unlocks nothing. On the dashboard, Settings shows derived entries read-only with a link to the request issue and the credential state, and the API answers an edit of one with `409`. +What agents see: the `📚 REFERENCE REPOS` block appends `(from owner/repo#N)` to each derived line, `(from owner/repo#N; read-only: )` when the credential fell back, and `(read-only this pass: )` while an App lookup is unresolved. The proxy rules are the ones in the table above: a derived entry unlocks opening issues and PRs on that repo and nothing else, and the read-only fallback unlocks nothing. On the dashboard, Settings shows derived entries read-only with a link to the request issue and the credential state, and the API answers an edit of one with `409`. ## Label policy: which issues agents may work diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index 964b83c097..8d753bd19e 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -24,10 +24,10 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/openrouter/models` | Dashboard auth/session | Open Router Models | `pkg/dashboard/openrouter.go:47` | | `GET` | `/api/openrouter/credit` | Dashboard auth/session | Open Router Credit | `pkg/dashboard/openrouter.go:48` | | `GET` | `/openrouter/callback` | Public | Open Router Callback | `pkg/dashboard/openrouter.go:49` | -| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1787` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1788` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1789` | -| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:556` | -| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:557` | -| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:558` | -| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:559` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1792` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1793` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1794` | +| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:558` | +| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:559` | +| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:560` | +| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:561` | diff --git a/src/docs/api-reference/configuration.md b/src/docs/api-reference/configuration.md index f9ab6eb359..9cf22c7829 100644 --- a/src/docs/api-reference/configuration.md +++ b/src/docs/api-reference/configuration.md @@ -101,10 +101,11 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `PUT` | `/api/config/escalation` | Owner only | Escalation Config Set | `pkg/dashboard/api.go:215` | | `GET` | `/api/config/write-surface` | Owner only | Lane write allowlist (`write_surface.allowlist`, [#9587](https://github.com/hivecommons/hive/issues/9587)): `allowlist`, `ops`, `warnings` | `pkg/dashboard/api.go:524` | | `PUT` | `/api/config/write-surface` | Owner only | Replace the lane write allowlist; `{"allowlist": {}}` clears it; unknown operation or bad lane name is a 400 with nothing changed | `pkg/dashboard/api.go:525` | -| `GET` | `/api/config/reference-repos` | Owner only | `project.reference_repos` ([#18136](https://github.com/hivecommons/hive/issues/18136)): `reference_repos` (`{repo, write, write_token_file}` plus `derived_from` on a derived entry and, on every write entry, `credential_state`, `credential_reason` and `credential_login`, the GitHub account the writes appear under ([#18197](https://github.com/hivecommons/hive/issues/18197)); always an array) and `write_kinds` | `pkg/dashboard/api.go:552` | +| `GET` | `/api/config/reference-repos` | Owner only | `project.reference_repos` ([#18136](https://github.com/hivecommons/hive/issues/18136)): `reference_repos` (`{repo, write, write_token_file}` plus `derived_from` on a derived entry and, on every write entry, `credential_state`, `credential_reason` and `credential_login`, the GitHub account the writes appear under ([#18197](https://github.com/hivecommons/hive/issues/18197)), plus `credential_identity` (`bot`, `owner` or `token_file`) and `credential_note`, the one-line why ([#18516](https://github.com/hivecommons/hive/issues/18516)); always an array), `write_kinds`, `write_identity` (`project.remote_write_identity` with the default applied), `write_identities` and `bot_login` (the App bot login, when known) | `pkg/dashboard/api.go:552` | | `PUT` | `/api/config/reference-repos` | Owner only | Replace `project.reference_repos`; `{"reference_repos": []}` clears it. Refused with a 400 and nothing changed when the config loader would reject the list (bare name, repo also in `project.repos`, duplicate, unknown write kind, token file without write) or when a write entry has no credential boot would accept — the same message boot exits 22 with — or when an entry carries a `write_token_file` the config file does not already hold for that repo (the path is operator-only; a dashboard write opt-in writes as the hive owner's connected GitHub account). Entries with `derived_from` ([#18139](https://github.com/hivecommons/hive/issues/18139)) are the request issue's grant: echo them back as served; changing one's write set, leaving one out, sending one the hive did not derive or adding a hand-written entry for the same repo is a 409 naming the issue to change instead ([#18161](https://github.com/hivecommons/hive/issues/18161)). They are never stored: the saved list holds the hand-written entries and the derived set is merged back in memory after the save. 500 when the file could not be written (proxy restored, nothing changed). On success the GitHub proxy's reference policies are replaced without a restart; audited as `config_reference_repos` | `pkg/dashboard/api.go:553` | -| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:562` | -| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:563` | +| `PUT` | `/api/config/reference-repos/write-identity` | Owner only | Set `project.remote_write_identity` ([#18516](https://github.com/hivecommons/hive/issues/18516)): body `{"write_identity": "bot"}`, one of `bot`, `bot_only`, `owner`. 400 on an unknown value, or when a hand-written write entry would have no credential under the new value (the message boot exits 22 with); nothing is stored then. 500 when the file could not be written. On success the reference repos are re-resolved before the response, which is the same body as `GET /api/config/reference-repos`; audited as `config_remote_write_identity` with `previous` and `write_identity` | `pkg/dashboard/api.go:555` | +| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:564` | +| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:565` | | `GET` | `/api/config/review` | Dashboard auth/session | Review Config Get | `pkg/dashboard/api.go:218` | | `PUT` | `/api/config/review` | Owner only | Review Config Set | `pkg/dashboard/api.go:221` | | `PUT` | `/api/config/governor/features` | Owner only | Governor Features | `pkg/dashboard/api.go:227` | diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index 38eca5ce98..f890c567c1 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -84,7 +84,7 @@ The monitor renders CI and Review concurrently on one shared PR row; see | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:377` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:378` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:379` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1794` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1799` | ### Activity observation provenance The CI snapshot retains real check/node IDs, head, App ID and transition times. diff --git a/src/docs/api-reference/health-status-events.md b/src/docs/api-reference/health-status-events.md index f384f2e2ea..5befd6524b 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -24,17 +24,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` — the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` — one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` — `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` — the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)). Also `startedAt` (RFC3339 process start — changes on every pod roll even when the build does not, so the dashboard can say "Restarted" vs "Upgraded") and, until the first status is published, `startupPhase`/`startupPhaseLabel` (the boot phase a fresh pod is in) ([#15788](https://github.com/hivecommons/hive/issues/15788)) | `pkg/dashboard/api.go:45` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=&to=` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` — the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:46` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:70` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1767` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1768` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1769` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1775` | -| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1780` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1781` | -| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1782` | -| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1783` | -| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1784` | -| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1785` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1786` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1772` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1773` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1774` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1780` | +| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1785` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1786` | +| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1787` | +| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1788` | +| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1789` | +| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1790` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1791` | | `GET` | `/api/swarm` | Dashboard auth/session | Current swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields. | `pkg/dashboard/swarm.go:310` | | `POST` | `/api/swarm` | Owner only | Start a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body `{"repo":"owner/name","force":true}` is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured. | `pkg/dashboard/swarm.go:311` | | `DELETE` | `/api/swarm` | Owner only | End the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured. | `pkg/dashboard/swarm.go:312` | diff --git a/src/docs/api-reference/snapshots-and-style.md b/src/docs/api-reference/snapshots-and-style.md index 3a7beea1b1..965c46c74a 100644 --- a/src/docs/api-reference/snapshots-and-style.md +++ b/src/docs/api-reference/snapshots-and-style.md @@ -6,7 +6,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| | `GET` | `/api/style` | Public | Sanitized custom dashboard CSS | `pkg/dashboard/api.go:47` | -| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1857` | +| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1862` | | `GET` | `/api/snapshot/frame-ancestors` | Public | Snapshot framing allowlist | `pkg/dashboard/api.go:83` | | `GET` | `/api/snapshot` | Public | Snapshot data | `pkg/dashboard/api.go:84` | | `GET` | `/snapshot` | Public | Public read-only snapshot page | `pkg/dashboard/api.go:85` | diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index f3c7124183..2b8887baab 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -254,9 +254,10 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through | `project.repo_policies[].label_driven_approval_labels` | Unset: inherits `project.label_driven_approval_labels`. | Per-repo approval-label list; only read when `label_driven` is set. Editable from the dashboard sub-row of the repo's label-driven toggle. | | `project.repo_policies[].companion_repos` | Unset (no companions). | List of sibling repositories (`name` in the project org, or `org/name`) that this repo's tooling expects checked out beside it under the agent workspace root — for example a docs/website repo a spec tool registers at `///…`. Contributor task prompts and resident-agent kicks carry a shallow-clone plan for each companion at `//` (`$HIVE_WORKSPACE_DIR` for contributor agents, `$HOME/workspace` for resident agents), and agents are told that a tool reporting one of those paths missing means *clone it*, never park the issue. Self-references and malformed entries are dropped. See [running-at-level-6.md](../running-at-level-6.md#needless-parks). | | `project.reference_repos` | Unset (none). | Repos **outside** the project the hive may *study* without managing them ([#18015](https://github.com/hivecommons/hive/issues/18015)) — the rare case of a hive whose deliverable is *about* another project, e.g. a CNCF TechDocs hive (authorized repo `cncf/techdocs`) assessing `hivecommons/docs`. Each entry is `owner/name` (bare names are rejected, as is any repo also in `project.repos`). Default tier is **read-only**: agents may `git clone`/fetch them unauthenticated over HTTPS and issue GitHub REST/GraphQL GETs; the proxy strips the hive's App token from every request to them and refuses every non-GET with a message naming `reference_repos`. The kick lists them under `📚 REFERENCE REPOS` so an authorized-repo item whose deliverables name one is treated as in scope (not out-of-scope/critical), and agents are told findings go in the deliverable inside the authorized repo, never as issues or PRs on the reference repo. The dashboard shows each as a minimal card with a `reference · ` chip — no stats, no ACMM, no work items. The owner can add, change and remove entries in Settings → Repos → Reference repos (`PUT /api/config/reference-repos`, [#18136](https://github.com/hivecommons/hive/issues/18136)); a save is refused with the loader's or boot's own message — including a write entry with no usable credential — and otherwise takes effect without a restart. Private reference repos are not readable (reads are unauthenticated). Example:
`project:`
` repos: [techdocs]`
` reference_repos:`
` - hivecommons/docs`
` - hivecommons/hivecommons.github.io`
` - {repo: hivecommons/hive, write: [issues, prs]}` | -| `project.reference_repos[].write` | Unset (read-only). | Per-entry write opt-in, any of `issues`, `prs`. The **only** writes it unlocks on that repo: open an issue; open a PR / push a topic branch; comment on an issue or PR the hive itself opened. Never: merge, push to the default branch, labels or assignees on others' items, reviews, closing others' issues — the proxy refuses those deterministically (`reference_repo` in the violations log). The write is sent with a credential GitHub honours for *that* repo, never the hive's own installation token: the same GitHub App must already be **installed on the target org** (the hive discovers that installation and mints a token scoped to the one repo and the opted-in permissions). The hive owner cannot install it on a third-party org; the installation exists when that org runs its own hive. For a hand-written entry on an org without one, set `write_token_file`. Boot refuses (exit code 22) a hand-written write-mode entry with neither; a derived entry (below) is served read-only instead. Direct POSTs are used here, not the `hive-open-pr`/`hive-open-issue` relays, which only act on `project.repos`; a lane under `write_surface.enforce` therefore cannot write to a reference repo. | +| `project.reference_repos[].write` | Unset (read-only). | Per-entry write opt-in, any of `issues`, `prs`. The **only** writes it unlocks on that repo: open an issue; open a PR / push a topic branch; comment on an issue or PR the hive itself opened. Never: merge, push to the default branch, labels or assignees on others' items, reviews, closing others' issues — the proxy refuses those deterministically (`reference_repo` in the violations log). The write is sent with a credential GitHub honours for *that* repo, never the hive's own installation token: per `project.remote_write_identity` (below), the hive's App bot where the repo's owner installed the App themselves (a token minted on that installation, scoped to the one repo and the opted-in permissions), else the hive owner's connected GitHub account, or a `write_token_file` on a hand-written entry. Boot refuses (exit code 22) a hand-written write-mode entry with neither; a derived entry (below) is served read-only instead. Direct POSTs are used here, not the `hive-open-pr`/`hive-open-issue` relays, which only act on `project.repos`; a lane under `write_surface.enforce` therefore cannot write to a reference repo. | | `project.reference_repos[].write_token_file` | Unset. | Path to a file holding a token (a maintainer PAT or fine-grained token) authorized for that repo; read on every use so a rotation needs no restart. Only meaningful with `write` on a hand-written entry; never consulted for a derived entry. Its `GET /user` login is what the proxy treats as "own item" for comments. File-only: the Settings editor shows a path the file set and keeps it across saves, but refuses to add or change one, since the path names a file on the hive host and a hosted hive's owner has no host access. | -| Derived `project.reference_repos` entries | Derived at boot, on every config reload and every `HIVE_REFERENCE_REPOS_DERIVE_INTERVAL` (default `10m`). | Write-tier (`issues+prs`) entries the hive builds from an open request issue in an authorized repo that carries `triage/accepted` applied by a person with write access to that repo, when the repo's bound workflow model declares `intake.referenceRepoFields` ([#18139](https://github.com/hivecommons/hive/issues/18139)). A label applied by a bot or App account grants nothing. Hand-written entries win on the same repo; a repo in `project.repos` is never derived; the credential is the App installation on the requesting org, with a read-only fallback and one marked comment on the request issue when there is none. Closing the issue or removing the label drops the entry on the next pass. Never written to the overlay or runtime config: `Config.Save` strips them. Not editable in Settings (`409` on an edit). See [Reference repos derived from an accepted request](../agent-configuration.md#reference-repos-derived-from-an-accepted-request). | +| `project.remote_write_identity` | `bot` (also what a missing key means). | Whose name a write-tier reference repo's issues, PRs and comments carry ([#18516](https://github.com/hivecommons/hive/issues/18516)). `bot`: the hive's GitHub App bot on a granted repo whose owner installed the App themselves, else the owner's connected account, else read-only. `bot_only`: the App bot or read-only, never the owner's token. `owner`: the owner's connected account everywhere. Never widens a grant; an App installation alone grants nothing. Owner-only in Settings → Repos → Reference repos (*Post on other projects as*, `PUT /api/config/reference-repos/write-identity`); a value that would leave a hand-written write entry without a credential is refused. See [Whose name the writes carry](../agent-configuration.md#whose-name-the-writes-carry-projectremote_write_identity). | +| Derived `project.reference_repos` entries | Derived at boot, on every config reload and every `HIVE_REFERENCE_REPOS_DERIVE_INTERVAL` (default `10m`). | Write-tier (`issues+prs`) entries the hive builds from an open request issue in an authorized repo that carries `triage/accepted` applied by a person with write access to that repo, when the repo's bound workflow model declares `intake.referenceRepoFields` ([#18139](https://github.com/hivecommons/hive/issues/18139)). A label applied by a bot or App account grants nothing. Hand-written entries win on the same repo; a repo in `project.repos` is never derived; the credential follows `project.remote_write_identity`, with a read-only fallback and one marked comment on the request issue when there is none. Closing the issue or removing the label drops the entry on the next pass. Never written to the overlay or runtime config: `Config.Save` strips them. Not editable in Settings (`409` on an edit). See [Reference repos derived from an accepted request](../agent-configuration.md#reference-repos-derived-from-an-accepted-request). | | `intake.referenceRepoFields` (workflow model, `spec.intake`) | Unset on every model except `cncf-techdocs-assessment@curated-2026.11.2`. | Rendered issue-form headings (the `###