diff --git a/changelog.d/added-pr-gate-grant-visibility.md b/changelog.d/added-pr-gate-grant-visibility.md new file mode 100644 index 0000000000..ca03224034 --- /dev/null +++ b/changelog.d/added-pr-gate-grant-visibility.md @@ -0,0 +1 @@ +- The hive-posted PR-contents gate (`auto_merge.pr_gate`) now fails visibly instead of silently: the hive reads the Commit statuses permission its App installation was actually granted at startup and every 15 minutes, forces the gate off when the write grant is missing (it never promotes itself to `enforce`), and records a 403 on a status write per repository without retrying for 15 minutes. The spoke dashboard shows a banner naming the installation, what is missing, where an owner accepts it and the days left before 2026-12-02. The hub health verdict carries the cause with a remediation hint, red when a required check depends on the gate and amber otherwise. In `enforce`, a PR whose required gate context cannot be posted shows `unauthorized:post-pr-gate-status` rather than a bare `required-check-missing`. Nothing changes while the mode is `off` (refs #19038). diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index def018f610..ee57824c2d 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -4805,6 +4805,7 @@ func (b *boot) bootHeartbeatWith(deps bootHeartbeatDeps) { providerLimitReason, providerLimitRebuffs, providerLimitHiveWide, providerLimitAgents := spoke.ProviderLimitHeartbeatFields(agents, dashboard.InferenceBudgetExceeded) lastWriteKickAt, kickDisposition, kickSkipReason, notWritableQueued := outputFreshnessHeartbeatFields(acmmLvl, govState, agents) + prGateCause, prGateDependsOn := b.dashSrv.PRGateCause() ghAppTokenStatus, ghAppTokenLastMintAt, ghAppTokenError := githubAppTokenHeartbeatFields(b.cfg, b.dashSrv.GetGitHubAppPermIssue()) ghAppErrorClass, ghAppHTTPStatus := githubAppStructuredFailure( @@ -4997,6 +4998,8 @@ func (b *boot) bootHeartbeatWith(deps bootHeartbeatDeps) { GitHubAppRequired: b.dashSrv.IsGitHubAppRequired(), GitHubAppPermIssue: b.dashSrv.GetGitHubAppPermIssue(), GitHubAppState: b.dashSrv.GetGitHubAppState(), + PRGateCause: prGateCause, + PRGateDependsOn: prGateDependsOn, GitHubAppTokenStatus: ghAppTokenStatus, GitHubAppTokenLastMintAt: ghAppTokenLastMintAt, GitHubAppTokenError: ghAppTokenError, diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index 576e73bac1..7a02fd4b8d 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -24,9 +24,9 @@ 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:1805` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1806` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1807` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1808` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1809` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1810` | | `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:567` | | `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:568` | | `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:569` | diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index ad09528f73..7f7266e273 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -113,7 +113,7 @@ review are settled. | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:378` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:379` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:380` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1812` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1815` | ### 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 11176f8319..14ce8935bd 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -25,17 +25,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `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:47` | | `GET` | `/api/version/contains` | Dashboard auth/session | Does the running build contain a PR or commit ([#18915](https://github.com/hivecommons/hive/issues/18915)): `?q=` returns `{query, commit?, running?, channel?, contains, reason?}`. `contains` is `yes`, `no` or `unknown`, computed from the commit this hive reports running (`hash` on `/api/version`) and repository ancestry; `unknown` (with `reason`) when the commit cannot be resolved, the lookup failed or the hive has no GitHub access, never a guess. An unmerged PR is `no`. `400` when `q` is neither a PR number nor a SHA | `pkg/dashboard/api_version_contains.go:113` | | `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:71` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1785` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1786` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1787` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1793` | -| `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:1798` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1799` | -| `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:1800` | -| `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:1801` | -| `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:1802` | -| `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:1803` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1804` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1788` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1789` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1790` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1796` | +| `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:1801` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1802` | +| `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:1803` | +| `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:1804` | +| `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:1805` | +| `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:1806` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1807` | | `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/hub-server.md b/src/docs/api-reference/hub-server.md index a3223de629..4b71dc889b 100644 --- a/src/docs/api-reference/hub-server.md +++ b/src/docs/api-reference/hub-server.md @@ -35,29 +35,29 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/benchmarks/ingest` | Per-hive heartbeat bearer | Spoke push target for anonymized [benchmark records](../benchmarks.md): body `{hive_id, records[]}`; the hub recomputes the hive hash from the authenticated id, rejects records whose `source.hive_id` differs (`401` bad bearer, `403` unregistered hive, `400` malformed), merges accepted records by id into `/data/benchmarks//.json` and returns `202 {accepted, rejected, files}` | `pkg/hub/benchmarks.go` | | `GET` | `/api/hub/benchmarks` | Public | Benchmark publisher status: `last_ingest_at`, `last_publish_at`, `last_publish_files`, `last_error`, `pending_files`, `hive_count`, `record_count` and per-hive-hash `hives{}` counts; the hub commits pending month files hourly to `hivecommons/benchmarks` (`HIVE_BENCHMARKS_REPO`) via its App identity | `pkg/hub/benchmarks.go` | | `GET` | `/api/reach` | Hub admin | PR Reach Report (?pr=NNN or ?recent=K) | `pkg/hub/saas.go:511` | -| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1829` | -| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1830` | +| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1831` | +| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1832` | | `GET` | `/activity` | Signed-in user | Fleet activity page ([#16063](https://github.com/hivecommons/hive/issues/16063)): read-only, data-free shell that polls `/api/hub/activity` every 15 s with `If-None-Match`. No session → `307` to `/login`; blocked user → `403`. Own Content-Security-Policy (scripts and styles from `'self'` only, `script-src-attr`/`style-src-attr` `'none'`), `Cache-Control: no-cache` + content `ETag`. See [Hub Fleet activity page](../hub-fleet-activity.md) | `pkg/hub/activity_page.go` | | `GET` | `/activity/public` | Public | Public-safe Fleet activity page ([#15966](https://github.com/hivecommons/hive/issues/15966)): the same data-free shell as `/activity`, served without a session; on this path the page polls `/api/hub/activity/public` with `credentials: 'omit'`. Source of the `twitch.tv/hivecommonsfleet` broadcast. Same CSP and cache headers as `/activity`. See [Hub Fleet activity page](../hub-fleet-activity.md#public-safe-view) | `pkg/hub/activity_public.go` | | `GET` | `/activity/assets/{name}` | Public | The shared tracker assets the Fleet activity page loads, byte-identical: the row asset (`pkg/webassets/trackerrow`, [#16062](https://github.com/hivecommons/hive/issues/16062)) and the `am.*` URL-view and display-playlist helpers (`pkg/webassets/trackerview`, [#16064](https://github.com/hivecommons/hive/issues/16064)); only names in `trackerrow.Files` or `trackerview.Files`, else `404`. `Cache-Control: no-cache` + content `ETag` | `pkg/hub/activity_page.go` | -| `POST` | `/api/shared-agent-pool/leases` | Hub handler-specific | Acquire or renew a shared CLI session lease | `pkg/hub/server.go:1748` | -| `PUT` | `/api/shared-agent-pool/leases` | Hub handler-specific | Renew an active shared CLI session lease | `pkg/hub/server.go:1749` | -| `DELETE` | `/api/shared-agent-pool/leases` | Hub handler-specific | Release a shared CLI session lease | `pkg/hub/server.go:1750` | -| `POST` | `/api/heartbeat` | Hub handler-specific | Heartbeat. A request carrying `X-Hive-Activity-Update` is an activity-only update ([#15963](https://github.com/hivecommons/hive/issues/15963)): body `{"activity_update":{"hive_id","activity"}}`, the same per-hive bearer, accepted only for a hive already in the registry (`404` otherwise); it replaces the in-memory activity digest and nothing else, and the signed response carries `ok`, `activity_etag` and `activity_events_ack` (the highest activity event sequence number the hub holds for the hive, [#15964](https://github.com/hivecommons/hive/issues/15964); full heartbeat responses carry it too) | `pkg/hub/server.go:1751` | -| `POST` | `/api/task-status` | Hub handler-specific | Task Status | `pkg/hub/server.go:1752` | -| `GET` | `/api/registry` | Hub handler-specific | Registry | `pkg/hub/server.go:1763` | -| `GET` | `/api/hub/leaderboard` | Hub handler-specific | Leaderboard | `pkg/hub/server.go:1764` | -| `GET` | `/api/hub/stats` | Hub handler-specific | Stats | `pkg/hub/server.go:1765` | -| `GET` | `/api/fleet-stats` | Hub handler-specific | Fleet Stats | `pkg/hub/server.go:1766` | +| `POST` | `/api/shared-agent-pool/leases` | Hub handler-specific | Acquire or renew a shared CLI session lease | `pkg/hub/server.go:1750` | +| `PUT` | `/api/shared-agent-pool/leases` | Hub handler-specific | Renew an active shared CLI session lease | `pkg/hub/server.go:1751` | +| `DELETE` | `/api/shared-agent-pool/leases` | Hub handler-specific | Release a shared CLI session lease | `pkg/hub/server.go:1752` | +| `POST` | `/api/heartbeat` | Hub handler-specific | Heartbeat. A request carrying `X-Hive-Activity-Update` is an activity-only update ([#15963](https://github.com/hivecommons/hive/issues/15963)): body `{"activity_update":{"hive_id","activity"}}`, the same per-hive bearer, accepted only for a hive already in the registry (`404` otherwise); it replaces the in-memory activity digest and nothing else, and the signed response carries `ok`, `activity_etag` and `activity_events_ack` (the highest activity event sequence number the hub holds for the hive, [#15964](https://github.com/hivecommons/hive/issues/15964); full heartbeat responses carry it too) | `pkg/hub/server.go:1753` | +| `POST` | `/api/task-status` | Hub handler-specific | Task Status | `pkg/hub/server.go:1754` | +| `GET` | `/api/registry` | Hub handler-specific | Registry | `pkg/hub/server.go:1765` | +| `GET` | `/api/hub/leaderboard` | Hub handler-specific | Leaderboard | `pkg/hub/server.go:1766` | +| `GET` | `/api/hub/stats` | Hub handler-specific | Stats | `pkg/hub/server.go:1767` | +| `GET` | `/api/fleet-stats` | Hub handler-specific | Fleet Stats | `pkg/hub/server.go:1768` | | `GET` | `/api/hub/evidence` | Hub admin | Read-only cross-hive evidence drill-down from each spoke's stored heartbeat `evidence` summary ([#12116](https://github.com/hivecommons/hive/issues/12116)); non-admins get `403`. Returns `spokes`, `reporting`, pooled `calibration` (bucket 0–5 → `{n, bad, rate, lo, hi}`; the hub view folds the six buckets into four reviewer-confidence ranges), `findings[]` (the plain-language *What this says* sentences, generated from the same fields; [#12456](https://github.com/hivecommons/hive/issues/12456)), `by_acmm_level` (`level`, `hives`, `merged_90d`, `revert_rate`, and `time_to_merge` — `median_of_hive_medians_s`, `hives`, `n` — the median of the level's per-hive median time-to-merge, omitted when no hive at the level reports one; [#12464](https://github.com/hivecommons/hive/issues/12464)), `family_false_approve_rate` (`same`/`cross`/`mixed`, hives classed by their reviewer vs author family sets), fleet `record_coverage` (merged PRs with an evidence record over `prs_merged_90d`), fleet panels ([#12370](https://github.com/hivecommons/hive/issues/12370)) `outcomes_by_author_kind[]` (`kind`, `hives`, `n`, `merged`, `reverted`, `merge_rate`, `revert_rate`), `write_counters[]` (`tier`, `hives`, `attempted`, `blocked`, `block_rate`) and `shadow_gate` (`review_gate` / `intent` → `held` / `passed` outcomes with `revert_rate`), each omitted while no spoke reports it and repeated per `by_acmm_level[]` row, and per hive `hives[]` with `acmm_level`, `prs_merged_90d`, `record_coverage`, `family_mix`, false-approve / false-block / revert rates, families, a calibration series the raw `counts` behind them (including `by_author_kind`) so the drill-down can re-pool a hive / ACMM-level selection client-side, and `criteria[]`: the per-axis criteria table derived hub-side from the quadrant criteria (`axis`, `label`, `scored`, `criteria[]` with `name`, `label`, `status` `met`/`unmet`/`not_reported`, `display`/`score` when measured, `reason` otherwise; offline, evidence-less or unscored hives are `not_reported`, never `unmet`; [#12463](https://github.com/hivecommons/hive/issues/12463)). Every rate is `{n, rate, lo, hi}` with a 95% Wilson interval; `rate`/`lo`/`hi` are null when `n` < 10. Window selection ([RFC #12062](https://github.com/hivecommons/hive/issues/12062)): `?hours=24|168|720` pools each hive's matching heartbeat `windows` block instead of its 90-day block (any other or absent `hours` → 90 days); `?from=YYYY-MM-DD|RFC3339[&to=…]` (date-only `to` is inclusive, `to` defaults to now, `to` ≥ `from`, span ≤ 366 days, else `400`) is served from the smallest reported window that reaches back to `from` and flagged `window.approximate`. The response carries `window` (`hours`, `key`, `label`, `from`, `to`, `approximate`, `coverage_available` — `record_coverage` is only computed for the 90-day window because `prs_merged_90d` is a 90-day count), `window_unreported` and per-hive `window_unreported` for hives whose spoke predates per-window reporting. `?hive=[,…]` (repeatable) and `?level=` restrict the registry server-side to those hives / that ACMM level before pooling. Hub admins open it from the Fleet quadrant card or its **🔬 Evidence** button ([#12117](https://github.com/hivecommons/hive/issues/12117)), pick a window (24h / 7d / 30d / 90d / custom), filter it by hive and ACMM level and read each section's ⓘ explainer; the per-hive author-kind revert counts behind the *Revert rate by author kind* panel are `hives[].counts.by_author_kind` ([#12326](https://github.com/hivecommons/hive/issues/12326)). Never consulted by merge decisions | `pkg/hub/evidence.go` | | `GET` | `/api/hub/evidence/report` | Hub admin | Plain-language report of the hub evidence view ([#12456](https://github.com/hivecommons/hive/issues/12456)), rendered server-side from the same `EvidenceView` as `/api/hub/evidence` so every figure reconciles with the modal; non-admins get `403`. Same `hours=` / `from=` / `to=` window and `hive=` / `level=` filter parameters. `format=md` (default, `text/markdown`) or `format=html` (standalone page, inline CSS, no scripts or external assets, hive names escaped); any other value → `400`. `download=1` sets `Content-Disposition: attachment; filename="hive-evidence---.md|html"`, otherwise inline. Sections: Summary (the generated findings), What we measured and why, The numbers, How to read these, What is not reported yet and why, Grade per section, footer link to `review-evidence.md`. `Cache-Control: no-store`. Read-only; never consulted by merge decisions | `pkg/hub/evidence_report.go` | | `GET` | `/api/hub/activity` | Signed-in user | Read-only hub-wide activity view ([#15951](https://github.com/hivecommons/hive/issues/15951), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)) merged from each spoke's heartbeat `activity` digest, held in hub memory only. Authorization is per user and per hive before aggregation: hub admins see every registered hive; everyone else only hives they own or hold an unexpired grant for; anonymous → `401`. Returns `hives[]` (`hive_id`, `name`, `status` `ok`/`stale`/`not_reporting`/`missing`, `reporting`, `stale` once the block is older than two heartbeats, `last_heartbeat`, `received_at`, `generated_at`, `totals` — `items`, `by_stage`, `by_modifier`, counting private and truncated items too — `truncated` and `events_dropped`), `items[]` (`hive_id`, `repo`, `n`, `kind`, `title`, `author_kind`, `stage`, `stage_n`, `since`, `mods`, `private`) ordered needs-human/needs-decision, stalled, furthest stage, oldest, a response-level `truncated` (cap 2000), and `events[]` ([#15964](https://github.com/hivecommons/hive/issues/15964): `hive_id`, `received_at`, `seq`, `type` `opened`/`stage`/`merged`, `repo`, `n`, `kind`, `title`, `from`, `stage`, `at`, `private`), oldest first, from a fleet-wide in-memory ring of at most 1,000 events, none held longer than 24 hours (ageing out is not counted in `events_dropped`; when full, the oldest event of the hive holding the most events is dropped, counted in that hive's `events_dropped`, so one hive cannot evict the others' events). Events are filtered per user and per hive exactly like items, before aggregation, so an event for a hive the viewer cannot see is never delivered; `mod`/`author_kind` filters keep only events whose item is still on the hive's board. A spoke block carries at most 200 events; drops are disclosed per hive as `events_dropped`. New events change the `ETag`. Each digest carries at most 100 items by default and never more than the 250-item hub ceiling; private-repository items appear only when the spoke opts in. Filters: `hive`, `repo`, `stage`, `mod`, `author_kind`, `q` (title substring or `#`), each ≤ 200 characters (else `400`). `ETag` + `If-None-Match` → `304`; `Cache-Control: private, no-cache`, `Vary: Cookie, Authorization`. No actions | `pkg/hub/activity.go` | | `GET` | `/api/hub/activity/public` | Public | Public-safe activity view ([#15966](https://github.com/hivecommons/hive/issues/15966)): the `/api/hub/activity` shape for anyone, never reading a cookie, token or `Authorization` header (credentials do not change the response). Only hives the registry lists as public on github.com, and only items and events not marked `private`; `totals`, per-hive `truncated` and `events_dropped`, hive owners and per-user grants are omitted. Same filters (`400` on an invalid one). The body is built at most once per 2 s per parsed filter and shared by every anonymous caller, so rows, `generated_at` and the `ETag` change at most every 2 s; query strings that parse to the default view share one entry. Toggling a hive's visibility drops the cache at once. `ETag` + `If-None-Match` → `304`; `Cache-Control: no-cache` | `pkg/hub/activity_public.go` | -| `GET` | `/api/hub/version` | Hub handler-specific | Hub Version | `pkg/hub/server.go:1774` | -| `DELETE` | `/api/hub/registry/{id}` | Hub handler-specific | Registry Delete | `pkg/hub/server.go:1784` | -| `GET` | `/api/hub/selfservice/status` | Hub auth | Self-service registration status: `{enabled, max_per_user, count, expiry}`; always answers so the dashboard can decide whether **Register your own hive** opens the form or the self-hosting guide ([#18060](https://github.com/hivecommons/hive/issues/18060)) | `pkg/hub/server.go:1788` | -| `GET` | `/api/hub/selfservice/hives` | Hub auth | The caller's own self-service (`byo-`) hives: `{hives[]}` of `{id, owner, org, repos, dashboard_url, created_at, ownership_checked_at, last_accepted_heartbeat_at, online}`; never a key or a hash. `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/server.go:1789` | -| `POST` | `/api/hub/selfservice/hives` | Hub auth | Register a self-hosted hive: body `{name, org, repos[], dashboard_url}`; the ID is `byo---` (the double hyphen keeps IDs unambiguous, since logins contain hyphens but never `--`). Proves `permissions.admin` on every `owner/name` repo with the caller's own stored GitHub token (`403` naming the refused repo, nothing stored); `400` invalid or reserved name, a login that contains `--` or starts or ends with `-`, bare-org or `.`/`..` repo, or non-`https`/private `dashboard_url`; `409` ID already registered; `429` over `HIVE_HUB_SELFSERVICE_MAX_PER_USER` (enforced again under the store lock, so concurrent registrations cannot exceed it). `201 {hive, key, hub_url, snippets{docker_compose, podman, kubernetes}}`: the raw key appears here once and only its hash is stored. `404` while the flag is off | `pkg/hub/server.go:1790` | +| `GET` | `/api/hub/version` | Hub handler-specific | Hub Version | `pkg/hub/server.go:1776` | +| `DELETE` | `/api/hub/registry/{id}` | Hub handler-specific | Registry Delete | `pkg/hub/server.go:1786` | +| `GET` | `/api/hub/selfservice/status` | Hub auth | Self-service registration status: `{enabled, max_per_user, count, expiry}`; always answers so the dashboard can decide whether **Register your own hive** opens the form or the self-hosting guide ([#18060](https://github.com/hivecommons/hive/issues/18060)) | `pkg/hub/server.go:1790` | +| `GET` | `/api/hub/selfservice/hives` | Hub auth | The caller's own self-service (`byo-`) hives: `{hives[]}` of `{id, owner, org, repos, dashboard_url, created_at, ownership_checked_at, last_accepted_heartbeat_at, online}`; never a key or a hash. `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/server.go:1791` | +| `POST` | `/api/hub/selfservice/hives` | Hub auth | Register a self-hosted hive: body `{name, org, repos[], dashboard_url}`; the ID is `byo---` (the double hyphen keeps IDs unambiguous, since logins contain hyphens but never `--`). Proves `permissions.admin` on every `owner/name` repo with the caller's own stored GitHub token (`403` naming the refused repo, nothing stored); `400` invalid or reserved name, a login that contains `--` or starts or ends with `-`, bare-org or `.`/`..` repo, or non-`https`/private `dashboard_url`; `409` ID already registered; `429` over `HIVE_HUB_SELFSERVICE_MAX_PER_USER` (enforced again under the store lock, so concurrent registrations cannot exceed it). `201 {hive, key, hub_url, snippets{docker_compose, podman, kubernetes}}`: the raw key appears here once and only its hash is stored. `404` while the flag is off | `pkg/hub/server.go:1792` | | `GET` | `/api/hub/v1` | Public | Hub registration protocol v1 discovery ([#18642](https://github.com/hivecommons/hive/issues/18642)): `{protocol, version, base_path, operations[], patch_fields[], limits{max_repos, max_per_user, expiry, key_rotation_overlap}, proof_methods[]}`. Readable without signing in so a client learns the limits before it hits a `4xx`. `proof_methods` is `["hub-session-token"]`: ownership is proven with the GitHub token stored at hub sign-in. `max_repos` is `HIVE_HUB_SELFSERVICE_MAX_REPOS`. `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/selfservice_v1_api.go` | | `POST` | `/api/hub/v1/registrations` | Hub auth | Register a self-hosted hive as a resource ([#18642](https://github.com/hivecommons/hive/issues/18642)): the same body, proof and refusals as `POST /api/hub/selfservice/hives` (including `429` over `HIVE_HUB_SELFSERVICE_MAX_PER_USER`), except that a repo list over `HIVE_HUB_SELFSERVICE_MAX_REPOS` answers `413 {error, limit: "max_repos", max_repos}` instead of `400`. `201 {registration, key, hub_url, snippets}` with `Location` and a strong `ETag` header; `registration` is the legacy view plus `etag` and `repo_proofs[{repo, checked_at}]` (when the owner's admin permission on each repo was last proven). The raw key appears once. `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/selfservice_v1_api.go` | | `GET` | `/api/hub/v1/registrations` | Hub auth | The caller's own registrations: `{registrations[]}`, each with its `etag` and `repo_proofs`; never a key or a hash | `pkg/hub/selfservice_v1_api.go` | @@ -65,26 +65,26 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `PATCH` | `/api/hub/v1/registrations/{id}` | Hub auth | Owner only, by hub session (a registration key is not accepted): change `repos` and/or `dashboard_url` in place with the heartbeat key kept valid ([#18642](https://github.com/hivecommons/hive/issues/18642)). Body: `repos` is a full list (replacement) or `{add[], remove[]}`; `dashboard_url` is an `https` URL or `""` to clear it. `If-Match` is required: `428` when absent, `412` carrying the current `ETag` when stale (checked before any GitHub call and again under the store lock). Only added repos are proven (`403` naming the first refused repo, nothing applied); kept repos keep their proof time and removed repos lose theirs. `org`, the owner, the ID and the keys are not editable: a body naming `org` or any other field is `400`, as is a list that would leave no repo. Over `HIVE_HUB_SELFSERVICE_MAX_REPOS` is `413 {error, limit: "max_repos", max_repos}`. Removing a repo the registration does not list is ignored; an edit that changes nothing answers `200` with the current `ETag` and does not bump the revision. `200 {registration}` with the new `ETag`; the key never appears. `404` for a missing hive, another user's hive and a hub admin who does not own it; `404` while `HIVE_HUB_SELFSERVICE_REGISTRATION` is off | `pkg/hub/selfservice_v1_patch.go` | | `POST` | `/api/hub/v1/registrations/{id}/keys` | Hub auth | Owner only: rotate the heartbeat key; the previous key keeps authenticating for the 10 minute overlap. `201 {id, key, hub_url, overlap, snippets}` (the legacy rotate answers `200`) with the new `ETag`; the raw key appears once. Optional `If-Match` (`412` when stale). A body asking for a grace window is refused with `400`: caller-chosen grace is a later rollout step | `pkg/hub/selfservice_v1_api.go` | | `DELETE` | `/api/hub/v1/registrations/{id}` | Hub auth | Owner or hub admin: revoke the key and remove the registry entry. `200 {removed, id}`. Optional `If-Match` (`412` when stale, carrying the current `ETag`) | `pkg/hub/selfservice_v1_api.go` | -| `POST` | `/api/hub/selfservice/hives/{id}/rotate` | Hub auth | Owner only: mint a new heartbeat key for `{id}`; the previous key keeps authenticating for `overlap` (10 minutes). `200 {id, key, hub_url, overlap, snippets}`, raw key once. Another user's hive, a missing hive and a hub admin who does not own it all get `404` | `pkg/hub/server.go:1791` | -| `DELETE` | `/api/hub/selfservice/hives/{id}` | Hub auth | Owner or hub admin: revoke the key and remove the registry entry. `200 {removed, id}`; another user's hive is `404` | `pkg/hub/server.go:1792` | -| `POST` | `/api/contribute/register` | Hub handler-specific | Contribute Proxy | `pkg/hub/server.go:1796` | -| `GET` | `/api/contribute/status` | Hub handler-specific | Contribute Status | `pkg/hub/server.go:1797` | -| `GET` | `/api/contribute/ws` | Hub handler-specific | Contribute WSProxy | `pkg/hub/server.go:1798` | -| `POST` | `/api/github/webhook` | Hub handler-specific | GitHub Webhook | `pkg/hub/server.go:1799` | +| `POST` | `/api/hub/selfservice/hives/{id}/rotate` | Hub auth | Owner only: mint a new heartbeat key for `{id}`; the previous key keeps authenticating for `overlap` (10 minutes). `200 {id, key, hub_url, overlap, snippets}`, raw key once. Another user's hive, a missing hive and a hub admin who does not own it all get `404` | `pkg/hub/server.go:1793` | +| `DELETE` | `/api/hub/selfservice/hives/{id}` | Hub auth | Owner or hub admin: revoke the key and remove the registry entry. `200 {removed, id}`; another user's hive is `404` | `pkg/hub/server.go:1794` | +| `POST` | `/api/contribute/register` | Hub handler-specific | Contribute Proxy | `pkg/hub/server.go:1798` | +| `GET` | `/api/contribute/status` | Hub handler-specific | Contribute Status | `pkg/hub/server.go:1799` | +| `GET` | `/api/contribute/ws` | Hub handler-specific | Contribute WSProxy | `pkg/hub/server.go:1800` | +| `POST` | `/api/github/webhook` | Hub handler-specific | GitHub Webhook | `pkg/hub/server.go:1801` | | `GET` | `/api/mail/hosts` | hive-mx bearer (`HIVE_HUB_MAIL_TOKEN`) | Hosts the mail receiver accepts `hive@` for ([#18395](https://github.com/hivecommons/hive/issues/18395)): `{hosts[]}`, sorted, lower-case: every hosted hive's subdomain host, vanity URL host and reported dashboard URL host. A host claimed by two hives is left out. `401` bad token, `404` while `HIVE_HUB_MAIL_TOKEN` is unset. `Cache-Control: no-store` | `pkg/hub/mail_relay.go` | | `POST` | `/api/mail/inbound` | hive-mx bearer (`HIVE_HUB_MAIL_TOKEN`) | One parsed mail delivery from hive-mx (`pkg/mailin/wire.Delivery`): JSON, or `multipart/form-data` for a large files delivery, routed by the `X-Hive-Mail-Delivery`, `X-Hive-Mail-Kind` and `X-Hive-Mail-Recipient` headers (at most 48 MiB, `HIVE_HUB_MAIL_MAX_BODY_BYTES`, this route only; without the headers, JSON of at most 8 MiB). The body is spooled to disk, never held whole in memory. The hub matches the recipient host to a hosted hive, signs the body byte for byte with that hive's relay key (`X-Hive-Relay-Timestamp`, `X-Hive-Relay-Signature-256` bound to `X-Hive-Relay-Delivery`) and forwards it to the spoke's `/api/meetings/invites`, `/api/inbox/email`, `/api/meetings/calendar-emails/proof` or `/api/inbox/email/report` (a refusal report, [#18699](https://github.com/hivecommons/hive/issues/18699)) by `kind`, behind the webhook relay's private-address guard and without following redirects. A files delivery that is multipart or larger than one piece (`HIVE_HUB_MAIL_CHUNK_BYTES`, 768 KiB) goes to `/api/inbox/email/chunk` in signed pieces instead ([#18564](https://github.com/hivecommons/hive/issues/18564)). Stores nothing once relayed; logs the delivery id only. `202` delivered; `400` invalid delivery; `404` no such hive; `413` too large; `422` the spoke refused it (permanent); `502`/`503` hive not reachable yet or unavailable (hive-mx asks the sender to retry) | `pkg/hub/mail_relay.go` | -| `GET` | `/gh-setup` | Hub handler-specific | GitHub App Setup Router | `pkg/hub/server.go:1802` | -| `GET` | `/learn` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1803` | -| `GET` | `/get-started` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1804` | -| `GET` | `/api/docs` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1807` | -| `GET` | `/api/reading-list` | Hub handler-specific | Reading List | `pkg/hub/server.go:1810` | -| `GET` | `/reading` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1811` | -| `GET` | `/cncf-reference-architecture` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1818` | -| `GET` | `/cncf-reference-architecture/console` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1819` | -| `GET` | `/cncf-reference-architecture/bluefin` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1820` | -| `GET` | `/{$}` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1837` | -| `GET` | `/og-card.png` | Hub handler-specific | OGCard | `pkg/hub/server.go:1842` | -| `GET` | `/` | Public | Static asset fallback (`http.FileServerFS` over the embedded `static/` tree) for any path no other route claims | `pkg/hub/server.go:1844` | +| `GET` | `/gh-setup` | Hub handler-specific | GitHub App Setup Router | `pkg/hub/server.go:1804` | +| `GET` | `/learn` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1805` | +| `GET` | `/get-started` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1806` | +| `GET` | `/api/docs` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1809` | +| `GET` | `/api/reading-list` | Hub handler-specific | Reading List | `pkg/hub/server.go:1812` | +| `GET` | `/reading` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1813` | +| `GET` | `/cncf-reference-architecture` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1820` | +| `GET` | `/cncf-reference-architecture/console` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1821` | +| `GET` | `/cncf-reference-architecture/bluefin` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1822` | +| `GET` | `/{$}` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1839` | +| `GET` | `/og-card.png` | Hub handler-specific | OGCard | `pkg/hub/server.go:1844` | +| `GET` | `/` | Public | Static asset fallback (`http.FileServerFS` over the embedded `static/` tree) for any path no other route claims | `pkg/hub/server.go:1846` | | `GET` | `/api/marketplace/workflows` | Public | Workflow-model marketplace index ([#17620](https://github.com/hivecommons/hive/issues/17620) phase 7): `{generatedAt, entries:[{name, version, hash, tier, description, source, states, columns, publishedAt, publishedBy, sourceSHA?, newerIngestAvailable, adoption:{}, ratings:{}, benchmarks:{}}]}`. Strong `ETag` (sha256 of the body) + `Cache-Control: no-cache`; `If-None-Match` → `304`. Tiers: `built-in`, `curated`, `ingested-unreviewed`, `local-published`. `404` when `HIVE_HUB_MARKETPLACE_DISABLED` is set | `pkg/hub/marketplace.go:36` | | `GET` | `/api/marketplace/workflows/{name}/{version}/bundle` | Public | One immutable signed bundle (`{apiVersion, model, profile, hash, createdAt, createdBy, tier}`), `Cache-Control: immutable`; `404` unknown, `400` malformed key | `pkg/hub/marketplace.go:37` | | `POST` | `/api/marketplace/workflows` | Spoke heartbeat bearer + `X-Hive-ID`, or Hub admin session | Publish a bundle. Body = bundle (≤ 4 MiB); the hub re-verifies the hash and recompiles the model before storing. Publisher may assert tier `local`/`local-published` (normalised to `local-published`) or `ingested-unreviewed`; `curated`/`built-in` require a hub admin session (`403` otherwise). `201 {published, created:true, entry}`; identical republish `200 created:false`; different content under an existing `name@version` `409`; verification failure `422`; unknown hive `403`; no hub secret `503` | `pkg/hub/marketplace.go:38` | diff --git a/src/docs/api-reference/snapshots-and-style.md b/src/docs/api-reference/snapshots-and-style.md index 54f0a86bae..880af5c538 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:48` | -| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1875` | +| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1878` | | `GET` | `/api/snapshot/frame-ancestors` | Public | Snapshot framing allowlist | `pkg/dashboard/api.go:84` | | `GET` | `/api/snapshot` | Public | Snapshot data | `pkg/dashboard/api.go:85` | | `GET` | `/snapshot` | Public | Public read-only snapshot page | `pkg/dashboard/api.go:86` | diff --git a/src/docs/fleet-health.md b/src/docs/fleet-health.md index 2819f2b638..7a5dace92a 100644 --- a/src/docs/fleet-health.md +++ b/src/docs/fleet-health.md @@ -173,6 +173,7 @@ agents down, advisory stale, …) deliberately get none rather than a guess. | Error streak | "agent NAME model calls failing (N consecutive) — pin a working model" | red | Pin a working model on the agent card | spoke dashboard agent card | | Consent wedge | "agent(s) NAME stuck at Copilot consent — restarting in a loop" | amber | Complete the Copilot consent flow on the live pod dashboard | spoke dashboard | | No cadence | "agent(s) NAME enabled but never kicked — set cadences" | amber | Set cadences on the agent card | spoke dashboard agent card | +| PR gate cannot be posted | "PR-contents gate cannot be posted: the Hive App has no Commit statuses write grant" (or "GitHub refused the gate's commit status write") | red when a required context depends on the gate, else amber | Accept the Hive App's pending Commit statuses (read and write) permission request in the organization settings, then press Re-check | GitHub App settings (organization owner) | | Hold stale | "awaiting human review — N held for approval" | amber | Review the needs-human queue | the repo's PR list (direct link) | | Channel lag | "spoke lags its channel — N commits behind stable" | amber | Check auto-upgrade / force rollout | hub fleet version controls | @@ -233,6 +234,10 @@ stamp on every kick attempt; once you complete the consent flow on the spoke dashboard, no new restarts occur and the agent ages out of the list by itself. +### PR gate cannot be posted + +When `auto_merge.pr_gate` is set for a repository (see [GitHub App setup](github-app-setup.md#pr-contents-gate-posted-by-the-hive)) the spoke reads the installation's granted Commit statuses permission at startup and every 15 minutes, and records any 403 on a status write per repository. A missing grant forces the gate off and never promotes it; a refused write is not retried for 15 minutes. The spoke reports the cause (`grant-missing` or `write-refused`) and whether a required context depends on the gate in its heartbeat. The hub turns the verdict **red** when the gate cannot be posted and a required check of a scoped repository is one the gate posts (or the repository's required set is not declared, which counts as dependent), because merges would stall behind a check nobody can post. Otherwise the verdict is **amber**. Before the 2026-12-02 cutoff a repository in `shadow` mode is judged amber at worst, since the workflow still supplies the required check; from the cutoff, or in `enforce`, a dependency makes it red. A harder red keeps its own headline. A hive without the setting reports nothing and is judged exactly as before. The cause clears with the next beat once the grant is accepted. + ### No cadence An agent that is enabled and governor-kickable but appears in **no** mode's diff --git a/src/docs/github-app-setup.md b/src/docs/github-app-setup.md index cbfa025330..96c889c456 100644 --- a/src/docs/github-app-setup.md +++ b/src/docs/github-app-setup.md @@ -230,10 +230,12 @@ auto_merge: - `off` posts nothing and changes nothing. - `shadow` posts only `verify PR contents (hive)` (a name no branch rule requires) on each PR head and compares the verdicts with the workflow's own `PR Type`, `PR Issue` and `verify PR contents` results. Nothing a branch rule reads can change. -- `enforce` is accepted in the file but runs as `shadow` until the grant check and the visible failure paths ship; it never posts the real names yet. +- `enforce` is accepted in the file but runs as `shadow` until the backstop sweep ships; it never posts the real names yet. The verdict logic is a Go port of the PR title verifier (`PR Type`, `PR Issue`); both implementations replay one shared golden corpus in CI, so they cannot drift. The poster can write exactly four contexts: `verify PR contents`, `PR Type`, `PR Issue` and `verify PR contents (hive)`. Any other context, `DCO` included, is refused in code before a request is made. Drafts and closed PRs are skipped, the head is re-read from GitHub before posting, and an identical status is never posted twice. +**Grant check and visible failure.** The gate never fails silently. At startup and every 15 minutes the hive reads the Commit statuses permission the installation was actually granted (an owner must accept a permission change before an installation holds it). A missing grant forces the gate off, never promotes it to `enforce`, and logs `pr-gate: the installation has no Commit statuses write grant, the gate is forced off`. A 403 on a status write is recorded per repository, counted, and not retried for 15 minutes. While either holds, the dashboard shows a **PR-contents gate cannot be posted** banner that names the installation, says what is missing and where an owner accepts it (the App's pending permission request in the organization settings), and counts the days left before the cutoff. The hub's hive health shows the same cause with a remediation hint: red when a required check depends on the gate, amber otherwise (see [fleet health](fleet-health.md#pr-gate-cannot-be-posted)). In `enforce`, a PR whose required gate context is missing for this reason shows the held reason `unauthorized:post-pr-gate-status` ("the hive's GitHub App is not permitted to post pr gate status") instead of a bare `required-check-missing`. + **Verify in shadow.** Open or edit a PR in a listed repository. Within seconds its **Checks** box shows a status named `verify PR contents (hive)` whose description reads `PR Type: success; PR Issue: success` (or `failure`). In the hive log, `pr-gate: status posted` names the repository, head and context, and `pr-gate: comparison with the workflow result agrees` (or `DISAGREES`, logged as a warning) appears when the workflow's check lands on the same head. A `pr-gate: status refused with 403` line means the installation has no Commit statuses write grant: accept the App's pending permission request in the organization settings (see [Adding a permission to an existing App](#adding-a-permission-to-an-existing-app)). ## Install and configure Hive diff --git a/src/docs/running-at-level-6.md b/src/docs/running-at-level-6.md index cec652d85e..0a79ede25f 100644 --- a/src/docs/running-at-level-6.md +++ b/src/docs/running-at-level-6.md @@ -243,7 +243,9 @@ workflow. Default is `off`. `pr-gate: comparison with the workflow result agrees`. See [the setup note](github-app-setup.md#pr-contents-gate-posted-by-the-hive). -**Limit:** needs the Hive App's Commit statuses read and write grant; `shadow` +**Limit:** needs the Hive App's Commit statuses read and write grant. A missing +grant forces the gate off and raises a dashboard banner and a hub health cause +(red when a required check depends on the gate, amber otherwise); `shadow` cannot satisfy a required context, and `enforce` runs as `shadow` for now. #### H3. Leave no-CI exceptions empty diff --git a/src/pkg/dashboard/api_pr_gate.go b/src/pkg/dashboard/api_pr_gate.go index 75a5d4d5ac..0f57a73b9f 100644 --- a/src/pkg/dashboard/api_pr_gate.go +++ b/src/pkg/dashboard/api_pr_gate.go @@ -36,6 +36,9 @@ func (s *Server) prGateInstance() *github.PRGate { return } s.prGate = github.NewPRGate(s.deps.GHClient, s.prGateModeOf, s.webhookLogger()) + // The merge lanes read the gate for the held reason of a PR whose + // required context the hive cannot post. + s.prGate.RegisterAsDefault() }) return s.prGate } @@ -110,3 +113,84 @@ func (s *Server) observePRGateEvent(event string, body []byte) string { }() return "scheduled" } + +// prGateGrantRefreshTimeout bounds one installation grant read. +const prGateGrantRefreshTimeout = 30 * time.Second + +// prGateScope returns the repositories auto_merge.pr_gate applies to. +func (s *Server) prGateScope() []string { + if s == nil || s.deps == nil || s.deps.Config == nil { + return nil + } + var scope []string + for _, repo := range s.deps.Config.AutoMerge.PRGate.Repos { + if repo = strings.TrimSpace(repo); repo != "" { + scope = append(scope, repo) + } + } + return scope +} + +// prGateDependsOnRequired reports whether a required context of any scoped +// repository is one the gate posts. A repository whose required set is not +// declared in config counts as depending on it: the operator listed it for the +// gate because its merge check comes from the gate's workflow. +func (s *Server) prGateDependsOnRequired(scope []string) bool { + am := s.deps.Config.AutoMerge + for _, repo := range scope { + set, known := am.RequiredCheckSetForRepo(repo) + if !known { + return true + } + for name := range set { + if github.IsPRGateCheckName(name) { + return true + } + } + } + return false +} + +// PRGateHealth is the gate's state for /api/status, the spoke banner and the +// hub heartbeat. It is nil unless at least one repository is configured for +// the gate, so a hive that never sets auto_merge.pr_gate reports nothing and +// makes no request. A stale installation grant is re-read in the background. +func (s *Server) PRGateHealth() *github.PRGateHealth { + scope := s.prGateScope() + if len(scope) == 0 || s.deps == nil || s.deps.Config == nil { + return nil + } + active := false + for _, repo := range scope { + if s.prGateModeOf(repo) != config.PRGateModeOff { + active = true + break + } + } + if !active { + return nil + } + g := s.prGateInstance() + if g == nil { + return nil + } + if g.GrantStale() { + go func() { + ctx, cancel := context.WithTimeout(context.Background(), prGateGrantRefreshTimeout) + defer cancel() + g.RefreshGrant(ctx) + }() + } + return g.Health(scope, s.prGateDependsOnRequired(scope), time.Now()) +} + +// PRGateCause is the heartbeat view of PRGateHealth: why the gate cannot be +// posted ("" when it can, or is not configured) and whether a required +// context depends on it. +func (s *Server) PRGateCause() (cause string, dependsOn bool) { + h := s.PRGateHealth() + if h == nil { + return "", false + } + return h.Cause, h.DependsOnGate +} diff --git a/src/pkg/dashboard/api_pr_gate_test.go b/src/pkg/dashboard/api_pr_gate_test.go index 5d83562bdd..260cda73d5 100644 --- a/src/pkg/dashboard/api_pr_gate_test.go +++ b/src/pkg/dashboard/api_pr_gate_test.go @@ -26,12 +26,14 @@ const ( // fakePRGateGitHub answers the two calls the gate makes: re-reading the PR and // writing a commit status. It records the statuses it was asked to write. type fakePRGateGitHub struct { - mu sync.Mutex - title string - reads int - posts []map[string]string - paths []string - posted chan struct{} + mu sync.Mutex + title string + reads int + posts []map[string]string + // statusCode, when set, answers every status write instead of 201. + statusCode int + paths []string + posted chan struct{} } func (f *fakePRGateGitHub) ServeHTTP(w http.ResponseWriter, r *http.Request) { @@ -52,9 +54,15 @@ func (f *fakePRGateGitHub) ServeHTTP(w http.ResponseWriter, r *http.Request) { f.mu.Lock() f.posts = append(f.posts, body) f.paths = append(f.paths, path) + code := f.statusCode f.mu.Unlock() - w.WriteHeader(http.StatusCreated) - _, _ = w.Write([]byte(`{"id": 1}`)) + if code != 0 { + w.WriteHeader(code) + _, _ = w.Write([]byte(`{"message": "Resource not accessible by integration"}`)) + } else { + w.WriteHeader(http.StatusCreated) + _, _ = w.Write([]byte(`{"id": 1}`)) + } f.posted <- struct{}{} default: http.NotFound(w, r) @@ -156,3 +164,88 @@ func TestPRGateWebhookIgnoresOtherEvents(t *testing.T) { t.Errorf("closed action produced %q", got) } } + +func TestPRGateHealthIsAbsentWhileOff(t *testing.T) { + for name, cfg := range map[string]config.PRGateConfig{ + "unset": {}, + "off": {Mode: "off", Repos: []string{prGateTestRepo}}, + "no repos": {Mode: "shadow"}, + "scope only": {Repos: []string{prGateTestRepo}}, + } { + s, _ := prGateTestServer(t, cfg) + if h := s.PRGateHealth(); h != nil { + t.Errorf("%s: health = %+v, want nil", name, h) + } + if cause, dep := s.PRGateCause(); cause != "" || dep { + t.Errorf("%s: cause = %q dependsOn = %t", name, cause, dep) + } + } +} + +func TestPRGateHealthReportsAWriteRefusal(t *testing.T) { + s, fake := prGateTestServer(t, config.PRGateConfig{Mode: "shadow", Repos: []string{prGateTestRepo}}) + fake.statusCode = http.StatusForbidden + h := s.PRGateHealth() + if h == nil || h.Cause != "" || h.Configured != "shadow" { + t.Fatalf("before any write: %+v", h) + } + s.observePRGateEvent("pull_request", readPRGateFixture(t, "pull_request_opened.json")) + select { + case <-fake.posted: + case <-time.After(prGateTestWait): + t.Fatal("no status write was attempted") + } + deadline := time.Now().Add(prGateTestWait) + for time.Now().Before(deadline) && s.prGateInstance().Snapshot()[prGateTestRepo].Forbidden == 0 { + <-time.After(10 * time.Millisecond) + } + h = s.PRGateHealth() + if h == nil || h.Cause != github.PRGateCauseWriteRefused || len(h.ForbiddenRepos) != 1 || h.Message == "" { + t.Fatalf("after a 403: %+v", h) + } + if h.Cutoff != "2026-12-02" { + t.Errorf("cutoff = %q", h.Cutoff) + } +} + +func TestPRGateDependsOnRequired(t *testing.T) { + scope := []string{prGateTestRepo} + tests := []struct { + name string + am config.AutoMergeConfig + want bool + }{ + {"required set unknown", config.AutoMergeConfig{}, true}, + {"global set names the gate context", config.AutoMergeConfig{RequiredChecks: []string{"build-and-test", "verify PR contents"}}, true}, + {"global set without a gate context", config.AutoMergeConfig{RequiredChecks: []string{"build-and-test", "DCO"}}, false}, + {"the shadow name is not a dependency", config.AutoMergeConfig{RequiredChecks: []string{"verify PR contents (hive)"}}, false}, + {"per-repo override wins", config.AutoMergeConfig{ + RequiredChecks: []string{"verify PR contents"}, + Repos: map[string]config.AutoMergeRepoConfig{prGateTestRepo: {RequiredChecks: []string{"build-and-test"}}}, + }, false}, + } + for _, tc := range tests { + s, _ := prGateTestServer(t, config.PRGateConfig{Mode: "shadow", Repos: scope}) + s.deps.Config.AutoMerge.RequiredChecks, s.deps.Config.AutoMerge.Repos = tc.am.RequiredChecks, tc.am.Repos + if got := s.prGateDependsOnRequired(scope); got != tc.want { + t.Errorf("%s: depends = %t, want %t", tc.name, got, tc.want) + } + } +} + +func TestPRGateBannerMarkupPinsTheContract(t *testing.T) { + html := spokeIndexHTML(t) + for _, snippet := range []string{ + `id="pr-gate-banner"`, + "function renderPRGateBanner(data)", + "data.prGate", + "gate.daysUntilCutoff", + "Commit statuses read and write grant", + "pending permission request", + "renderPRGateBanner(data);", + } { + if !strings.Contains(html, snippet) { + t.Errorf("spoke index.html is missing %q", snippet) + } + } +} diff --git a/src/pkg/dashboard/server.go b/src/pkg/dashboard/server.go index 4ddbe6c37a..a04953cc94 100644 --- a/src/pkg/dashboard/server.go +++ b/src/pkg/dashboard/server.go @@ -768,6 +768,9 @@ type StatusPayload struct { Capabilities *FrontendCapabilities `json:"capabilities,omitempty"` GitHubAppPermIssue string `json:"githubAppPermIssue,omitempty"` GitHubAppState string `json:"githubAppState,omitempty"` + // PRGate is the PR-contents gate's state while auto_merge.pr_gate is + // configured for any repository (hivecommons/hive#19038); absent otherwise. + PRGate *github.PRGateHealth `json:"prGate,omitempty"` // GitHubAppInstallMissing is CONFIG TRUTH, independent of any auth probe // or classification: a real App is named (app_id set, not the placeholder) // but installation_id is 0. That state alone means every token is a @@ -2914,6 +2917,7 @@ func (s *Server) UpdateStatusIfFresh(status *StatusPayload, buildEpoch uint64) b status.GitHubAppPermIssue = s.githubAppPermIssue status.GitHubAppState = s.githubAppState s.githubAppMu.RUnlock() + status.PRGate = s.PRGateHealth() // CONFIG-TRUTH OVERRIDE, applied last so no probe-derived field can veto // it: a real App with installation_id 0 must light the install banner the diff --git a/src/pkg/dashboard/stage_tracker_caption.go b/src/pkg/dashboard/stage_tracker_caption.go index 555faf4816..4fd8466d63 100644 --- a/src/pkg/dashboard/stage_tracker_caption.go +++ b/src/pkg/dashboard/stage_tracker_caption.go @@ -497,6 +497,7 @@ func unauthorizedStepWords(step string) string { const ( stageTrackerUnauthorizedApproveRuns = "The hive bot's GitHub App is missing the 'actions: write' permission needed to approve the workflow runs GitHub is holding for this head, so a person has to take that step: click Approve and run on the PR's checks banner (or the Actions tab); the `hive:unauthorized` comment on the PR lists the run ids. Hive resumes and clears the label once the required checks report." stageTrackerUnauthorizedGeneric = "The hive bot's GitHub App is missing a permission needed for the next step, so a person has to take that step. The `hive:unauthorized` comment on the PR names the permission and the action; hive resumes and clears the label once it's done." + stageTrackerUnauthorizedPRGate = "The hive posts the required PR-contents check itself, and its GitHub App installation has no Commit statuses write grant (or GitHub refused the write), so that check will not report on this head. An organization owner accepts the App's pending permission request in the organization settings; the hive resumes on its next sweep." stageTrackerUnauthorizedMergeWF = "The hive bot's GitHub App is missing the 'workflows: write' permission needed to merge this owner-approved PR that edits .github/workflows files, so a person has to take that step: click Merge on GitHub (the approval already stands), or grant the App Workflows: Read and write so the hive can merge such PRs itself." ) @@ -515,6 +516,9 @@ func stageTrackerUnauthorized(reason string) (step, tip string) { if rest == stageengineprstage.UnauthorizedStepMergeWorkflowPath { return step, stageTrackerUnauthorizedMergeWF } + if rest == stageengineprstage.UnauthorizedStepPostPRGateStatus { + return step, stageTrackerUnauthorizedPRGate + } return step, "The hive bot's GitHub App is missing the permission needed to " + step + ", so a person has to take that step. The `hive:unauthorized` comment on the PR names the permission and the action; hive resumes and clears the label once it's done." } diff --git a/src/pkg/dashboard/static-src/html/root-notices.html b/src/pkg/dashboard/static-src/html/root-notices.html index 412a495aeb..c342fd47a0 100644 --- a/src/pkg/dashboard/static-src/html/root-notices.html +++ b/src/pkg/dashboard/static-src/html/root-notices.html @@ -54,6 +54,13 @@ + +