refactor(release): separate binary preparation and attachment (#11106)

Author: mergify[bot]

.github/workflows/README.md

@@ -31,6 +31,8 @@ graph TB
   %% Reusable build
   subgraph Build
     BuildDocker[zfnd-build-docker-image.yml]
+    PrepareBinaries[zfnd-release-binaries.yml]
+    AttachBinaries[zfnd-attach-release-binaries.yml]
   end
 
   %% Release automation
@@ -69,14 +71,16 @@ graph TB
   Manual --> IT & DeployNodes & Cleanup
 
   %% Build dependency
+  ReleaseBinaries --> BuildDocker & PrepareBinaries
+  PrepareBinaries --> AttachBinaries
   BuildDocker --> IT
   IT --> FindDisks --> Deploy
 
   %% Styling
   classDef primary fill:#2374ab,stroke:#2374ab,color:white
   classDef secondary fill:#48a9a6,stroke:#48a9a6,color:white
   classDef trigger fill:#95a5a6,stroke:#95a5a6,color:white
-  class BuildDocker primary
+  class BuildDocker,PrepareBinaries,AttachBinaries primary
   class ReleaseWorkflow,ReleaseBinaries primary
   class Unit,Lint,Coverage,DockerCfg,CrateBuild,PRGate,Docs,Security secondary
   class IT,FindDisks,Deploy,DeployNodes,Cleanup secondary
@@ -160,12 +164,14 @@ _The diagram above illustrates the parallel execution patterns in our CI/CD syst
 - **Docs (Book + internal)** (`book.yml`): Builds mdBook and internal rustdoc, publishes to Pages
 - **Security Analysis** (`zizmor.yml`): GitHub Actions security lint (SARIF)
 - **Release** (`release.yml`): Creates or updates Release PRs with release-plz, then uses `ZcashFoundation/cargo-release` and native Cargo to reconcile crates, tags, and one `zebrad` GitHub Release. See the [release process](../../book/src/dev/release-process.md#release-candidate--release-process) for operational instructions.
-- **Release Binaries** (`release-binaries.yml`): Build and publish release artifacts
+- **Release Binaries** (`release-binaries.yml`): Orchestrates release images, prepares and attaches downloadable binaries, and supports manual preparation validation without release attachment
 - **Integration Tests on GCP** (`zfnd-ci-integration-tests-gcp.yml`): Stateful tests, E2E tests, cached disks, lwd flows
 
 ### Supporting/Re-usable Workflows
 
 - **Build docker image** (`zfnd-build-docker-image.yml`): Reusable image build with caching and tagging
+- **Prepare release binaries** (`zfnd-release-binaries.yml`): Builds, attests, checksums, signs, and uploads the immutable binary bundle
+- **Attach release binaries** (`zfnd-attach-release-binaries.yml`): Attaches the prepared binary bundle to an existing GitHub Release
 - **Find cached disks** (`zfnd-find-cached-disks.yml`): Discovers GCP disks for stateful tests
 - **Deploy integration tests** (`zfnd-deploy-integration-tests-gcp.yml`): Orchestrates GCP VMs and test runs
 - **Deploy nodes** (`zfnd-deploy-nodes-gcp.yml`): Provision long-lived nodes

.github/workflows/release-binaries.yml

@@ -7,12 +7,14 @@
 # This workflow is triggered if:
 # - A release is published
 # - A pre-release is changed to a release
+# - A maintainer manually validates binary preparation before a release
 name: Release binaries
 
 on:
   release:
     types:
       - released
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -51,15 +53,52 @@ jobs:
       DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
       DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
 
-  # Build and attach downloadable zebrad binaries to the GitHub release.
-  binaries:
-    name: Attach release binaries
+  # Resolve the release tag into the version used in binary asset names.
+  binary-version:
+    name: Resolve release binary version
     if: github.repository_owner == 'ZcashFoundation' && startsWith(github.event.release.tag_name, 'v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Resolve release inputs
+        id: release
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          printf 'version=%s\n' "${RELEASE_TAG#v}" >> "${GITHUB_OUTPUT}"
+
+  prepare-binaries:
+    name: Prepare release binaries
+    needs: binary-version
     permissions:
-      contents: write
-      id-token: write
-      attestations: write
+      contents: read
+      id-token: write # authenticate binary provenance and signatures
+      attestations: write # store binary provenance
     uses: ./.github/workflows/zfnd-release-binaries.yml
+    with:
+      version: ${{ needs.binary-version.outputs.version }}
+      features: default-release-binaries
+
+  validate-binaries:
+    name: Validate release binary preparation
+    if: github.event_name == 'workflow_dispatch' && github.repository_owner == 'ZcashFoundation'
+    permissions:
+      contents: read
+      id-token: write # authenticate test provenance and signatures
+      attestations: write # store test provenance
+    uses: ./.github/workflows/zfnd-release-binaries.yml
+    with:
+      version: 0.0.0-test
+      features: default-release-binaries
+
+  attach-binaries:
+    name: Attach release binaries
+    needs: prepare-binaries
+    permissions:
+      contents: write # attach assets to the existing release
+    uses: ./.github/workflows/zfnd-attach-release-binaries.yml
     with:
       release_tag: ${{ github.event.release.tag_name }}
 
@@ -95,7 +134,9 @@ jobs:
       }}
     needs:
       - build
-      - binaries
+      - binary-version
+      - prepare-binaries
+      - attach-binaries
     timeout-minutes: 1
     steps:
       - name: Decide whether the needed jobs succeeded or failed
@@ -106,7 +147,7 @@ jobs:
   failure-issue:
     name: Open or update issues for release binaries failures
     # When a new job is added to this workflow, add it to this list.
-    needs: [ build, binaries ]
+    needs: [ build, binary-version, prepare-binaries, attach-binaries ]
     # Open tickets for any failed build in this workflow.
     if: failure() || cancelled()
     runs-on: ubuntu-latest

.github/workflows/zfnd-attach-release-binaries.yml

@@ -0,0 +1,46 @@
+# Attaches a prepared `release-binaries` workflow artifact to an existing
+# GitHub release. Binary construction and signing belong to
+# `zfnd-release-binaries.yml`.
+name: Attach release binaries (reusable)
+
+on:
+  workflow_call:
+    inputs:
+      release_tag:
+        description: "Existing GitHub release tag that receives the binaries"
+        required: true
+        type: string
+
+permissions: {}
+
+jobs:
+  attach:
+    name: Attach release binaries
+    if: >-
+      ${{
+        github.repository == 'ZcashFoundation/zebra' &&
+        github.event_name == 'release' &&
+        github.event.action == 'released' &&
+        startsWith(inputs.release_tag, 'v') &&
+        inputs.release_tag == github.event.release.tag_name
+      }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write # attach assets to the existing release
+    env:
+      RELEASE_TAG: ${{ inputs.release_tag }}
+      REPOSITORY: ${{ github.repository }}
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c #v8.0.1
+        with:
+          name: release-binaries
+          path: dist
+
+      - name: Upload binaries to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload "${RELEASE_TAG}" \
+            dist/*.tar.gz dist/*.sha256 dist/SHA256SUMS dist/SHA256SUMS.sigstore.json \
+            --repo "${REPOSITORY}" --clobber

.github/workflows/zfnd-release-binaries.yml

@@ -1,31 +1,22 @@
-# Builds the zebrad binary for Linux and packages it into signed, checksummed
-# `.tar.gz` archives. Reused by the release path and by the validation harness.
+# Builds zebrad for Linux and packages it into signed, checksummed `.tar.gz`
+# archives. The completed bundle is uploaded as the `release-binaries`
+# workflow artifact for a separate attachment job to consume.
 #
 # Binaries are built on Ubuntu 22.04 for a low glibc floor, with RocksDB and the
 # zcash FFI linked statically, so they run on most current distributions.
-#
-# With `release_tag`, the archives are uploaded to that GitHub release; without
-# it, they are uploaded as a CI artifact for inspection.
-name: Release binaries (reusable)
+name: Prepare release binaries (reusable)
 
 on:
   workflow_call:
     inputs:
-      release_tag:
-        description: "Release tag to upload assets to; empty uploads a CI artifact instead"
-        required: false
-        type: string
-        default: ""
       version:
-        description: "Version used in asset filenames; defaults to release_tag without its `v`"
-        required: false
+        description: "Version used in asset filenames"
+        required: true
         type: string
-        default: ""
       features:
         description: "Cargo features to build zebrad with"
-        required: false
+        required: true
         type: string
-        default: "default-release-binaries"
 
 permissions: {}
 
@@ -47,12 +38,11 @@ jobs:
     # ubuntu-22.04-arm), not the downstream publisher's runner.
     permissions:
       contents: read
-      id-token: write
-      attestations: write
+      id-token: write # authenticate build provenance
+      attestations: write # store build provenance
     env:
       TARGET: ${{ matrix.target }}
-      RELEASE_TAG: ${{ inputs.release_tag }}
-      VERSION_INPUT: ${{ inputs.version }}
+      VERSION: ${{ inputs.version }}
       FEATURES: ${{ inputs.features }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
@@ -74,9 +64,11 @@ jobs:
       - name: Build and package zebrad
         run: |
           set -euo pipefail
-          version="${VERSION_INPUT}"
-          if [ -z "${version}" ]; then version="${RELEASE_TAG#v}"; fi
-          if [ -z "${version}" ]; then echo "::error::no version or release_tag provided"; exit 1; fi
+
+          if [ -z "${VERSION}" ]; then
+            echo "::error::version must not be empty"
+            exit 1
+          fi
 
           SOURCE_DATE_EPOCH="$(git log -1 --pretty=%ct)"
           export SOURCE_DATE_EPOCH
@@ -103,7 +95,7 @@ jobs:
             exit 1
           fi
 
-          stage="zebrad-${version}-${TARGET}"
+          stage="zebrad-${VERSION}-${TARGET}"
           mkdir -p "dist/${stage}"
           cp target/release/zebrad "dist/${stage}/zebrad"
           cp LICENSE-APACHE LICENSE-MIT README.md "dist/${stage}/"
@@ -116,10 +108,7 @@ jobs:
 
       # Generated in the build job so the attestation reflects the matrix
       # runner (ubuntu-22.04 / ubuntu-22.04-arm), not the publish job's runner.
-      # Gated to release runs so the test harness cannot mint attestations
-      # under the same --signer-workflow path users are told to trust.
       - name: Attest build provenance
-        if: inputs.release_tag != ''
         uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
         with:
           subject-path: dist/*.tar.gz
@@ -130,17 +119,16 @@ jobs:
           path: dist/
           retention-days: 1
 
-  publish:
-    name: Sign and publish binaries
+  bundle:
+    name: Sign release binary bundle
     needs: build
     runs-on: ubuntu-latest
     timeout-minutes: 15
     permissions:
-      contents: write
-      id-token: write
-      attestations: read
+      contents: read
+      id-token: write # authenticate the checksum signature
+      attestations: read # verify archive provenance
     env:
-      RELEASE_TAG: ${{ inputs.release_tag }}
       REPOSITORY: ${{ github.repository }}
     steps:
       - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c #v8.0.1
@@ -157,16 +145,13 @@ jobs:
           ( cd dist && sha256sum -- *.tar.gz > SHA256SUMS )
 
       - name: Install Cosign
-        if: inputs.release_tag != ''
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
 
       - name: Sign the checksum manifest
-        if: inputs.release_tag != ''
         working-directory: dist
         run: cosign sign-blob --yes --bundle SHA256SUMS.sigstore.json SHA256SUMS
 
       - name: Verify signatures
-        if: inputs.release_tag != ''
         working-directory: dist
         env:
           GH_TOKEN: ${{ github.token }}
@@ -175,25 +160,16 @@ jobs:
           set -euo pipefail
           cosign verify-blob SHA256SUMS \
             --bundle SHA256SUMS.sigstore.json \
-            --certificate-identity-regexp="^https://github\\.com/${REPOSITORY}/\\.github/workflows/zfnd-release-binaries\\.yml@" \
+            --certificate-identity="https://github.com/${REPOSITORY}/.github/workflows/zfnd-release-binaries.yml@${GITHUB_REF}" \
             --certificate-oidc-issuer='https://token.actions.githubusercontent.com'
           for archive in *.tar.gz; do
             gh attestation verify "${archive}" \
               --repo "${REPOSITORY}" \
-              --signer-workflow "${REPOSITORY}/.github/workflows/zfnd-release-binaries.yml"
+              --signer-workflow "${REPOSITORY}/.github/workflows/zfnd-release-binaries.yml" \
+              --source-digest "${GITHUB_SHA}"
           done
 
-      - name: Upload binaries to the release
-        if: inputs.release_tag != ''
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh release upload "${RELEASE_TAG}" \
-            dist/*.tar.gz dist/*.sha256 dist/SHA256SUMS dist/SHA256SUMS.sigstore.json \
-            --repo "${REPOSITORY}" --clobber
-
-      - name: Upload binaries as a CI artifact
-        if: inputs.release_tag == ''
+      - name: Upload release binary bundle
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a #v7.0.1
         with:
           name: release-binaries

book/src/user/install.md

@@ -24,10 +24,11 @@ Or download an archive, verify it, and extract `zebrad`:
 ```bash
 gh attestation verify zebrad-<version>-x86_64-unknown-linux-gnu.tar.gz \
   --repo ZcashFoundation/zebra \
-  --signer-workflow ZcashFoundation/zebra/.github/workflows/zfnd-release-binaries.yml
+  --signer-workflow ZcashFoundation/zebra/.github/workflows/zfnd-release-binaries.yml \
+  --source-ref 'refs/tags/v<version>'
 cosign verify-blob SHA256SUMS \
   --bundle SHA256SUMS.sigstore.json \
-  --certificate-identity-regexp='^https://github\.com/ZcashFoundation/zebra/\.github/workflows/zfnd-release-binaries\.yml@' \
+  --certificate-identity='https://github.com/ZcashFoundation/zebra/.github/workflows/zfnd-release-binaries.yml@refs/tags/v<version>' \
   --certificate-oidc-issuer='https://token.actions.githubusercontent.com'
 sha256sum --ignore-missing -c SHA256SUMS
 tar xzf zebrad-<version>-x86_64-unknown-linux-gnu.tar.gz

docs/decisions/devops/0008-release-binary-artifacts.md

@@ -29,7 +29,7 @@ Per release, for `x86_64-unknown-linux-gnu` and `aarch64-unknown-linux-gnu`:
 - `zebrad-<version>-<target>.tar.gz` (the binary plus `LICENSE-APACHE`, `LICENSE-MIT`, `README.md`) and a `.tar.gz.sha256` sidecar.
 - One `SHA256SUMS` manifest covering both archives.
 - `SHA256SUMS.sigstore.json`: a Cosign keyless (Sigstore) signature over the manifest, with the Fulcio certificate identity pinned to the release workflow.
-- SLSA v1 build provenance per archive via `actions/attest-build-provenance`, stored in GitHub's attestation API and verified with `gh attestation verify --signer-workflow`.
+- SLSA v1 build provenance per archive via `actions/attest-build-provenance`, stored in GitHub's attestation API and verified against the expected signer workflow and release source ref.
 
 Six assets. Integrity and provenance for the whole release rest on one signed manifest plus one attestation per archive, not on per-file signatures. `cargo binstall zebrad` consumes these archives, giving a package-manager-style one-liner with no hosted repository to operate.
 
@@ -86,6 +86,7 @@ That augmentation has to be re-validated on every bump of those crates, and the
 gh attestation verify <archive> \
   --repo ZcashFoundation/zebra \
   --signer-workflow ZcashFoundation/zebra/.github/workflows/zfnd-release-binaries.yml \
+  --source-ref 'refs/tags/v<version>' \
   --predicate-type https://spdx.dev/Document/v2.3
 ```