docs(release): align desktop handoff instructions (#3988)

## Summary
- document exact-head trusted approval as the only desktop tagging
authorization
- explicitly require `desktop_ref=desktop-v<version>` for the internal
desktop handoff
- replace the stale `squareup/sprout-releases` repository name with
`squareup/buzz-releases`

## Audit coverage
Compared `block/buzz` release documentation and automation with
`squareup/buzz-releases` `main`
(`5b09e5c5d71c80a0849a33458f4e45695df515d7`), including its README,
agent guide, Buildkite field hint, desktop validator, release validation
tests, and protected updater promotion instructions.

## Validation
- `bash scripts/test-release-ref-contract.sh`
- `git diff --check origin/main...HEAD`

Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
This commit is contained in:
Wes
2026-08-03 09:43:10 -07:00
committed by GitHub
co-authored by Carl
parent 09c86c56e5
commit 44fa1e8e3a
2 changed files with 16 additions and 13 deletions
+2 -2
View File
@@ -13,14 +13,14 @@ Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay,
| Repo | Purpose |
|------|---------|
| [block/buzz](https://github.com/block/buzz) | OSS source — relay, desktop app, mobile app, CLI, agent harness |
| [squareup/sprout-releases](https://github.com/squareup/sprout-releases) | Buildkite pipeline producing Block-signed macOS + iOS builds with `-block` version suffix |
| [squareup/buzz-releases](https://github.com/squareup/buzz-releases) | Buildkite pipelines producing Block-signed macOS + iOS builds with `-block` desktop version suffix |
| [squareup/sprout-oss](https://github.com/squareup/sprout-oss) | CI pipeline building the relay Docker image and pushing to internal ECR |
| [squareup/block-coder-tf-stacks](https://github.com/squareup/block-coder-tf-stacks) | Terraform + ArgoCD deploying the relay to the staging Kubernetes cluster |
| [squareup/sprout-backend-blox](https://github.com/squareup/sprout-backend-blox) | Desktop backend provider script connecting Blox workstation agents to the relay |
```
block/buzz (source)
├─► sprout-releases (desktop + mobile builds → Artifactory, GitHub, Mobile Releases)
├─► buzz-releases (desktop + mobile builds → Artifactory, GitHub, Mobile Releases)
├─► sprout-oss (relay Docker image → ECR)
│ └─► block-coder-tf-stacks (Helm chart → ArgoCD → staging cluster)
└─── sprout-backend-blox (Blox compute provider for Desktop agent launch)
+14 -11
View File
@@ -56,14 +56,15 @@ or mobile GitHub Release.
updates the PR.
2. Review the recorded base and candidate SHA, the complete changelog, and CI.
The required **Desktop Release Candidate** check validates the exact head.
Authorization is either an approval on that exact head or a permitted Default
ruleset bypass at merge time. Any regeneration changes the head and requires
the checks—and, for the review path, approvalto run again.
A trusted repository member, owner, or collaborator must approve that exact
candidate head. Any regeneration or push changes the head, invalidates the
prior approval, and requires both the checks and approval to run again.
3. **Squash merge** the PR. The protected branch must still be exactly the
recorded base; otherwise regenerate the candidate from current `main`.
4. `auto-tag-on-release-pr-merge` verifies the frozen parent, full-tree identity,
required checks, and one of the two authorization paths, then tags the squash
commit as `desktop-v<version>`.
required checks, and trusted approval on the exact candidate head, then tags
the squash commit as `desktop-v<version>`. An admin or ruleset bypass does not
authorize desktop tagging.
5. The tag triggers `release.yml`. It builds and stages Apple Silicon and Intel
macOS, Windows, and Linux artifacts; publishes the versioned release only
after the complete set succeeds; then updates the rolling updater manifest
@@ -184,10 +185,12 @@ Buildkite pipeline accepts only an exact candidate tag.
For mobile, trigger the private
[Release Mobile pipeline](https://buildkite.com/runway/buzz-mobile-releases) with
an exact RC tag for the platform build being cut. For desktop, use
[Release Desktop](https://buildkite.com/runway/sprout-releases). See the
an exact RC tag for the platform build being cut. For desktop, start
[Release Desktop](https://buildkite.com/runway/sprout-releases) and enter the
exact public source tag as `desktop_ref=desktop-v<version>`; a generic
`v<version>` tag is intentionally rejected. See the
[buzz-releases README](https://github.com/squareup/buzz-releases#cutting-a-release)
for the private pipeline contract.
for the rest of the private pipeline contract.
---
@@ -269,9 +272,9 @@ actor list.
Do not update the branch manually and do not weaken the ruleset. Run
`just release-desktop <version>` again from current `main`; this regenerates the
candidate, reruns CI, and requires a fresh approval when using the review path.
The post-merge verifier refuses to tag a squash whose parent differs from the
recorded candidate base or whose tree differs from the validated PR head.
candidate, reruns CI, and requires a fresh trusted approval on the new exact
head. The post-merge verifier refuses to tag a squash whose parent differs from
the recorded candidate base or whose tree differs from the validated PR head.
### Local `just release-desktop` fails with "must be on main branch"
Switch to `main` and pull latest before running the release recipe.