Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-18915-build-contains-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Added "does this build contain PR #N" lookups ([#18915](https://github.com/hivecommons/hive/issues/18915)): `GET /api/saas/build-contains?q=<PR number or SHA>` on the hub answers `yes`, `no` or `unknown` for each hive you can see, and `GET /api/version/contains?q=` answers for a hive's own running build. The answer comes from git ancestry of the commit the hive already reports; a commit that cannot be resolved is always `unknown`, and a PR outside the build's history is `no`. No new heartbeat field; see `src/docs/telemetry.md` for the on-demand GitHub request.
79 changes: 79 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -6536,6 +6536,85 @@
}
}
},
"/api/version/contains": {
"get": {
"tags": [
"System"
],
"summary": "Does the running build contain a PR or commit",
"description": "Answers from git ancestry, computed from the commit this hive reports running (the same value as `hash` on `/api/version`) and the repository history. `contains` is `yes` when the PR's merge commit (or the commit itself) is the running commit or one of its ancestors, `no` when ancestry was resolved and it is not (including a PR that was never merged), and `unknown` when it cannot be established: the commit is not resolvable in the repository history, the lookup failed, or this hive has no GitHub access. `unknown` is never a guess. Reads the public repository through the hive's existing GitHub client; sends only commit SHAs and a PR number.",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"description": "A PR number (`123`, `#123`, `PR 123`; up to six digits) or a commit SHA (7 to 40 hex characters)",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Containment answer",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"pr",
"commit"
]
},
"pr": {
"type": "integer"
},
"commit": {
"type": "string"
}
}
},
"commit": {
"type": "string",
"description": "The commit whose presence was tested: the PR's merge commit, or the SHA asked about"
},
"running": {
"type": "string",
"description": "The commit this hive reports running"
},
"channel": {
"type": "string",
"description": "The release channel the hive's image follows, when known"
},
"contains": {
"type": "string",
"enum": [
"yes",
"no",
"unknown"
]
},
"reason": {
"type": "string",
"description": "Why the answer is unknown, or why a PR is not contained"
}
}
}
}
}
},
"400": {
"description": "The query is neither a PR number nor a commit SHA"
}
}
}
},
"/api/version/release-notes": {
"get": {
"tags": [
Expand Down
1 change: 1 addition & 0 deletions src/docs/api-reference/health-status-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ 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=<sha>&to=<channel-branch-tag-or-sha>` 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` |
| `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=<PR number or commit SHA>` 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:70` |
| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1781` |
| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1782` |
Expand Down
1 change: 1 addition & 0 deletions src/docs/api-reference/hub-saas.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `POST` | `/api/saas/admin/rotate-master-key` | Hub admin | Rotate Token Master Key (double-call refused) | `pkg/hub/saas.go:501` |
| `GET` | `/api/saas/admin/advisory-diagnostics` | Hub admin | Fleet Advisory/App-State Diagnostics | `pkg/hub/saas.go:527` |
| `POST` | `/api/saas/hives/bulk` | Hub auth | Bulk Hive Action | `pkg/hub/saas_bulk.go:89` |
| `GET` | `/api/saas/build-contains` | Hub auth | Does each hive's running build contain a PR or commit ([#18915](https://github.com/hivecommons/hive/issues/18915)): `?q=<PR number or commit SHA>` returns `{query:{kind,pr?,commit?}, commit?, reason?, hives:[{id,name?,commit?,channel?,contains,reason?}]}` for the hives the caller can see in My Hives. `contains` is `yes`, `no` or `unknown`, computed from the hive's already-reported commit and repository ancestry: `yes` when the PR's merge commit (or the SHA) is the running commit or an ancestor, `no` when ancestry resolved and it is not (an unmerged PR is `no`), `unknown` (with `reason`) when the commit cannot be resolved or the lookup failed. Never a guess. `400` when `q` is neither a PR number nor a SHA. See [Build visibility](../release-channels.md) | `pkg/hub/build_contains.go:225` |
| `GET` | `/api/saas/me/country` | Hub auth | My Country Get | `pkg/hub/saas.go:391` |
| `PUT` | `/api/saas/me/country` | Hub auth | My Country Set (write blocked while impersonating) | `pkg/hub/saas.go:392` |
| `POST` | `/api/saas/lite/enroll` | Hub auth | Hive Lite Enroll | `pkg/hub/saas.go:393` |
Expand Down
19 changes: 19 additions & 0 deletions src/docs/release-channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -285,3 +285,22 @@ The My Hives **GROUP BY** selector includes an `Upgrade state` dimension ([#3805
`GET /api/version/release-notes?from=<sha>&to=<channel-or-sha>` answers "what changes if I upgrade from here to there?" ([#11065](https://github.com/hivecommons/hive/issues/11065)). The dashboard reads `CHANGELOG.md` at both revisions (through the configured GitHub credential, falling back to the public raw endpoint) and returns the `## <date> (vX.Y.Z)` sections that exist at `to` but not at `from`, newest first, grouped Added / Changed / Fixed / Security / Deprecated. The diff comes from repo content, never version arithmetic, so channel and nightly heads work. When `to` is not a release tag, `changelog.d/` fragments that are new at `to` are listed under an `Unreleased (in this build)` section, categorised by filename prefix. If the notes cannot be fetched the endpoint still returns 200 with `source: "unavailable"` and a reason, so an upgrade is never blocked on it. Responses are cached per (from, to) pair for an hour (the cache holds at most 64 pairs, evicting the oldest) and capped at 400 entries (`truncated: true` when cut). Because each uncached build can cost a few hundred GitHub content reads against the hive's own credential, uncached builds are admitted at most 2 at a time and 8 per 10 minutes process-wide; a request past that limit still returns 200 with `source: "unavailable"` and a retry hint, while already-cached pairs keep being served.

When a hub-managed spoke is upgraded without the operator clicking anything, its dashboard shows a dismissible banner at the top of the overview for owners and mergers: "Upgraded <old> → <new>: N releases. What changed ▸" ([#11067](https://github.com/hivecommons/hive/issues/11067)). Expanding it opens these release notes in a read-only modal. It appears once per upgrade per browser and never on a first visit. See [Dashboard-triggered standalone upgrades](dashboard-standalone-upgrades.md#release-notes-before-and-after-an-upgrade).

## Does this build contain PR #N?

"Merged" is not "deployed". Image tags move, a build can be untagged, and a digest says nothing about history, so the only sound answer is git ancestry ([#18915](https://github.com/hivecommons/hive/issues/18915)). Two read endpoints answer it from the commit a hive already reports running:

- `GET /api/saas/build-contains?q=<PR number or SHA>` on the hub, one answer per hive the caller can see in My Hives.
- `GET /api/version/contains?q=<PR number or SHA>` on a hive, for that hive's own running build.

`q` is a PR number (`123`, `#123`, `PR 123`; up to six digits) or a commit SHA (7 to 40 hex characters). A PR resolves to its merge commit. Each answer is one of:

| `contains` | Meaning |
|---|---|
| `yes` | The merge commit (or the SHA) is the running commit or one of its ancestors. |
| `no` | Ancestry was resolved and it is not in the running build's history. A PR that was never merged is `no` for every hive. |
| `unknown` | Ancestry could not be established, and `reason` says why: the hive reports no usable commit, the commit is not in the repository history the hub can read (unpublished, force-pushed or from a fork), the PR does not exist, or the lookup failed. `unknown` is never a guess; try again or check the commit by hand. |

The lookup reads the public repository through the hub's existing read-only GitHub identity (or the hive's own GitHub client for the hive endpoint) and sends only commit SHAs and a PR number. It adds no heartbeat field: the commit and image reference are what the hive already reports. One lookup compares at most 40 distinct running commits; hives past that answer `unknown`.

A channel image can sit on an older commit than the newest merge (the "latest merged, not yet built" gap). The My Hives rows already carry both numbers separately: `behindTargetSHA` is the newest commit whose image is published for the hive's channel, and `branchTipSHA` is the newest merged commit on the hive's branch. A `no` for a PR merged after the channel's newest image therefore means "merged, not yet built", not "lost".
Loading
Loading