Skip to content

Commit f249710

Browse files
Qualify canonical relay images for staged delivery (#6781)
## Why Phase 1 of progressive delivery needs an explicit eligibility boundary before deployment automation can safely consume relay artifacts. Today the canonical Docker workflow can publish independently of the same-SHA CI result, the relay does not expose its source/build identity, and the Helm chart only renders mutable tags. The existing `ghcr.io/block/buzz-staging-dev` workflow in #6709 remains a manual pre-merge preview lane. It is deliberately not a canonical promotion input. ## What changed - Compile the full source SHA and GitHub Actions build identity into canonical relay binaries and expose it at `/_status`. - Gate creation of tagged multi-architecture manifests on the latest exact-SHA `CI` push run succeeding on `main` or `release`. - Preserve the signed SLSA provenance and add a signed, release-only deployment-eligibility predicate with source, build run, qualifying CI run, and exact compatible Buzz chart version. - Keep failed or pending builds untagged and without an eligibility predicate; preview-package artifacts are excluded by package and signer contract. - Add optional `image.digest` support to Buzz chart `0.1.8`, retaining the existing tag fallback. - Document verification and the intentional boundary between image/chart compatibility and backwards-compatible database migrations. ## Risk and rollout Canonical tag publication now waits for same-SHA CI and fails closed when the newest matching run fails. Per-architecture blobs may remain untagged after a failed qualification; they are not promotion inputs. Debug manifests are also CI-gated but do not receive the release eligibility predicate. There are no migration or schema-orchestration changes. The companion BuilderBot infrastructure PR will pin a separately verified canonical main digest and expose a read-only running-deployment inspection command. Signed eligibility is available only for artifacts published after this workflow lands. ## Verification - Blox: workflow contract fixtures, including stale-green rejection and predicate structure - Blox: `actionlint` for `ci.yml` and `docker.yml` - Blox: 46 Helm unit tests, chart lint, and production/quickstart render fixtures - Blox: relay status unit test, workspace Rust formatting, and workspace all-target clippy - Live evidence: exact-SHA CI selector chose successful run `32857345153` for source `9d1e4b257657f382d3111ce748f3da8d063b7671` - Existing canonical digest provenance verified with `gh attestation verify` ## References - #6709 — developer-preview precursor; intentionally separate from canonical eligibility - `docs/deployment-identity.md` *Generated with Codex* --------- Signed-off-by: Luke Tornquist <[email protected]>
1 parent 7ba1197 commit f249710

17 files changed

Lines changed: 467 additions & 10 deletions

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,8 @@ jobs:
7575
- '.github/workflows/ci.yml'
7676
- name: Release workflow source contract
7777
run: scripts/test-release-ref-contract.sh
78+
- name: Relay image eligibility contract
79+
run: scripts/test-relay-image-eligibility-workflow.sh
7880
- name: Desktop release candidate contract
7981
run: scripts/test-desktop-release-candidate.sh
8082
- name: OSS desktop promotion contract

‎.github/workflows/docker.yml‎

Lines changed: 149 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ on:
4949
- "Dockerfile.push-gateway"
5050
- ".dockerignore"
5151
- ".github/workflows/docker.yml"
52+
- "deploy/charts/buzz/Chart.yaml"
53+
- "scripts/create-deployment-eligibility-predicate.jq"
54+
- "scripts/select-qualified-ci-run.jq"
55+
- "scripts/test-relay-image-eligibility-workflow.sh"
5256
- "Cargo.toml"
5357
- "Cargo.lock"
5458
- "rust-toolchain.toml"
@@ -172,6 +176,10 @@ jobs:
172176
target: runtime
173177
platforms: ${{ matrix.platform }}
174178
labels: ${{ steps.meta.outputs.labels }}
179+
build-args: |
180+
BUZZ_SOURCE_SHA=${{ github.sha }}
181+
BUZZ_BUILD_ID=github-actions:${{ github.run_id }}:${{ github.run_attempt }}
182+
BUZZ_BUILD_URL=https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}/attempts/${{ github.run_attempt }}
175183
# Push by digest, not by tag — the merge job assembles the tags
176184
# into one multi-arch manifest. This is what makes the native-arm
177185
# matrix possible.
@@ -190,6 +198,10 @@ jobs:
190198
target: runtime-debug
191199
platforms: ${{ matrix.platform }}
192200
labels: ${{ steps.meta.outputs.labels }}
201+
build-args: |
202+
BUZZ_SOURCE_SHA=${{ github.sha }}
203+
BUZZ_BUILD_ID=github-actions:${{ github.run_id }}:${{ github.run_attempt }}
204+
BUZZ_BUILD_URL=https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}/attempts/${{ github.run_attempt }}
193205
outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=${{ github.event_name != 'pull_request' }}
194206
cache-from: |
195207
type=registry,ref=${{ env.IMAGE_NAME }}-buildcache:${{ matrix.arch }}
@@ -222,11 +234,86 @@ jobs:
222234
if-no-files-found: error
223235
retention-days: 1
224236

237+
qualify:
238+
name: Qualify relay image source
239+
if: github.event_name != 'pull_request'
240+
runs-on: ubuntu-24.04
241+
timeout-minutes: 70
242+
permissions:
243+
actions: read
244+
contents: read
245+
outputs:
246+
source_sha: ${{ steps.qualify.outputs.source_sha }}
247+
ci_run_id: ${{ steps.qualify.outputs.ci_run_id }}
248+
ci_run_attempt: ${{ steps.qualify.outputs.ci_run_attempt }}
249+
ci_run_url: ${{ steps.qualify.outputs.ci_run_url }}
250+
chart_version: ${{ steps.qualify.outputs.chart_version }}
251+
steps:
252+
- name: Checkout source
253+
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
254+
with:
255+
persist-credentials: false
256+
257+
- name: Require successful same-SHA CI run
258+
id: qualify
259+
env:
260+
GH_TOKEN: ${{ github.token }}
261+
SOURCE_SHA: ${{ github.sha }}
262+
run: |
263+
set -euo pipefail
264+
265+
if [[ ! "$SOURCE_SHA" =~ ^[0-9a-f]{40}$ ]]; then
266+
echo "::error::Invalid source SHA: $SOURCE_SHA"
267+
exit 1
268+
fi
269+
270+
deadline=$((SECONDS + 3900))
271+
while (( SECONDS < deadline )); do
272+
payload=$(gh api \
273+
"/repos/${GITHUB_REPOSITORY}/actions/workflows/ci.yml/runs?head_sha=${SOURCE_SHA}&event=push&per_page=100")
274+
successful_run=$(jq -c --arg source_sha "$SOURCE_SHA" \
275+
-f "$GITHUB_WORKSPACE/scripts/select-qualified-ci-run.jq" <<<"$payload")
276+
277+
if [[ -n "$successful_run" ]]; then
278+
ci_run_id=$(jq -r '.id' <<<"$successful_run")
279+
ci_run_attempt=$(jq -r '.run_attempt' <<<"$successful_run")
280+
ci_run_url=$(jq -r '.html_url' <<<"$successful_run")
281+
chart_version=$(awk '/^version:/ { print $2; exit }' deploy/charts/buzz/Chart.yaml)
282+
if [[ ! "$chart_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
283+
echo "::error::Invalid Buzz chart version: $chart_version"
284+
exit 1
285+
fi
286+
{
287+
echo "source_sha=$SOURCE_SHA"
288+
echo "ci_run_id=$ci_run_id"
289+
echo "ci_run_attempt=$ci_run_attempt"
290+
echo "ci_run_url=$ci_run_url"
291+
echo "chart_version=$chart_version"
292+
} >>"$GITHUB_OUTPUT"
293+
echo "Qualified source $SOURCE_SHA with CI run $ci_run_id (attempt $ci_run_attempt)."
294+
exit 0
295+
fi
296+
297+
matching=$(jq --arg source_sha "$SOURCE_SHA" '[.workflow_runs[] | select(.head_sha == $source_sha) | select(.event == "push") | select(.head_branch == "main" or .head_branch == "release")] | length' <<<"$payload")
298+
pending=$(jq --arg source_sha "$SOURCE_SHA" '[.workflow_runs[] | select(.head_sha == $source_sha) | select(.event == "push") | select(.head_branch == "main" or .head_branch == "release") | select(.status != "completed")] | length' <<<"$payload")
299+
if (( matching > 0 && pending == 0 )); then
300+
echo "::error::No successful CI run exists for source $SOURCE_SHA"
301+
jq -r --arg source_sha "$SOURCE_SHA" '.workflow_runs[] | select(.head_sha == $source_sha) | "run=\(.id) attempt=\(.run_attempt) status=\(.status) conclusion=\(.conclusion)"' <<<"$payload"
302+
exit 1
303+
fi
304+
305+
echo "Waiting for same-SHA CI qualification ($matching matching, $pending pending)..."
306+
sleep 30
307+
done
308+
309+
echo "::error::Timed out waiting for successful CI qualification of $SOURCE_SHA"
310+
exit 1
311+
225312
merge:
226313
name: Merge ${{ matrix.variant }} multi-arch manifest
227314
if: github.event_name != 'pull_request'
228315
runs-on: ubuntu-24.04
229-
needs: build
316+
needs: [build, qualify]
230317
timeout-minutes: 15
231318
permissions:
232319
contents: read
@@ -286,6 +373,10 @@ jobs:
286373
env:
287374
IMAGE_NAME: ${{ env.IMAGE_NAME }}
288375
META_TAGS: ${{ steps.meta.outputs.tags }}
376+
SOURCE_SHA: ${{ needs.qualify.outputs.source_sha }}
377+
CI_RUN_ID: ${{ needs.qualify.outputs.ci_run_id }}
378+
CI_RUN_ATTEMPT: ${{ needs.qualify.outputs.ci_run_attempt }}
379+
CHART_VERSION: ${{ needs.qualify.outputs.chart_version }}
289380
run: |
290381
set -euo pipefail
291382
# Build -t flags from the metadata-action output.
@@ -300,7 +391,15 @@ jobs:
300391
digests+=("${IMAGE_NAME}@sha256:${digest}")
301392
done
302393
303-
docker buildx imagetools create "${tags[@]}" "${digests[@]}"
394+
annotations=(
395+
--annotation "index:org.opencontainers.image.revision=${SOURCE_SHA}"
396+
--annotation "index:xyz.block.buzz.build.id=github-actions:${GITHUB_RUN_ID}:${GITHUB_RUN_ATTEMPT}"
397+
--annotation "index:xyz.block.buzz.qualification.ci-run-id=${CI_RUN_ID}"
398+
--annotation "index:xyz.block.buzz.qualification.ci-run-attempt=${CI_RUN_ATTEMPT}"
399+
--annotation "index:xyz.block.buzz.qualification.ci-conclusion=success"
400+
--annotation "index:xyz.block.buzz.helm-chart.version=${CHART_VERSION}"
401+
)
402+
docker buildx imagetools create "${tags[@]}" "${annotations[@]}" "${digests[@]}"
304403
305404
# Capture the merged manifest digest for the attestation step.
306405
first_tag=$(echo "$META_TAGS" | head -n1)
@@ -317,17 +416,58 @@ jobs:
317416
subject-digest: ${{ steps.manifest.outputs.digest }}
318417
push-to-registry: true
319418

419+
- name: Create deployment eligibility predicate
420+
if: matrix.variant == 'release'
421+
env:
422+
SOURCE_SHA: ${{ needs.qualify.outputs.source_sha }}
423+
CI_RUN_ID: ${{ needs.qualify.outputs.ci_run_id }}
424+
CI_RUN_ATTEMPT: ${{ needs.qualify.outputs.ci_run_attempt }}
425+
CI_RUN_URL: ${{ needs.qualify.outputs.ci_run_url }}
426+
CHART_VERSION: ${{ needs.qualify.outputs.chart_version }}
427+
run: |
428+
jq -n \
429+
--arg source_repository "$GITHUB_REPOSITORY" \
430+
--arg source_ref "$GITHUB_REF" \
431+
--arg source_sha "$SOURCE_SHA" \
432+
--arg build_workflow ".github/workflows/docker.yml" \
433+
--argjson build_run_id "$GITHUB_RUN_ID" \
434+
--argjson build_run_attempt "$GITHUB_RUN_ATTEMPT" \
435+
--arg build_run_url "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}/attempts/${GITHUB_RUN_ATTEMPT}" \
436+
--arg qualification_workflow ".github/workflows/ci.yml" \
437+
--argjson qualification_run_id "$CI_RUN_ID" \
438+
--argjson qualification_run_attempt "$CI_RUN_ATTEMPT" \
439+
--arg qualification_run_url "$CI_RUN_URL" \
440+
--arg chart_version "$CHART_VERSION" \
441+
-f "$GITHUB_WORKSPACE/scripts/create-deployment-eligibility-predicate.jq" \
442+
>/tmp/deployment-eligibility.json
443+
444+
- name: Attest deployment eligibility
445+
if: matrix.variant == 'release'
446+
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
447+
with:
448+
subject-name: ${{ env.IMAGE_NAME }}
449+
subject-digest: ${{ steps.manifest.outputs.digest }}
450+
predicate-type: https://buzz.block.xyz/attestations/deployment-eligibility/v1
451+
predicate-path: /tmp/deployment-eligibility.json
452+
push-to-registry: true
453+
320454
- name: Summary
321455
env:
322456
IMAGE_NAME: ${{ env.IMAGE_NAME }}
323457
VARIANT: ${{ matrix.variant }}
324458
MERGED_DIGEST: ${{ steps.manifest.outputs.digest }}
325459
META_TAGS: ${{ steps.meta.outputs.tags }}
460+
SOURCE_SHA: ${{ needs.qualify.outputs.source_sha }}
461+
CI_RUN_URL: ${{ needs.qualify.outputs.ci_run_url }}
462+
CHART_VERSION: ${{ needs.qualify.outputs.chart_version }}
326463
run: |
327464
{
328465
echo "### Published \`${IMAGE_NAME}\` (${VARIANT})"
329466
echo
330467
echo "**Digest:** \`${MERGED_DIGEST}\`"
468+
echo "**Source:** \`${SOURCE_SHA}\`"
469+
echo "**Compatible Buzz chart:** \`${CHART_VERSION}\`"
470+
echo "**Qualifying CI:** ${CI_RUN_URL} (success)"
331471
echo
332472
echo "**Tags:**"
333473
echo '```'
@@ -338,6 +478,13 @@ jobs:
338478
echo '```'
339479
echo "gh attestation verify oci://${IMAGE_NAME}@${MERGED_DIGEST} --owner block"
340480
echo '```'
481+
if [[ "$VARIANT" == "release" ]]; then
482+
echo
483+
echo "Verify deployment eligibility:"
484+
echo '```'
485+
echo "gh attestation verify oci://${IMAGE_NAME}@${MERGED_DIGEST} --repo block/buzz --signer-workflow block/buzz/.github/workflows/docker.yml --predicate-type https://buzz.block.xyz/attestations/deployment-eligibility/v1 --source-digest ${SOURCE_SHA}"
486+
echo '```'
487+
fi
341488
} >> "$GITHUB_STEP_SUMMARY"
342489
343490
push-gateway-build:

‎Dockerfile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,14 @@ COPY --from=planner /build/recipe.json recipe.json
6767
# scoping to -p buzz-relay misses transitive deps and re-builds them later.
6868
RUN cargo chef cook --release --recipe-path recipe.json
6969
COPY . .
70+
# Compile immutable artifact identity into the relay. Defaults preserve local
71+
# and third-party builds that do not run in provenance-aware CI.
72+
ARG BUZZ_SOURCE_SHA=unknown
73+
ARG BUZZ_BUILD_ID=local
74+
ARG BUZZ_BUILD_URL=unknown
75+
ENV BUZZ_SOURCE_SHA=${BUZZ_SOURCE_SHA} \
76+
BUZZ_BUILD_ID=${BUZZ_BUILD_ID} \
77+
BUZZ_BUILD_URL=${BUZZ_BUILD_URL}
7078
RUN cargo build --release --locked -p buzz-relay --bin buzz-relay \
7179
-p buzz-admin --bin buzz-admin \
7280
-p buzz-pair-relay --bin buzz-pair-relay
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
//! Build-time identity compiled into the relay binary.
2+
3+
/// Full source commit SHA, or `unknown` outside a provenance-aware build.
4+
pub(crate) fn source_sha() -> &'static str {
5+
option_env!("BUZZ_SOURCE_SHA").unwrap_or("unknown")
6+
}
7+
8+
/// Stable build identifier, or `local` outside CI.
9+
pub(crate) fn build_id() -> &'static str {
10+
option_env!("BUZZ_BUILD_ID").unwrap_or("local")
11+
}
12+
13+
/// Build details URL, or `unknown` outside CI.
14+
pub(crate) fn build_url() -> &'static str {
15+
option_env!("BUZZ_BUILD_URL").unwrap_or("unknown")
16+
}

‎crates/buzz-relay/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
//! NIP-01 WebSocket relay for Buzz private team communication.
44
55
mod admission;
6+
mod build_info;
67

78
/// REST API route handlers.
89
pub mod api;

‎crates/buzz-relay/src/router.rs‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -413,14 +413,22 @@ async fn readiness_handler(State(state): State<Arc<AppState>>) -> impl IntoRespo
413413
}
414414
}
415415

416-
/// Status endpoint — service name, version, uptime.
417-
async fn status_handler(State(state): State<Arc<AppState>>) -> impl IntoResponse {
418-
let uptime_secs = state.started_at.elapsed().as_secs();
419-
Json(json!({
416+
fn status_payload(uptime_secs: u64) -> serde_json::Value {
417+
json!({
420418
"service": "buzz-relay",
421419
"version": env!("CARGO_PKG_VERSION"),
422420
"uptime_seconds": uptime_secs,
423-
}))
421+
"build": {
422+
"source_sha": crate::build_info::source_sha(),
423+
"id": crate::build_info::build_id(),
424+
"url": crate::build_info::build_url(),
425+
},
426+
})
427+
}
428+
429+
/// Status endpoint — service name, version, uptime, and intrinsic build identity.
430+
async fn status_handler(State(state): State<Arc<AppState>>) -> impl IntoResponse {
431+
Json(status_payload(state.started_at.elapsed().as_secs()))
424432
}
425433

426434
/// `/_mesh` — live mesh status: peer table, connection/phi state, per-peer
@@ -506,6 +514,23 @@ mod tests {
506514
assert!(!should_serve_spa("/arbitrary", true));
507515
}
508516

517+
#[test]
518+
fn status_payload_exposes_source_and_build_identity() {
519+
let payload = status_payload(42);
520+
521+
assert_eq!(payload["service"], "buzz-relay");
522+
assert_eq!(payload["version"], env!("CARGO_PKG_VERSION"));
523+
assert_eq!(payload["uptime_seconds"], 42);
524+
for field in ["source_sha", "id", "url"] {
525+
assert!(
526+
payload["build"][field]
527+
.as_str()
528+
.is_some_and(|value| !value.is_empty()),
529+
"build.{field} must be a non-empty string"
530+
);
531+
}
532+
}
533+
509534
#[tokio::test(flavor = "current_thread")]
510535
async fn http_and_datastore_spans_are_exported_in_the_same_trace() {
511536
let exporter = InMemorySpanExporter::default();

‎deploy/charts/buzz/Chart.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: |
77
PostgreSQL and Redis. Configurable for single-node evaluation
88
(subcharts on) and HA production (external services, existingSecret).
99
type: application
10-
version: 0.1.7
10+
version: 0.1.8
1111
appVersion: "0.1.0"
1212
home: https://github.com/block/buzz
1313
sources:
@@ -24,7 +24,7 @@ maintainers:
2424
annotations:
2525
artifacthub.io/changes: |
2626
- kind: added
27-
description: Generic init-container, volume, volume-mount, command, and args extension points for the relay Pod.
27+
description: Optional immutable relay image digest pinning with backwards-compatible tag fallback.
2828
artifacthub.io/license: Apache-2.0
2929

3030
# Optional eval-only subcharts. Production deploys disable both and point

‎deploy/charts/buzz/README.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This chart has two operating profiles selected by values:
1212
## Quickstart (eval only)
1313

1414
```sh
15-
helm install buzz oci://ghcr.io/block/buzz/charts/buzz --version 0.1.7 \
15+
helm install buzz oci://ghcr.io/block/buzz/charts/buzz --version 0.1.8 \
1616
--create-namespace --namespace buzz \
1717
--set quickstart=true \
1818
--set postgresql.enabled=true \
@@ -29,6 +29,15 @@ intent marker surfaced in NOTES.txt; the bundled services are opted in via the
2929
four `*.enabled` flags above (see `ci/quickstart-values.yaml` for the exact set
3030
CI installs). Eval-only: every bundled service is a single replica with no HA.
3131

32+
For immutable delivery, pin the OCI digest instead of a tag. `image.digest`
33+
overrides `image.tag` when both are present:
34+
35+
```yaml
36+
image:
37+
repository: ghcr.io/block/buzz
38+
digest: sha256:<64-lowercase-hex-characters>
39+
```
40+
3241
## Production (GitOps)
3342
3443
The chart is designed for ArgoCD and Flux. Both render charts with `helm template`, in which mode Helm's `lookup` function returns empty — any chart-side `randAlphaNum` call would regenerate secrets on every sync. The chart-managed Secret path is **only** safe for `helm install` / `helm upgrade`.

‎deploy/charts/buzz/templates/_helpers.tpl‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,13 @@ app.kubernetes.io/component: relay
5353
{{- end -}}
5454

5555
{{- define "buzz.image" -}}
56+
{{- if .Values.image.digest -}}
57+
{{- printf "%s@%s" .Values.image.repository .Values.image.digest -}}
58+
{{- else -}}
5659
{{- $tag := default .Chart.AppVersion .Values.image.tag -}}
5760
{{- printf "%s:%s" .Values.image.repository $tag -}}
5861
{{- end -}}
62+
{{- end -}}
5963

6064
{{/*
6165
Name of the chart-managed Secret holding relay-identity material and any

0 commit comments

Comments
 (0)