Skip to content

Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.

Build once, promote: release.sh --stage builds X.Y.Z on staging; release.sh X.Y.Z only promotes

islandmed5b071ea3ec8c
diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml
index d06e4770..bcc47768 100644
--- a/.github/workflows/packages.yml
+++ b/.github/workflows/packages.yml
@@ -1,21 +1,24 @@
name: Packages
# The release packages (.deb, AppImage, .tar.gz, Flatpak, .rpm and VFX Reference Platform tarballs, .dmg, Windows
-# installer and .zip), each built and tested exactly as a release ships them. It runs on every push to main that
-# changes the app, so a tagged release can promote the packages of the commit it tags instead of building them again
-# (.github/workflows/release.yml); the release workflow also calls it to build from scratch when there are none.
+# installer and .zip), each built and tested exactly as a release ships them. It runs on every push to staging and main
+# that changes the app, so a tagged release promotes the staging run's packages of the commit it tags instead of
+# building them again (.github/workflows/release.yml); release.yml also calls it to build from the tag (--rebuild).
#
-# Integrity: the release promotes only artifacts of a successful run of THIS workflow for exactly the tagged commit,
-# either on a push to main or dispatched on `staging` by scripts/merge-queue.sh (checked in release.yml); main's push
-# then reuses the staging run (job reuse). Compiler caches are restored here but saved only by branch runs (pushes
-# to main, maintainers' own dispatches): never from a tag (a release that calls this builds from main's cache and
-# writes nothing) and never from a pull request (this workflow doesn't run on pull requests). See ci.yml for ccache.
+# Integrity: the release promotes only artifacts of a successful run of THIS workflow triggered by a maintainer's push
+# to `staging` (scripts/merge-queue.sh staging) for exactly the tagged commit (tools/release/staged_run.py, in
+# release.yml and scripts/release.sh); main's push then reuses the staging run (job reuse). Every package gets a GitHub
+# artifact attestation (job permissions id-token/attestations: write, nothing else) and job sums records their SHA-256;
+# release.yml checks both before publishing (tools/release/verify_staged.py). Artifacts are kept 14 days.
+# Compiler caches are restored here but saved only by branch runs (pushes to main or staging, maintainers' own
+# dispatches): never from a tag (a release that calls this builds from main's cache and writes nothing) and
+# never from a pull request (this workflow doesn't run on pull requests). See ci.yml for ccache.
# Runners: repository variables SF_RUNNER_* (Settings > Secrets and variables > Actions > Variables) name other
# runners for these build-and-test jobs; unset, they are GitHub's standard ones. No job here gets a secret.
on:
push:
- branches: [main]
+ branches: [main, staging] # staging: the merge queue's batch, the release's packages (built once, promoted unchanged)
paths: # everything but the website (its phone page, website/link, is built into the app) and release paperwork
- '**'
- '!website/**'
@@ -59,7 +62,7 @@ env:
jobs:
reuse:
- # A batch that went through `staging` (scripts/merge-queue.sh staging) had this workflow dispatched there for the
+ # A batch that went through `staging` (scripts/merge-queue.sh staging) ran this workflow there on the push, for the
# same commit; main's push then reuses that run instead of building it all again, and the release promotes the
# staging run's packages (release.yml, job locate). In progress: wait for it. Failed, cancelled or none: build.
name: Reuse the staging run
@@ -78,7 +81,7 @@ jobs:
REPO: ${{ github.repository }}
SHA: ${{ github.sha }}
run: |
- id=$(gh api "repos/$REPO/actions/workflows/packages.yml/runs?head_sha=$SHA&event=workflow_dispatch&branch=staging&per_page=5" \
+ id=$(gh api "repos/$REPO/actions/workflows/packages.yml/runs?head_sha=$SHA&event=push&branch=staging&per_page=5" \
--jq '[.workflow_runs[] | select(.head_sha == "'"$SHA"'" and .head_branch == "staging"
and .path == ".github/workflows/packages.yml" and .head_repository.full_name == "'"$REPO"'")][0].id // empty')
[ -n "$id" ] || { echo "No Packages run on staging for $SHA: building here"; exit 0; }
@@ -95,6 +98,10 @@ jobs:
name: Linux ${{ matrix.arch }} (.deb, AppImage, .tar.gz)
needs: reuse
if: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}
+ permissions: # the attestation: a signed statement of what this run built
+ contents: read
+ id-token: write
+ attestations: write
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
@@ -156,12 +163,24 @@ jobs:
build/*.tar.gz
build/*.AppImage
build/*.AppImage.zsync
+ retention-days: 14
+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+ with:
+ subject-path: |
+ build/*.deb
+ build/*.tar.gz
+ build/*.AppImage
+ build/*.AppImage.zsync
# Built in the freedesktop SDK (packaging/flatpak/build.sh), installed, and UI tests run inside the sandbox.
flatpak:
name: Flatpak ${{ matrix.arch }}
needs: reuse
if: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}
+ permissions: # the attestation: a signed statement of what this run built
+ contents: read
+ id-token: write
+ attestations: write
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
@@ -205,11 +224,19 @@ jobs:
with:
name: flatpak-${{ matrix.arch }}
path: dist/*.flatpak
+ retention-days: 14
+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+ with:
+ subject-path: dist/*.flatpak
vfx:
name: ${{ matrix.label }} ${{ matrix.arch }}
needs: reuse
if: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}
+ permissions: # the attestation: a signed statement of what this run built
+ contents: read
+ id-token: write
+ attestations: write
runs-on: ${{ matrix.os }}
container: ${{ matrix.image }}
strategy:
@@ -291,11 +318,21 @@ jobs:
path: |
build/*.rpm
build/*.tar.gz
+ retention-days: 14
+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+ with:
+ subject-path: |
+ build/*.rpm
+ build/*.tar.gz
macos:
name: macOS (universal .dmg)
needs: reuse
if: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}
+ permissions: # the attestation: a signed statement of what this run built
+ contents: read
+ id-token: write
+ attestations: write
runs-on: ${{ vars.SF_RUNNER_MAC || 'macos-15' }}
steps:
- uses: actions/checkout@v7
@@ -347,11 +384,19 @@ jobs:
with:
name: macos
path: build/*.dmg
+ retention-days: 14
+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+ with:
+ subject-path: build/*.dmg
windows:
name: Windows x64 (installer, .zip)
needs: reuse
if: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}
+ permissions: # the attestation: a signed statement of what this run built
+ contents: read
+ id-token: write
+ attestations: write
runs-on: ${{ vars.SF_RUNNER_WIN || 'windows-2022' }}
steps:
- uses: actions/checkout@v7
@@ -408,3 +453,28 @@ jobs:
path: |
build/*.exe
build/*.zip
+ retention-days: 14
+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+ with:
+ subject-path: |
+ build/*.exe
+ build/*.zip
+
+ # The SHA-256 of every package this run built, as an artifact of its own: release.yml publishes these files only if
+ # each one still has exactly this checksum and its attestation (tools/release/verify_staged.py).
+ sums:
+ name: Record checksums
+ needs: [linux, flatpak, vfx, macos, windows]
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/download-artifact@v8
+ with:
+ path: dist
+ merge-multiple: true
+ pattern: '{linux,flatpak,vfx,macos,windows}*'
+ - run: cd dist && sha256sum * > ../SHA256SUMS.staged.txt && cat ../SHA256SUMS.staged.txt
+ - uses: actions/upload-artifact@v7
+ with:
+ name: staged-sums
+ path: SHA256SUMS.staged.txt
+ retention-days: 14
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e740f6b8..c8c39835 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -3,14 +3,20 @@ name: Release
# A v* tag publishes a GitHub release (docs/releasing.md has the whole process; scripts/release.sh drives it).
#
# locate the tagged commit must carry the version the tag names (CMakeLists.txt's version, plus its
-# SCULPTFORGE_PRERELEASE for a beta: v0.11.0-beta.1 tags 0.11.0 with "beta.1"). If CI succeeded on a push to
-# main for exactly this commit and the Packages workflow (packages.yml) succeeded for it, on `staging` (the
-# release batch carried the bump) or on that push, the release uses those packages: built and tested once,
-# promoted unchanged. Otherwise:
-# build the Packages workflow runs here, from the tag (compiler cache restored from main, never saved).
+# SCULPTFORGE_PRERELEASE for a beta: v0.11.0-beta.1 tags 0.11.0 with "beta.1"). When the Packages workflow
+# (packages.yml) ran on a maintainer's push to `staging` for exactly this commit (scripts/release.sh --stage),
+# the release promotes that run's packages unchanged: built and tested once. tools/release/staged_run.py
+# picks it (push event, branch, actor, success, at most 7 days old, artifacts present) and refuses the
+# release if no such run qualifies; CI must have passed on main for the commit. With no staging run at all:
+# build the Packages workflow runs here, from the tag (compiler cache restored from main, never saved): the
+# --rebuild path.
+# verify every package's SHA-256 is the one its run recorded (packages.yml job sums) and its GitHub artifact
+# attestation names packages.yml, this commit and that run (and, promoted, a push to staging):
+# tools/release/verify_staged.py. Any mismatch refuses the release.
# smoke every package installed or unpacked on a fresh runner: the app opens a model and sculpts
# (tests/ui/release_smoke.sfui), sculptforge-cli opens, sculpts, saves and reopens (tests/release_smoke.py).
-# publish only after every smoke test passed: checksums, notes from CHANGELOG.md, the GitHub release. A tag with
+# publish only after verify and every smoke test passed (environment `release`, the only holder of
+# UPDATE_SIGNING_KEY besides member-release: tags v* only): checksums re-checked, signed, notes from CHANGELOG.md, the GitHub release. A tag with
# a '-' (a beta) is a member perk, published by publish-members instead: a pre-release in the private
# repository islandmed/sculptforge-insiders (INSIDERS_REPO_TOKEN, held only by the environment
# member-release: v* tags only, maintainer approval) with CHANGELOG's [Unreleased] notes, and posted in
@@ -20,8 +26,9 @@ name: Release
# to a full commit SHA (scripts/release.sh check enforces it). Build and smoke jobs take their
# runner from the SF_RUNNER_* repository variables (standard GitHub runners when unset); locate and publish always run
# on GitHub's own runners.
-# workflow_dispatch rebuilds and republishes an existing tag; dry_run does everything but publish, and promote_run
-# (dry runs only) smoke-tests the packages of any Packages run, so the pipeline can be tried from a branch.
+# workflow_dispatch republishes an existing tag (dispatch it ON the tag, `--ref vX.Y.Z`: the environment takes only
+# tags); dry_run does everything but publish, and promote_run (dry runs only) smoke-tests the packages of any Packages
+# run, unverified, so the pipeline can be tried from a branch.
on:
push:
@@ -56,6 +63,7 @@ jobs:
run-id: ${{ steps.find.outputs.run-id }}
sha: ${{ steps.find.outputs.sha }}
tag: ${{ steps.find.outputs.tag }}
+ staged: ${{ steps.find.outputs.staged }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { ref: '${{ env.TAG }}', fetch-depth: 20 } # the commits before the bump, for the paperwork check
@@ -90,20 +98,25 @@ jobs:
echo "run-id=$run" >> "$GITHUB_OUTPUT"
exit 0
fi
- # Successful runs on a push to main for exactly this commit, from this repository's own workflow files.
+ # CI: a successful run on a push to main for exactly this commit, from this repository's own workflow file.
runs() {
gh api "repos/$REPO/actions/workflows/$1/runs?head_sha=$sha&event=push&branch=main&status=success&per_page=5" \
--jq '.workflow_runs[] | select(.head_sha == "'"$sha"'" and .head_branch == "main" and .event == "push"
and .path == ".github/workflows/'"$1"'" and .head_repository.full_name == "'"$REPO"'") | .id' | head -1
}
+ # The packages: only the Packages run of a maintainer's push to `staging` for exactly this commit (exit 3:
+ # there is none, build here; exit 1: there are runs, none may be promoted: refuse).
+ rc=0
+ pkg=$(python3 tools/release/staged_run.py --repo "$REPO" --sha "$sha") || rc=$?
+ if [ $rc = 3 ]; then
+ echo "No Packages run on staging for $sha: building the packages here (the --rebuild path)"
+ exit 0
+ elif [ $rc != 0 ]; then
+ echo "::error::$sha has Packages runs on staging but none may be promoted (above). Fix: stage the release again (scripts/release.sh X.Y.Z --stage), or delete the tag and use scripts/release.sh X.Y.Z --rebuild."
+ exit 1
+ fi
ci=$(runs ci.yml || true)
- # The packages: the run on `staging` for exactly this commit (the release batch carried the bump: scripts/
- # merge-queue.sh staging dispatches packages.yml there, and main's push run then reuses it), else main's own.
- pkg=$(gh api "repos/$REPO/actions/workflows/packages.yml/runs?head_sha=$sha&event=workflow_dispatch&branch=staging&status=success&per_page=5" \
- --jq '.workflow_runs[] | select(.head_sha == "'"$sha"'" and .head_branch == "staging" and .event == "workflow_dispatch"
- and .path == ".github/workflows/packages.yml" and .head_repository.full_name == "'"$REPO"'") | .id' | head -1 || true)
- [ -n "$pkg" ] || pkg=$(runs packages.yml || true)
- if [ -z "$ci" ] && [ -n "$pkg" ]; then
+ if [ -z "$ci" ]; then
# The bump commit adds only release paperwork (tools/release/paperwork_only.py: version lines, CHANGELOG,
# docs, site, fragments) to a main commit whose CI passed: that result stands (scripts/release.sh step ci).
for c in $(git rev-list --first-parent -n 8 "$sha~1"); do
@@ -112,12 +125,10 @@ jobs:
[ -n "$ci" ] && { echo "CI run $ci on $c stands for $sha (only release paperwork since)"; break; }
done
fi
- if [ -n "$ci" ] && [ -n "$pkg" ]; then
- echo "Promoting the packages of Packages run $pkg (CI run $ci passed for $sha)"
- echo "run-id=$pkg" >> "$GITHUB_OUTPUT"
- else
- echo "No successful CI ($ci) and Packages ($pkg) runs on main for $sha: building the packages here"
- fi
+ [ -n "$ci" ] || { echo "::error::no successful CI run on main for $sha: a staged commit lands on main only after CI passed"; exit 1; }
+ echo "Promoting the packages of staging's Packages run $pkg (CI run $ci passed for $sha)"
+ echo "run-id=$pkg" >> "$GITHUB_OUTPUT"
+ echo "staged=true" >> "$GITHUB_OUTPUT"
build:
name: Build
@@ -126,11 +137,47 @@ jobs:
permissions:
contents: read
actions: read # packages.yml's reuse job asks for it (it skips itself here: not a push to main)
+ id-token: write # packages.yml attests what it builds
+ attestations: write
uses: ./.github/workflows/packages.yml
with:
ref: ${{ needs.locate.outputs.sha }}
tag: ${{ needs.locate.outputs.tag }}
+ # Every package against its run's recorded SHA-256 and its attestation (tools/release/verify_staged.py). Dry runs
+ # too; not for promote_run (a dry run's look at any run's packages).
+ verify:
+ name: Verify checksums and attestations
+ needs: [locate, build]
+ if: ${{ !cancelled() && needs.locate.result == 'success' && (needs.build.result == 'success' || needs.build.result == 'skipped') && !(inputs.dry_run == true && inputs.promote_run != '') }}
+ runs-on: ubuntu-24.04
+ permissions:
+ contents: read
+ actions: read
+ attestations: read
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with: { ref: '${{ needs.locate.outputs.sha }}', persist-credentials: false, sparse-checkout: tools/release }
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+ with:
+ path: dist
+ merge-multiple: true
+ pattern: '{linux,flatpak,vfx,macos,windows}*'
+ run-id: ${{ needs.locate.outputs.run-id || github.run_id }}
+ github-token: ${{ github.token }}
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+ with:
+ name: staged-sums
+ path: sums
+ run-id: ${{ needs.locate.outputs.run-id || github.run_id }}
+ github-token: ${{ github.token }}
+ - env:
+ GH_TOKEN: ${{ github.token }}
+ RUN: ${{ needs.locate.outputs.run-id || github.run_id }}
+ SHA: ${{ needs.locate.outputs.sha }}
+ STAGED: ${{ needs.locate.outputs.staged }}
+ run: python3 tools/release/verify_staged.py dist sums/SHA256SUMS.staged.txt --repo "$GITHUB_REPOSITORY" --run "$RUN" --sha "$SHA" ${STAGED:+--staged}
+
smoke:
name: Smoke test ${{ matrix.name }}
needs: [locate, build]
@@ -233,9 +280,10 @@ jobs:
publish:
name: Publish GitHub Release
- needs: [locate, build, smoke]
- if: ${{ !cancelled() && needs.smoke.result == 'success' && inputs.dry_run != true && !contains(needs.locate.outputs.tag, '-') }}
+ needs: [locate, build, verify, smoke]
+ if: ${{ !cancelled() && needs.verify.result == 'success' && needs.smoke.result == 'success' && inputs.dry_run != true && !contains(needs.locate.outputs.tag, '-') }}
runs-on: ubuntu-24.04
+ environment: release # UPDATE_SIGNING_KEY lives only here (and in member-release): deployments from tags v* only
permissions:
contents: write
actions: read
@@ -249,6 +297,17 @@ jobs:
pattern: '{linux,flatpak,vfx,macos,windows}*'
run-id: ${{ needs.locate.outputs.run-id || github.run_id }}
github-token: ${{ github.token }}
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+ with:
+ name: staged-sums
+ path: sums
+ run-id: ${{ needs.locate.outputs.run-id || github.run_id }}
+ github-token: ${{ github.token }}
+ - name: The same bytes job verify checked (SHA-256 as recorded, nothing added or missing)
+ env:
+ RUN: ${{ needs.locate.outputs.run-id || github.run_id }}
+ SHA: ${{ needs.locate.outputs.sha }}
+ run: python3 tools/release/verify_staged.py dist sums/SHA256SUMS.staged.txt --run "$RUN" --sha "$SHA" --sums-only && rm -r sums
- name: Version-less copies (fixed links such as releases/latest/download/SculptForge-macos.dmg)
run: |
cd dist
@@ -295,8 +354,8 @@ jobs:
# a workflow_dispatch from a branch); scripts/release.sh check enforces the environment and pinned actions.
publish-members:
name: Publish members' beta
- needs: [locate, build, smoke]
- if: ${{ !cancelled() && needs.smoke.result == 'success' && inputs.dry_run != true && contains(needs.locate.outputs.tag, '-') }}
+ needs: [locate, build, verify, smoke]
+ if: ${{ !cancelled() && needs.verify.result == 'success' && needs.smoke.result == 'success' && inputs.dry_run != true && contains(needs.locate.outputs.tag, '-') }}
runs-on: ubuntu-24.04
environment: member-release
permissions:
@@ -312,6 +371,17 @@ jobs:
pattern: '{linux,flatpak,vfx,macos,windows}*'
run-id: ${{ needs.locate.outputs.run-id || github.run_id }}
github-token: ${{ github.token }}
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+ with:
+ name: staged-sums
+ path: sums
+ run-id: ${{ needs.locate.outputs.run-id || github.run_id }}
+ github-token: ${{ github.token }}
+ - name: The same bytes job verify checked (SHA-256 as recorded, nothing added or missing)
+ env:
+ RUN: ${{ needs.locate.outputs.run-id || github.run_id }}
+ SHA: ${{ needs.locate.outputs.sha }}
+ run: python3 tools/release/verify_staged.py dist sums/SHA256SUMS.staged.txt --run "$RUN" --sha "$SHA" --sums-only && rm -r sums
- name: Blender add-on and Maya shelf script
run: |
V=${TAG#v}
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0608ce66..a44e3d9b 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -762,11 +762,16 @@ if(SCULPTFORGE_BUILD_TESTS)
add_test(NAME release_workflows COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/check_workflows.py)
add_test(NAME release_workflows_self_test COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/check_workflows.py --self-test)
add_test(NAME release_paperwork COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/paperwork_only.py --self-test)
+ # Build once, promote: only a maintainer's push run on staging is promotable (staged_run.py), and every package must
+ # match its recorded SHA-256 and attestation before publishing (verify_staged.py).
+ add_test(NAME release_staged_run COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/staged_run.py --self-test)
+ add_test(NAME release_verify_staged COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/verify_staged.py --self-test)
# Step bump pins tests/ui/whats_new.sfui to the newest What's New sections (tools/release/pin_whats_new_test.py).
add_test(NAME release_pin_whats_new COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/pin_whats_new_test.py --self-test)
# scripts/merge-queue.sh refuses a merge or squash that throws away the other side's change (tools/ci/no_revert.py).
add_test(NAME ci_no_revert COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/ci/no_revert.py --self-test)
- # scripts/release.sh's beta (X.Y.Z-beta.N) and its promotion to stable, in a sandbox with stand-ins for gh and curl.
+ # scripts/release.sh's beta (X.Y.Z-beta.N), its promotion to stable, and build once (--stage, then promote), in a
+ # sandbox with stand-ins for gh and curl.
if(UNIX AND NOT APPLE AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/.git)
add_test(NAME release_script_beta COMMAND bash ${CMAKE_CURRENT_SOURCE_DIR}/tests/release_beta_test.sh)
set_tests_properties(release_script_beta PROPERTIES TIMEOUT 300)
diff --git a/docs/releasing.md b/docs/releasing.md
index abfa0011..5ac3e1e3 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -1,9 +1,12 @@
# Releasing SculptForge
-One page for whoever coordinates a release. One command does the work:
+One page for whoever coordinates a release. Two commands do the work: the packages are built and tested once, on
+`staging`, already carrying X.Y.Z, and the release publishes exactly those files.
```sh
-HIGHLIGHTS=highlights.txt scripts/release.sh X.Y.Z --yes
+scripts/release.sh X.Y.Z --stage # in the merger's batch checkout: bump + staging + main
+HIGHLIGHTS=highlights.txt scripts/release.sh X.Y.Z --yes # on main: promote (tag the staged commit, publish)
+HIGHLIGHTS=highlights.txt scripts/release.sh X.Y.Z --rebuild --yes # fallback, the old way: build from the tag
```
It either stops within seconds, before anything is tagged, with the fix, or runs through to the end. This page explains
@@ -14,11 +17,12 @@ the gates, what each step does, and how to recover.
1. **Merged tree, tested once on each machine** (docs/testing-flow.md): the merger's batch goes to the branch
`staging` (`scripts/merge-queue.sh staging --with ~/Work/.sf/t1.sh HEAD`). The whole suite runs on the PC (T1) while
the full CI runs on staging (T2), and main fast-forwards to the batch only when both are green. Nobody runs a
- second local full ctest. Packages (packages.yml) is built on staging too, beside CI. **The release batch carries
- the bump**: `RELEASE=X.Y.Z [HIGHLIGHTS=f] ~/Work/.sf/merge-batch.sh <branches>` runs
- `scripts/release.sh X.Y.Z --only bump --staged` on top of the merged batch (it commits, pushes nothing), so staging
- builds and tests the packages of the exact commit that will be tagged. The release command afterwards finds the
- versions already set, reuses CI and promotes those packages: tag to published is the smoke tests, about 5 minutes.
+ second local full ctest. Packages (packages.yml) runs on the push to staging, beside CI. **The release batch
+ carries the bump**: `scripts/release.sh X.Y.Z --stage` in the batch checkout commits the bump on top of it and runs
+ `scripts/merge-queue.sh staging` (with `STAGE_WITH`, default `~/Work/.sf/t1.sh .`), so staging builds and tests the
+ packages of the exact commit that will be tagged (`RELEASE=X.Y.Z ~/Work/.sf/merge-batch.sh <branches>` does the
+ same through `--only bump --staged`). The release command afterwards finds the versions already set, reuses CI and
+ promotes those packages: tag to published is verification and the smoke tests, about 5 minutes.
2. **Version and words**:
- written by people, on main before the release: one note fragment per branch, `changes/<branch>.md`
(changes/README.md: the What's New bullet, CHANGELOG entry and section, highlight, #testers bullets); in
@@ -53,25 +57,49 @@ the gates, what each step does, and how to recover.
## Build once, promote
-A push to main runs CI and Packages; a batch that went through `staging` already ran both there, and main's runs
-reuse them. When the tag points at a commit whose CI passed on main and whose Packages passed on staging or on main,
-the Release workflow takes **that run's packages unchanged** (it checks the commit, the workflow file, the branch and
-the event). It
-smoke-tests them, then publishes. Nothing is compiled again, so a release takes a few minutes. Otherwise (for
-example, the tag is on a commit Packages skipped), Release builds the packages itself from the tag.
+`--stage` lands the bump through staging; the push to `staging` runs Packages for that commit, and main's push reuses
+the run. `scripts/release.sh X.Y.Z` then only promotes: step `bump` checks main already carries X.Y.Z, step `ci`
+waits for staging's Packages run and checks it, step `tag` tags **exactly that commit** (main must be it). The Release
+workflow takes that run's packages unchanged, verifies them, smoke-tests them, signs and publishes.
-Two rules make this safe:
-- **Compiler caches:** release builds restore main's caches, and nothing run from a tag or a pull request ever saves
- one.
-- **Tokens:** only the `publish` job holds a token that can write.
+What makes a run promotable (tools/release/staged_run.py, used by release.sh steps ci and tag and by release.yml
+`locate`; refused otherwise, nothing is rebuilt silently):
+- packages.yml of this repository, triggered by a **push** to `staging` for exactly the tagged commit: never a
+ pull_request, a workflow_dispatch or a fork's run;
+- pushed and (re)run by islandmed (`actor` and `triggering_actor`);
+- concluded `success`, at most 7 days old (`SF_STAGED_MAX_DAYS`; artifacts are kept 14), every package artifact and
+ `staged-sums` still there;
+- CI passed on main for the commit (or for its parent, when the bump only added paperwork).
-The packages are not signed yet. When signing comes (SignPath for Windows, Apple notarization), it belongs in a step
-between smoke and publish that signs the promoted files, so promotion stays valid.
+Before anything is published (release.yml `verify`, tools/release/verify_staged.py): the downloaded files are exactly
+those packages.yml's job `sums` recorded, each with the recorded SHA-256, and each has a GitHub artifact attestation
+(actions/attest-build-provenance in every build job) that `gh attestation verify` accepts for packages.yml, this
+commit, that run and, promoted, `refs/heads/staging` and a push. `publish` re-checks the checksums of the files it
+uploads. Any mismatch stops the release.
+
+Signing happens only at promotion: `UPDATE_SIGNING_KEY` is a secret of the environments `release` (job `publish`,
+deployments from tags `v*` only) and `member-release` (betas), never of the repository, so no staging or branch run can
+read it. Step `check` refuses otherwise. packages.yml reads no secret at all (tools/release/check_workflows.py).
+
+Unreleased builds: nothing is released, drafted or put in the feed before the tag. Staging's packages exist only as
+that run's Actions artifacts (14 days). In this public repository signed-in GitHub users can download Actions
+artifacts, as they always could for main's Packages runs; the attestations (public, in Sigstore's log) carry only
+checksums and the commit.
+
+**--rebuild** (fallback): bump pushed to main, no staging run for that commit, so release.yml builds the packages from
+the tag (about 40 minutes), attests and verifies them the same way, then smoke-tests and publishes.
+
+Compiler caches: release builds restore main's caches, and nothing run from a tag or a pull request ever saves one.
+Tokens: only `publish` holds a token that can write.
+
+The packages are not code-signed yet. When signing comes (SignPath for Windows, Apple notarization), it belongs in a
+step between smoke and publish that signs the promoted files, so promotion stays valid.
## The script
```sh
-HIGHLIGHTS=highlights.txt scripts/release.sh 0.10.4 --yes # all steps
+scripts/release.sh 0.10.4 --stage # bump + staging (in the batch checkout)
+HIGHLIGHTS=highlights.txt scripts/release.sh 0.10.4 --yes # all steps (promote)
HIGHLIGHTS=highlights.txt scripts/release.sh 0.10.4 --from site # resume
scripts/release.sh 0.10.4 --only replies
```
@@ -81,10 +109,11 @@ The home page's What's New area (between the `whats-new` markers in website/inde
| step | does | skips when |
|---|---|---|
-| bump | refuses without What's New, its UI test, CHANGELOG entries, the version's features block and HIGHLIGHTS; then sets the version files, CHANGELOG section and the features block's date, rebuilds the guide and the home page's What's New area, commits as islandmed, pushes main | each file already at X.Y.Z |
+| bump | refuses without What's New, its UI test, CHANGELOG entries, the version's features block and HIGHLIGHTS; then sets the version files, CHANGELOG section and the features block's date, rebuilds the guide and the home page's What's New area, commits as islandmed (--stage: in the batch; --rebuild: pushes main; promoting: only checks main has it) | each file already at X.Y.Z |
+| stage | (--stage only) scripts/merge-queue.sh staging on the bumped batch: CI there, STAGE_WITH here, main fast-forwards | never |
| check | gate 2 and every precondition of the later steps, on a clean, up-to-date main, with gh logged in as islandmed | never (read-only) |
-| ci | waits for CI and Packages on main's commit; stops if either failed | the tag exists |
-| tag | asks, then tags main and pushes the tag (this publishes) | the tag is on GitHub |
+| ci | waits for CI on main's commit and for staging's Packages run, and checks it is promotable (--rebuild: CI only) | the tag exists |
+| tag | checks main is the staged commit with a promotable run, asks, then tags it and pushes the tag (this publishes) | the tag is on GitHub |
| release | waits for the Release run, then checks the assets and SHA256SUMS.txt | the release has SHA256SUMS.txt |
| site | update feed (version + your highlights), home page version text, pushes; then waits for the live feed (10 min) and guide (5 min) | latest.json says X.Y.Z |
| aur | packaging/arch/PKGBUILD: pkgver and the source checksum, computed by downloading the tag's tarball | already at X.Y.Z with that checksum |
@@ -222,7 +251,9 @@ don't pile them up for later.
| check: a version file missing | run step bump (`--only bump`), then resume from check |
| ci: a CI or Packages job failed | runner hiccup (network, a timeout): `gh run rerun <id> --failed`. Real failure: fix on a branch, merge, start from check |
| release: a smoke test failed | the package is broken: fix on main, delete the tag (`git push origin :vX.Y.Z; git tag -d vX.Y.Z`), release again |
-| release: publish failed after smoke passed | `gh workflow run release.yml -f tag=vX.Y.Z` (it promotes the same packages) |
+| ci/tag: no promotable staging run | stage again (`--stage` in the batch), or a runner hiccup: rerun it; or `--rebuild` |
+| release: verify refused | something differs from what staging built: investigate before anything else; never skip it |
+| release: publish failed after smoke passed | `gh workflow run release.yml --ref vX.Y.Z -f tag=vX.Y.Z` (on the tag: the `release` environment takes only tags; it promotes the same packages) |
| site: live site still old | check the Website workflow (`gh run list -w pages.yml`) and re-run it |
| omarchy: the PR merged or closed | open a bump PR there and update `OMARCHY_PR` in the script |
@@ -232,8 +263,9 @@ don't pile them up for later.
gh workflow run release.yml -f tag=vX.Y.Z -f dry_run=true
```
-Add `-f promote_run=<Packages run id>` to smoke-test the packages of any Packages run, e.g. one dispatched from a
-branch. A dry run never publishes.
+A dry run from a branch builds the packages (the --rebuild path) and runs `verify` on them. Add
+`-f promote_run=<Packages run id>` to smoke-test the packages of any Packages run instead (unverified). A dry run never
+publishes.
## Runners
diff --git a/scripts/merge-queue.sh b/scripts/merge-queue.sh
index f0b684e4..4070d816 100755
--- a/scripts/merge-queue.sh
+++ b/scripts/merge-queue.sh
@@ -18,9 +18,10 @@
# while CMD runs here (e.g. '~/Work/.sf/pc.sh .', T1), and when both pass main
# fast-forwards to exactly that commit. CI's run on main then reuses the
# staging result (ci.yml, job Changes) instead of building it all again.
-# The release packages (packages.yml) are built on staging too, beside CI;
-# main's Packages run reuses them, and a release batch that carries the
-# bump (release.sh --staged) gets the packages it will publish.
+# The release packages (packages.yml) are built on the push to staging,
+# beside CI; main's Packages run reuses them, and a release batch that
+# carries the bump (scripts/release.sh X.Y.Z --stage) gets the packages
+# the release promotes (only a push's run counts: tools/release/staged_run.py).
#
# run, batch mode (the default): main plus every queued PR merged in queue order on a branch queue/batch-<time>
# (a PR that conflicts, or whose own checks are red, is dropped with a comment and the "queue-failed" label), the
@@ -171,9 +172,9 @@ land_staging() { # land_staging [--with CMD] [REF]
say "staging ${sha:0:8} ($(git log -1 --format=%s "$sha" | cut -c1-60)) on main $(git rev-parse --short origin/main)"
git push -q --force origin "$sha:refs/heads/staging"
git fetch -q origin staging
- # Not waited for: a red Packages run doesn't hold main (main's push then builds its own, as before staging).
- gh workflow run packages.yml -R "$REPO" --ref staging >/dev/null && echo " Packages dispatched on staging" ||
- echo " note: couldn't dispatch Packages on staging: main's push builds them"
+ # The push itself starts Packages on staging (packages.yml on: push). Not waited for: a red Packages run doesn't
+ # hold main (main's push then builds its own); a release checks it before tagging (release.sh step ci).
+ echo " Packages runs on the staging push"
if [ -n "$with" ]; then
bash -c "$with" > "/tmp/merge-queue-with-${sha:0:8}.log" 2>&1 &
pid=$!
@@ -218,7 +219,7 @@ run)
if [ "${2:-}" = --serial ]; then run_serial; else run_batch; fi
;;
*)
- sed -n '5,27p' "$0" | sed 's/^# \{0,1\}//'
+ sed -n '5,28p' "$0" | sed 's/^# \{0,1\}//'
exit 2
;;
esac
diff --git a/scripts/release.sh b/scripts/release.sh
index 24184dc7..2ad07da3 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -3,13 +3,21 @@
# SPDX-License-Identifier: GPL-3.0-or-later
#
# Releases SculptForge X.Y.Z from main and brings every channel to it in lock step (docs/releasing.md).
+# Build once, promote: the packages are built and tested once, on `staging`, carrying X.Y.Z; the release publishes
+# exactly those files.
#
-# HIGHLIGHTS=notes.txt scripts/release.sh X.Y.Z --yes every step, in order (the normal way: one command)
+# scripts/release.sh X.Y.Z --stage 1. in the merger's batch checkout: the bump commit on top of the
+# batch, then scripts/merge-queue.sh staging (STAGE_WITH, default '~/Work/.sf/t1.sh .', runs here
+# beside CI); main fast-forwards to it and packages.yml builds X.Y.Z on the push to staging
+# HIGHLIGHTS=notes.txt scripts/release.sh X.Y.Z --yes 2. on main: promotes. Checks main is the staged commit, waits for
+# and checks staging's Packages run (tools/release/staged_run.py), tags that exact commit; release.yml
+# verifies checksums and attestations, smoke-tests, signs and publishes; then site, feed, packages
+# scripts/release.sh X.Y.Z --rebuild --yes the old way (fallback): bump pushed to main, the release builds
+# its packages from the tag (about 40 minutes more)
# scripts/release.sh X.Y.Z --from site resume at a step (after fixing what stopped it)
# scripts/release.sh X.Y.Z --only replies one step
-# scripts/release.sh X.Y.Z --only bump --staged the bump commit only, not pushed: the merger puts it on top of
-# the release batch (RELEASE=X.Y.Z ~/Work/.sf/merge-batch.sh), so `staging` builds the packages of
-# the exact commit to tag while CI runs, and the release later only smoke-tests and publishes them
+# scripts/release.sh X.Y.Z --only bump --staged the bump commit only, not pushed (what --stage does first;
+# RELEASE=X.Y.Z ~/Work/.sf/merge-batch.sh uses it before its own staging run)
# scripts/release.sh X.Y.Z-beta.N --yes a beta (also -rc.N): a members-only pre-release in the private repository
# islandmed/sculptforge-insiders, announced in #members (see "Betas" below and docs/releasing.md)
# HIGHLIGHTS=file the update feed's 3-5 highlight lines, one per line (default: the version's highlight: lines in
@@ -17,9 +25,10 @@
# (the home page's What's New area is written by tools/guide/build_site.py from docs/guide/whats-new.md: the
# version's ```features block, its tagline and pictures; CARD is no longer used)
#
-# Steps: bump check ci tag release site aur brew omarchy replies status
-# bump sets every version file, rebuilds the guide and pushes main; check then verifies everything the later steps
-# need, so a release either stops in seconds before the tag or runs through to the end.
+# Steps: bump check ci tag release site aur brew omarchy replies status (--stage: bump stage)
+# bump sets every version file and rebuilds the guide (--stage: committed in the batch; --rebuild: pushed to main;
+# promoting: only checks main already has it); check then verifies everything the later steps need, so a release
+# either stops in seconds before the tag or runs through to the end.
# Each step looks at the live state first and skips what is already done, so running it again is always safe.
# When something is wrong it stops and prints the fix; fix it, then run again with --from <that step>.
# It never posts issue replies: it writes drafts for a person to read and post.
@@ -36,6 +45,7 @@ set -euo pipefail
REPO=islandmed/SculptForge
INSIDERS_REPO=islandmed/sculptforge-insiders # members' betas (release.yml publishes there with INSIDERS_REPO_TOKEN)
+MEMBER_ENV=member-release
AUTHOR_NAME=islandmed
[email protected] # never a personal address in outside repos
OMARCHY_PR=1800
@@ -47,8 +57,8 @@ ok() { printf ' ok: %s\n' "$*"; }
# resume STEP: the exact command that continues at STEP, with this run's HIGHLIGHTS, BUILD_DIR and --yes (a stopped
# release is one the owner already said ship it for; without --yes, step tag would stop again at "not confirmed").
resume() {
- printf '%s%sscripts/release.sh %s --from %s --yes' "${HIGHLIGHTS_GIVEN:+HIGHLIGHTS=$HIGHLIGHTS_GIVEN }" \
- "${BUILD_DIR:+BUILD_DIR=$BUILD_DIR }" "$V" "$1"
+ printf '%s%sscripts/release.sh %s%s --from %s --yes' "${HIGHLIGHTS_GIVEN:+HIGHLIGHTS=$HIGHLIGHTS_GIVEN }" \
+ "${BUILD_DIR:+BUILD_DIR=$BUILD_DIR }" "$V" "${MODE_FLAG:-}" "$1"
}
# die "what is wrong" "the exact fix"
die() {
@@ -68,23 +78,25 @@ confirm() {
V=${1:-}
[[ "$V" =~ ^([0-9]+\.[0-9]+\.[0-9]+)(-((beta|rc)\.[0-9]+))?$ ]] ||
- { echo "usage: scripts/release.sh X.Y.Z[-beta.N|-rc.N] [--from STEP | --only STEP] [--yes] [--staged]"; exit 2; }
+ { echo "usage: scripts/release.sh X.Y.Z[-beta.N|-rc.N] [--stage | --rebuild] [--from STEP | --only STEP] [--yes] [--staged]"; exit 2; }
BASE=${BASH_REMATCH[1]} PRE=${BASH_REMATCH[3]} # 0.11.0-beta.1: BASE 0.11.0, PRE beta.1; a stable release: PRE ""
[ -z "$PRE" ] || STEPS=(bump check ci tag release status)
RELEASE_REPO=$REPO; [ -z "$PRE" ] || RELEASE_REPO=$INSIDERS_REPO # where release.yml publishes this version
shift
-FROM=bump ONLY= STAGED=
+FROM=bump ONLY= STAGED= MODE=promote MODE_FLAG=
while [ $# -gt 0 ]; do
case $1 in
--from) FROM=$2; shift 2 ;;
--only) ONLY=$2; shift 2 ;;
--yes) YES=1; shift ;;
--staged) STAGED=1; shift ;;
+ --stage) [ $MODE = promote ] || { echo "--stage and --rebuild exclude each other"; exit 2; }; MODE=stage MODE_FLAG=" --stage" STAGED=1 STEPS=(bump stage); shift ;;
+ --rebuild) [ $MODE = promote ] || { echo "--stage and --rebuild exclude each other"; exit 2; }; MODE=rebuild MODE_FLAG=" --rebuild"; shift ;;
*) echo "unknown argument $1"; exit 2 ;;
esac
done
[[ " ${STEPS[*]} " == *" ${ONLY:-$FROM} "* ]] || { echo "unknown step ${ONLY:-$FROM}; steps: ${STEPS[*]}"; exit 2; }
-[ -z "$STAGED" ] || [ "$ONLY" = bump ] || { echo "--staged goes with --only bump (the later steps run on main after it lands)"; exit 2; }
+[ -z "$STAGED" ] || [ "$ONLY" = bump ] || [ $MODE = stage ] || { echo "--staged goes with --only bump (the later steps run on main after it lands)"; exit 2; }
T=v$V
TODAY=$(date +%F)
CURRENT=setup
@@ -109,10 +121,10 @@ push_main() {
release_ready() {
gh release view "$T" -R "$RELEASE_REPO" --json assets -q '.assets[].name' > "$work/assets" 2>/dev/null ||
die "no GitHub release $T yet" "run the earlier steps: $(resume tag)"
- grep -qx SHA256SUMS.txt "$work/assets" || die "release $T has no SHA256SUMS.txt (unfinished)" "re-run the Release workflow: gh workflow run release.yml -R $REPO -f tag=$T"
+ grep -qx SHA256SUMS.txt "$work/assets" || die "release $T has no SHA256SUMS.txt (unfinished)" "re-run the Release workflow: gh workflow run release.yml -R $REPO --ref $T -f tag=$T"
# One-click update (src/core/SelfUpdate.h): once the app has a key, every release must carry the signature.
if grep -q 'kUpdatePublicKeyHex = "[0-9a-f]\{64\}"' src/core/SelfUpdate.h 2>/dev/null; then
- grep -qx SHA256SUMS.txt.sig "$work/assets" || die "release $T has no SHA256SUMS.txt.sig: apps can't update to it in one click" "check the UPDATE_SIGNING_KEY secret, then re-run the Release workflow: gh workflow run release.yml -R $REPO -f tag=$T"
+ grep -qx SHA256SUMS.txt.sig "$work/assets" || die "release $T has no SHA256SUMS.txt.sig: apps can't update to it in one click" "check the UPDATE_SIGNING_KEY secret, then re-run the Release workflow: gh workflow run release.yml -R $REPO --ref $T -f tag=$T"
fi
}
# Downloads one release asset and checks it against SHA256SUMS.txt with a checksum computed here. Prints the sum.
@@ -196,6 +208,20 @@ wait_live() {
# gh_file OWNER/REPO PATH [REF]: a file's contents from GitHub ("" when it can't be read).
gh_file() { gh api "repos/$1/contents/$2${3:+?ref=$3}" -q .content 2>/dev/null | base64 -d 2>/dev/null || true; }
+# bumped: CMakeLists.txt (and for a stable release CHANGELOG) already say this version: step bump has been made.
+bumped() {
+ grep -q "^project(SculptForge VERSION ${BASE//./\\.}[ )]" CMakeLists.txt && prerelease_is "$PRE" &&
+ { [ -n "$PRE" ] || grep -q "^## \[${V//./\\.}\]" CHANGELOG.md; }
+}
+# staged_run SHA [--wait]: the id of staging's Packages run that this release may promote (tools/release/staged_run.py:
+# a push to staging by islandmed for exactly SHA, successful, at most SF_STAGED_MAX_DAYS (7) days old, artifacts
+# present). Its exit status: 0 found, 3 there is no staging run for SHA, 1 none may be promoted (why in $work/staged.err).
+staged_run() {
+ python3 tools/release/staged_run.py --repo "$REPO" --sha "$1" --actors "$AUTHOR_NAME" --max-days "${SF_STAGED_MAX_DAYS:-7}" \
+ ${2:+"$2"} 2>"$work/staged.err"
+}
+stage_fix() { echo "stage $V: in the merger's batch checkout, scripts/release.sh $V --stage (bump, staging, main), then $(resume ci); or build from the tag instead: ${1:-$(MODE_FLAG=" --rebuild" resume bump)}"; }
+
# --- preconditions: what the steps after the tag need, checked before anything is tagged --------------------------
# The home page's "new in X.Y.Z" card and "New in X.Y.Z:" lede in #whats-new, written by build_site.py (step bump) from
@@ -269,6 +295,19 @@ preflight() {
# The members' publishing path: release.yml's actions pinned to commit SHAs, INSIDERS_REPO_TOKEN only in the
# member-release environment (docs/releasing.md, "Secrets").
out=$(python3 tools/release/check_workflows.py 2>&1) || die "the release workflows aren't locked down: $out" "fix .github/workflows (docs/releasing.md, \"Secrets\"), commit, push main"
+ # The update signing key: only in the protected environments (deployments from tags v*), never at repository
+ # level, where every workflow on every branch (staging's packages included) could read it.
+ if [ "$mode" != bump ]; then
+ local env=release
+ [ -z "$PRE" ] || env=$MEMBER_ENV
+ gh secret list -R "$REPO" >"$work/secrets" 2>/dev/null || die "can't list the repository's secrets" "gh auth status (the owner's account)"
+ ! grep -q '^UPDATE_SIGNING_KEY\b' "$work/secrets" ||
+ die "UPDATE_SIGNING_KEY is a repository secret: any workflow on any branch could read it" \
+ "the owner moves it (the PEM from Drive \"SculptForge keys\"): gh secret set UPDATE_SIGNING_KEY --env release -R $REPO < key.pem (member-release has it already), then gh secret delete UPDATE_SIGNING_KEY -R $REPO"
+ gh secret list --env "$env" -R "$REPO" 2>/dev/null | grep -q '^UPDATE_SIGNING_KEY\b' ||
+ die "the $env environment has no UPDATE_SIGNING_KEY: release.yml couldn't sign SHA256SUMS.txt" \
+ "the owner sets it (the PEM from Drive \"SculptForge keys\"): gh secret set UPDATE_SIGNING_KEY --env $env -R $REPO < key.pem"
+ fi
if [ -n "$PRE" ]; then # a beta: members only, through the private repository; nothing of the site, no packages
gh secret list --env member-release -R "$REPO" 2>/dev/null | grep -q '^INSIDERS_REPO_TOKEN\b' ||
die "the member-release environment has no INSIDERS_REPO_TOKEN, so release.yml can't publish the beta to $INSIDERS_REPO" \
@@ -313,6 +352,12 @@ preflight() {
# Sets every version file to X.Y.Z, rebuilds the guide and the home page's What's New area, pushes main (--staged:
# commits on top of the checked-out batch and pushes nothing; scripts/merge-queue.sh staging lands it).
step_bump() {
+ if [ $MODE = promote ] && [ -z "$STAGED" ]; then # the bump was staged with the packages: main must already have it
+ on_main
+ bumped || die "main is not at $V yet: the bump goes through staging with the packages it names" "$(stage_fix)"
+ ok "main $(git rev-parse --short HEAD) already carries $V (staged)"
+ return
+ fi
if [ -n "$STAGED" ]; then
[ -z "$(git status --porcelain --untracked-files=no)" ] || die "uncommitted changes" "commit them first (git status)"
git fetch -q origin main --tags
@@ -426,10 +471,24 @@ PY
ok "version files at $V, guide rebuilt, pushed main $(git rev-parse --short HEAD)"
}
+# --stage: the batch with the bump on top goes through staging (CI there, STAGE_WITH here); main fast-forwards to it
+# and packages.yml builds the packages of X.Y.Z on the push to staging, which the release then promotes.
+step_stage() {
+ local sha with=${STAGE_WITH-}
+ sha=$(git rev-parse HEAD)
+ bumped || die "HEAD ${sha:0:8} is not at $V" "run the bump first: $(resume bump)"
+ [ -n "${STAGE_WITH+x}" ] || { [ -x "$HOME/Work/.sf/t1.sh" ] && with="$HOME/Work/.sf/t1.sh ."; }
+ "${MERGE_QUEUE:-scripts/merge-queue.sh}" staging ${with:+--with "$with"} "$sha" ||
+ die "staging ${sha:0:8} is red, or main moved (above)" "fix the batch (main moved: merge origin/main), then $(resume bump)"
+ ok "main is the staged ${sha:0:8} ($V); packages.yml is building its packages on the staging push"
+ echo " next, on main: ${HIGHLIGHTS_GIVEN:+HIGHLIGHTS=$HIGHLIGHTS_GIVEN }scripts/release.sh $V --yes (waits for that run, then promotes it)"
+}
+
step_check() {
on_main
preflight
local bump="run step bump: scripts/release.sh $V --only bump (it sets every version file)"
+ [ $MODE = rebuild ] || bump=$(stage_fix "scripts/release.sh $V --rebuild --only bump, then $(MODE_FLAG=" --rebuild" resume check)")
grep -q "^project(SculptForge VERSION ${BASE//./\\.}[ )]" CMakeLists.txt || die "CMakeLists.txt is not at $BASE" "$bump"
prerelease_is "$PRE" || die "CMakeLists.txt's SCULPTFORGE_PRERELEASE is not \"$PRE\"" "$bump"
if [ -n "$PRE" ]; then
@@ -469,17 +528,30 @@ step_ci() {
wait_run ci.yml "$sha" 18 >/dev/null || die "no CI run on main for $sha after 3 minutes" "push main first (git push origin main), or check Actions, then run again"
ok "CI passed on $sha"
fi
- if wait_run packages.yml "$sha" >/dev/null; then
- ok "the Packages run passed: the release will promote its tested packages"
- else
- echo " note: no Packages run for $sha (only website or paperwork changed since?): the release builds its own (about 20 min)"
+ if [ $MODE = rebuild ]; then
+ echo " note: --rebuild: the Release workflow builds the packages from the tag (about 40 min)"
+ return
fi
+ local run rc=0
+ echo " staging's Packages run for ${sha:0:8} (waits while it runs) ..."
+ run=$(staged_run "$sha" --wait) || rc=$?
+ case $rc in
+ 0) ok "staging's Packages run $run built and tested $V for ${sha:0:8}: the release promotes exactly its packages" ;;
+ 3) die "no Packages run on staging for ${sha:0:8}" "$(stage_fix)" ;;
+ *) die "staging's Packages runs for ${sha:0:8} can't be promoted: $(tail -1 "$work/staged.err")" \
+ "a failed run that was a runner hiccup: gh run rerun <id> --failed -R $REPO, then $(resume ci); otherwise $(stage_fix)" ;;
+ esac
}
step_tag() {
if gh api "repos/$REPO/git/ref/tags/$T" >/dev/null 2>&1; then ok "$T is already pushed"; return; fi
local sha
sha=$(git rev-parse HEAD)
+ if [ $MODE = promote ]; then # the tag goes on exactly the staged commit, which main is
+ git fetch -q origin main
+ [ "$sha" = "$(git rev-parse origin/main)" ] || die "HEAD ${sha:0:8} is not origin/main $(git rev-parse --short origin/main)" "git switch main && git merge --ff-only origin/main; if main moved past the staged commit, stage again: $(stage_fix)"
+ staged_run "$sha" >/dev/null || die "${sha:0:8} has no promotable staging Packages run: $(tail -1 "$work/staged.err")" "$(stage_fix)"
+ fi
confirm "Tag $T at $(git log -1 --format='%h %s' "$sha") and push it? This publishes SculptForge $V${PRE:+ for members, in $INSIDERS_REPO}." ||
die "not confirmed" "run again and answer y (or YES=1) once the owner has said ship it for $V"
git rev-parse -q --verify "refs/tags/$T" >/dev/null || git tag "$T" "$sha"
@@ -499,7 +571,7 @@ step_release() {
[ -n "$id" ] && break
sleep 10
done
- [ -n "$id" ] || die "no Release run for $T after 5 minutes" "gh workflow run release.yml -R $REPO -f tag=$T"
+ [ -n "$id" ] || die "no Release run for $T after 5 minutes" "gh workflow run release.yml -R $REPO --ref $T -f tag=$T"
echo " waiting for Release run $id (https://github.com/$REPO/actions/runs/$id) ..."
gh run watch "$id" -R "$REPO" --exit-status >/dev/null ||
die "Release run $id failed (https://github.com/$REPO/actions/runs/$id)" \
@@ -508,7 +580,7 @@ step_release() {
release_ready
local n
n=$(wc -l < "$work/assets")
- [ "$n" -ge 30 ] || die "release $T has only $n assets" "re-run the Release workflow: gh workflow run release.yml -R $REPO -f tag=$T"
+ [ "$n" -ge 30 ] || die "release $T has only $n assets" "re-run the Release workflow: gh workflow run release.yml -R $REPO --ref $T -f tag=$T"
ok "$n assets, SHA256SUMS.txt included"
}
diff --git a/tests/release_beta_test.sh b/tests/release_beta_test.sh
index cea70552..07aaddda 100755
--- a/tests/release_beta_test.sh
+++ b/tests/release_beta_test.sh
@@ -7,7 +7,9 @@
# so nothing reaches GitHub, the website or the build. It releases 9.0.0-beta.1 (steps bump check status: members
# only, nothing public),
# then promotes it to 9.0.0 (bump check site) with the beta tag present, and checks what each one may and may not
-# touch (docs/releasing.md, "Betas").
+# touch (docs/releasing.md, "Betas"). Those two take the old path (--rebuild: bump pushed to main). Then build once,
+# promote: 9.0.1 staged (--stage) and promoted, with the refusals (a dispatched or a stranger's staging run, the
+# signing key at repository level).
set -euo pipefail
ROOT=$(cd "$(dirname "$0")/.." && pwd)
@@ -59,9 +61,26 @@ mkdir -p "$S/bin" "$S/home" "$S/build"
touch "$S/build/CTestTestfile.cmake"
cat > "$S/bin/gh" <<EOF
#!/usr/bin/env bash
+# staging's Packages run for the asked commit (tools/release/staged_run.py): STAGED_EVENT, STAGED_ACTOR vary it.
+runs() {
+ sha=\$(sed -n 's/.*head_sha=\([0-9a-f]*\).*/\1/p' <<<"\$1")
+ printf '{"workflow_runs": [{"id": 77, "path": ".github/workflows/packages.yml", "head_sha": "%s", "head_branch": "staging",
+ "event": "%s", "status": "completed", "conclusion": "success", "created_at": "%s",
+ "head_repository": {"full_name": "islandmed/SculptForge"}, "repository": {"full_name": "islandmed/SculptForge"},
+ "actor": {"login": "%s"}, "triggering_actor": {"login": "islandmed"}}]}\n' \
+ "\$sha" "\${STAGED_EVENT:-push}" "\$(date -u +%FT%TZ)" "\${STAGED_ACTOR:-islandmed}"
+}
case "\$*" in
"auth status"*) echo "Logged in to github.com account islandmed" ;;
- "secret list"*) printf 'INSIDERS_REPO_TOKEN\t2026-11-05T00:00:00Z\n' ;;
+ "secret list --env"*) printf 'INSIDERS_REPO_TOKEN\t2026-11-05T00:00:00Z\nUPDATE_SIGNING_KEY\t2026-11-05T00:00:00Z\n' ;;
+ "secret list"*) printf 'DISCORD_MEMBERS_WEBHOOK\t2026-11-05T00:00:00Z\n'; [ -z "\${SECRET_AT_REPO:-}" ] || printf 'UPDATE_SIGNING_KEY\t2026-11-05T00:00:00Z\n' ;;
+ "api repos/islandmed/SculptForge/actions/workflows/packages.yml/runs"*) runs "\$2" ;;
+ "api repos/islandmed/SculptForge/actions/runs/77/artifacts"*)
+ python3 -c 'import json; print(json.dumps({"artifacts": [{"name": n} for n in "linux-x86_64 linux-arm64 flatpak-x86_64 flatpak-aarch64 vfx-vfx2026-x86_64 vfx-vfx2026-arm64 vfx-vfx2027-x86_64 vfx-vfx2027-arm64 macos windows staged-sums".split()]}))' ;;
+ "api repos/islandmed/SculptForge/git/ref/tags/"*) exit 1 ;; # not pushed yet
+ "run list"*) echo 7 ;;
+ "run view"*"-q .status"*) echo completed ;;
+ "run view"*"-q .conclusion"*) echo success ;;
"repo view islandmed/sculptforge-insiders"*) echo "islandmed/sculptforge-insiders" ;;
"release view"*) printf 'SHA256SUMS.txt\nSHA256SUMS.txt.sig\n' ;; # (signed: the app has an update key)
"release download"*) exit 1 ;;
@@ -98,10 +117,12 @@ done
# --- the beta ------------------------------------------------------------------------------------------------------
start=$(git rev-parse HEAD)
echo 'placeholder: {{SOME_NUMBER}}' >>CHANGELOG.md && git commit -q -am placeholder
-scripts/release.sh 9.0.0-beta.1 --only bump >"$S/out.log" 2>&1 && fail "bump passed with an unfilled placeholder"
+scripts/release.sh 9.0.0-beta.1 --rebuild --only bump >"$S/out.log" 2>&1 && fail "bump passed with an unfilled placeholder"
grep -q 'unfilled placeholders: CHANGELOG.md' "$S/out.log" || fail "no placeholder stop: $(cat "$S/out.log")"
git reset -q --hard HEAD^
-quiet scripts/release.sh 9.0.0-beta.1 --only bump
+scripts/release.sh 9.0.0-beta.1 --only bump >"$S/out.log" 2>&1 && fail "bump on main without --rebuild (promote mode) bumped"
+grep -q -- '--stage' "$S/out.log" || fail "promote mode's bump doesn't point at --stage: $(cat "$S/out.log")"
+quiet scripts/release.sh 9.0.0-beta.1 --rebuild --only bump
grep -q '^project(SculptForge VERSION 9.0.0 ' CMakeLists.txt || fail "beta bump: CMakeLists.txt is not at 9.0.0"
grep -qx 'set(SCULPTFORGE_PRERELEASE "beta.1")' CMakeLists.txt || fail "beta bump: no prerelease beta.1"
for f in $stable_files; do
@@ -123,7 +144,7 @@ git checkout -q -- tests/ui/whats_new.sfui
quiet scripts/release.sh 9.0.0-beta.1 --only check
grep -q 'CMakeLists.txt says 9.0.0 beta.1' "$S/out.log" || fail "beta check: $(cat "$S/out.log")"
-quiet scripts/release.sh 9.0.0-beta.1 --only bump # again: nothing left to do
+quiet scripts/release.sh 9.0.0-beta.1 --rebuild --only bump # again: nothing left to do
grep -q 'already says' "$S/out.log" || fail "beta bump is not idempotent: $(cat "$S/out.log")"
# A beta is members only: nothing of the site or the update feed changes.
@@ -147,7 +168,7 @@ open(p, "w", encoding="utf-8").write(t.replace(head, head + "tagline: The beta,
EOF
grep -q '^tagline: The beta, finished.$' docs/guide/whats-new.md || fail "test setup: couldn't add the tagline"
git commit -q -am "What's New 9.0.0 tagline" && git push -q origin main
-quiet scripts/release.sh 9.0.0 --only bump
+quiet scripts/release.sh 9.0.0 --rebuild --only bump
grep -qx 'set(SCULPTFORGE_PRERELEASE "")' CMakeLists.txt || fail "stable bump didn't clear the prerelease"
grep -q '^## \[9.0.0\] - ' CHANGELOG.md || fail "stable bump: no CHANGELOG [9.0.0]"
grep -qx 'version: 9.0.0' CITATION.cff || fail "stable bump: CITATION.cff not at 9.0.0"
@@ -162,4 +183,53 @@ feed = json.load(open("website/latest.json"))
assert feed["version"] == "9.0.0" and feed["highlights"] == ["One", "Two", "Three"], feed
assert "preview" not in feed.get("channels", {}), "the passed beta is still on the Preview channel"
EOF
-echo "release.sh beta and promotion: ok"
+
+git push -q origin main
+
+# --- build once, promote: 9.0.1 staged, then promoted ----------------------------------------------------------------
+cat > changes/promote-test.md <<'EOF'
+---
+whats_new: **Promote test**: built once.
+highlight: First highlight of 9.0.1
+highlight: Second highlight of 9.0.1
+highlight: Third highlight of 9.0.1
+fixed: **Promote test**: built once.
+---
+EOF
+python3 - <<'EOF'
+p = "docs/guide/whats-new.md"
+t = open(p, encoding="utf-8").read()
+i = t.index("## Version 9.0.0")
+open(p, "w", encoding="utf-8").write(t[:i] + "## Version 9.0.1\n\n```features\ndate: unreleased\ntagline: Built once.\n```\n\n" + t[i:])
+EOF
+git add changes docs/guide/whats-new.md && git commit -q -m "9.0.1 notes" && git push -q origin main
+# The merger's batch checkout (detached, main merged in); a stand-in merge queue lands it on staging and main.
+cat > "$S/bin/mq" <<EOF
+#!/usr/bin/env bash
+echo "\$*" > "$S/mq.args"
+git push -q origin "\${@: -1}:refs/heads/staging" "\${@: -1}:refs/heads/main"
+EOF
+chmod +x "$S/bin/mq"
+git switch -q --detach
+MERGE_QUEUE=$S/bin/mq STAGE_WITH= quiet scripts/release.sh 9.0.1 --stage
+staged=$(git rev-parse HEAD)
+[ "$(git -C "$S/origin.git" rev-parse staging)" = "$staged" ] || fail "--stage didn't put the bump on staging"
+grep -q "^staging $staged\$" "$S/mq.args" || fail "--stage ran the merge queue as: $(cat "$S/mq.args")"
+grep -q '^## \[9.0.1\]' CHANGELOG.md || fail "--stage: no CHANGELOG [9.0.1] in the staged commit"
+git switch -q main && git merge -q --ff-only origin/main
+quiet scripts/release.sh 9.0.1 --only bump # promoting: main already carries it
+grep -q 'already carries 9.0.1' "$S/out.log" || fail "promote bump: $(cat "$S/out.log")"
+SECRET_AT_REPO=1 scripts/release.sh 9.0.1 --only check >"$S/out.log" 2>&1 && fail "check passed with UPDATE_SIGNING_KEY at repository level"
+grep -q 'UPDATE_SIGNING_KEY is a repository secret' "$S/out.log" || fail "no signing-key stop: $(cat "$S/out.log")"
+quiet scripts/release.sh 9.0.1 --only check
+STAGED_EVENT=workflow_dispatch scripts/release.sh 9.0.1 --only ci >"$S/out.log" 2>&1 && fail "ci accepted a dispatched staging run"
+grep -q 'no Packages run on staging' "$S/out.log" || fail "dispatched run: $(cat "$S/out.log")"
+STAGED_ACTOR=mallory scripts/release.sh 9.0.1 --only ci >"$S/out.log" 2>&1 && fail "ci accepted a stranger's staging run"
+grep -q "can't be promoted: .*mallory" "$S/out.log" || fail "stranger's run: $(cat "$S/out.log")"
+STAGED_ACTOR=mallory scripts/release.sh 9.0.1 --only tag >"$S/out.log" 2>&1 && fail "tag accepted a stranger's staging run"
+git -C "$S/origin.git" rev-parse -q --verify v9.0.1 >/dev/null && fail "a refused promotion pushed the tag"
+quiet scripts/release.sh 9.0.1 --only ci
+grep -q "Packages run 77 built and tested 9.0.1" "$S/out.log" || fail "promote ci: $(cat "$S/out.log")"
+quiet scripts/release.sh 9.0.1 --only tag
+[ "$(git -C "$S/origin.git" rev-parse 'v9.0.1^{commit}')" = "$staged" ] || fail "v9.0.1 doesn't tag the staged commit"
+echo "release.sh beta, promotion, build once: ok"
diff --git a/tools/release/check_workflows.py b/tools/release/check_workflows.py
index 40a1c1a4..1654be36 100755
--- a/tools/release/check_workflows.py
+++ b/tools/release/check_workflows.py
@@ -9,7 +9,12 @@
(contents: write) or isn't limited to betas,
- any workflow's job reads INSIDERS_REPO_TOKEN outside a GitHub Environment (environment secrets are invisible
there anyway, so such a job is a sign someone put the token back at repository level),
- - any workflow uses pull_request_target, or release.yml turns on shell tracing (set -x) that would log values.
+ - any workflow uses pull_request_target, or release.yml turns on shell tracing (set -x) that would log values,
+ - build once, promote (docs/releasing.md): a job reads UPDATE_SIGNING_KEY outside the environments `release` and
+ `member-release`; release.yml's publish isn't in `release`; locate doesn't pick the packages with
+ tools/release/staged_run.py; a publisher doesn't need job verify or re-check the checksums
+ (tools/release/verify_staged.py); packages.yml reads any secret, or a job of it uploads packages without a
+ pinned actions/attest-build-provenance step.
Plain text parsing (no PyYAML): workflows here keep jobs at two spaces and their keys at four.
"""
@@ -19,6 +24,9 @@ from pathlib import Path
TOKEN = "secrets.INSIDERS_REPO_TOKEN"
MEMBER_ENV = "member-release"
+SIGNING = "secrets.UPDATE_SIGNING_KEY"
+SIGNING_ENVS = {"release", MEMBER_ENV}
+ATTEST = re.compile(r"uses:\s*actions/attest-build-provenance@[0-9a-f]{40}\b")
PINNED = re.compile(r"^[\w.-]+/[\w./-]+@[0-9a-f]{40}(\s+#\s*\S.*)?$")
@@ -44,7 +52,7 @@ def jobs(text):
def environment(lines):
for line in lines:
- m = re.match(r"^ environment:\s*(\S.*?)\s*$", line)
+ m = re.match(r"^ environment:\s*([^#\s]+)", line)
if m:
return m.group(1).strip("'\"")
return None
@@ -59,6 +67,16 @@ def check(files):
for job, lines in jobs(text).items():
if any(TOKEN in l for l in lines) and not environment(lines):
errs.append(f"{name}: job {job} reads INSIDERS_REPO_TOKEN outside a GitHub Environment")
+ if any(SIGNING in l for l in lines) and environment(lines) not in SIGNING_ENVS:
+ errs.append(f"{name}: job {job} reads UPDATE_SIGNING_KEY outside the environments release / member-release")
+ pk = files.get("packages.yml")
+ if pk is not None:
+ if "secrets." in pk:
+ errs.append("packages.yml: reads a secret (staging builds must never see one; signing happens at promotion)")
+ for job, lines in jobs(pk).items():
+ body = "\n".join(lines)
+ if job != "sums" and "upload-artifact" in body and not ATTEST.search(body):
+ errs.append(f"packages.yml: job {job} uploads packages without a pinned actions/attest-build-provenance step")
rel = files.get("release.yml")
if rel is None:
return errs + ["release.yml: missing"]
@@ -68,7 +86,18 @@ def check(files):
errs.append(f"release.yml:{n}: `uses: {m.group(1)}` is not pinned to a full commit SHA (pin it, comment the version)")
if re.search(r"(^|[\s;])set\s+-[a-wyz]*x", line):
errs.append(f"release.yml:{n}: shell tracing (set -x) would log secret-derived values")
- holders = {j: l for j, l in jobs(rel).items() if any(TOKEN in x for x in l)}
+ rj = jobs(rel)
+ if "staged_run.py" not in "\n".join(rj.get("locate", [])):
+ errs.append("release.yml: job locate doesn't pick the packages with tools/release/staged_run.py")
+ if "verify_staged.py" not in "\n".join(rj.get("verify", [])):
+ errs.append("release.yml: no job verify running tools/release/verify_staged.py")
+ if environment(rj.get("publish", [])) != "release":
+ errs.append("release.yml: job publish isn't in `environment: release` (the only holder of UPDATE_SIGNING_KEY)")
+ for job in ("publish", "publish-members"):
+ body = "\n".join(rj.get(job, []))
+ if not re.search(r"needs:.*\bverify\b", body) or "verify_staged.py" not in body:
+ errs.append(f"release.yml: job {job} must need verify and re-check the checksums (verify_staged.py --sums-only)")
+ holders = {j: l for j, l in rj.items() if any(TOKEN in x for x in l)}
if not holders:
errs.append("release.yml: no job publishes to the insiders repository with INSIDERS_REPO_TOKEN")
for job, lines in holders.items():
@@ -90,22 +119,52 @@ GOOD = """on:
permissions:
contents: read
jobs:
+ locate:
+ steps:
+ - run: python3 tools/release/staged_run.py --sha "$sha"
build:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: ./.github/workflows/packages.yml
+ verify:
+ steps:
+ - run: python3 tools/release/verify_staged.py dist sums
+ publish:
+ needs: [locate, build, verify, smoke]
+ environment: release
+ steps:
+ - run: python3 tools/release/verify_staged.py dist sums --sums-only
+ - env:
+ UPDATE_SIGNING_KEY: ${{ secrets.UPDATE_SIGNING_KEY }}
+ run: tools/release/sign_sums.sh dist
publish-members:
+ needs: [locate, build, verify, smoke]
if: ${{ contains(needs.locate.outputs.tag, '-') }}
environment: member-release
permissions:
contents: read
steps:
+ - run: python3 tools/release/verify_staged.py dist sums --sums-only
- name: Publish
env:
GH_TOKEN: ${{ secrets.INSIDERS_REPO_TOKEN }}
run: gh release create
"""
+PACKAGES = """on:
+ push:
+ branches: [main, staging]
+jobs:
+ linux:
+ permissions:
+ id-token: write
+ steps:
+ - uses: actions/upload-artifact@v7
+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+ sums:
+ steps:
+ - uses: actions/upload-artifact@v7
+"""
def self_test():
@@ -114,6 +173,16 @@ def self_test():
"unpinned": ({"release.yml": GOOD.replace("checkout@3d3c42e5aac5ba805825da76410c181273ba90b1", "checkout@v7")}, 1),
"short sha": ({"release.yml": GOOD.replace("3d3c42e5aac5ba805825da76410c181273ba90b1", "3d3c42e")}, 1),
"no environment": ({"release.yml": GOOD.replace(" environment: member-release\n", "")}, 1),
+ "packages good": ({"release.yml": GOOD, "packages.yml": PACKAGES}, 0),
+ "packages unattested": ({"release.yml": GOOD, "packages.yml": PACKAGES.replace("attest-build-provenance", "x")}, 1),
+ "packages attest unpinned": ({"release.yml": GOOD, "packages.yml": PACKAGES.replace("@4d101475d8b20a2381f78447822ac1eab6504dd8", "@v4")}, 1),
+ "packages secret": ({"release.yml": GOOD, "packages.yml": PACKAGES + " env: { K: '${{ secrets.X }}' }\n"}, 1),
+ "signing key outside env": ({"release.yml": GOOD.replace(" environment: release\n", "")}, 1),
+ "signing key at repo level elsewhere": ({"release.yml": GOOD, "x.yml": f"jobs:\n a:\n env:\n K: ${{{{ {SIGNING} }}}}\n"}, 1),
+ "no staged_run": ({"release.yml": GOOD.replace("staged_run.py", "x.py")}, 1),
+ "no verify job": ({"release.yml": GOOD.replace(" verify:\n", " check:\n")}, 1),
+ "publish without verify": ({"release.yml": GOOD.replace("needs: [locate, build, verify, smoke]\n environment: release", "needs: [locate, build, smoke]\n environment: release")}, 1),
+ "members without re-check": ({"release.yml": GOOD.replace(" - run: python3 tools/release/verify_staged.py dist sums --sums-only\n - name: Publish", " - name: Publish")}, 1),
"other environment": ({"release.yml": GOOD.replace("member-release", "production")}, 1),
"write token": ({"release.yml": GOOD.replace(" contents: read\n steps", " contents: write\n steps")}, 1),
"not beta-only": ({"release.yml": GOOD.replace("contains(needs.locate.outputs.tag, '-')", "true")}, 1),
diff --git a/tools/release/sign_sums.sh b/tools/release/sign_sums.sh
index e07fb96b..96692dcb 100755
--- a/tools/release/sign_sums.sh
+++ b/tools/release/sign_sums.sh
@@ -1,7 +1,8 @@
#!/usr/bin/env bash
# Signs DIST/SHA256SUMS.txt for one-click update (src/core/SelfUpdate.h): DIST/SHA256SUMS.txt.sig, a raw 64-byte
-# Ed25519 signature, made with the private key in $UPDATE_SIGNING_KEY (a PEM; the repository secret). Used by
-# release.yml for public releases and member betas alike (the same key, the same check in the app).
+# Ed25519 signature, made with the private key in $UPDATE_SIGNING_KEY (a PEM; a secret of the environments release and
+# member-release only, never the repository's). Used by release.yml at promotion, for public releases and member betas
+# alike (the same key, the same check in the app); the staging builds never see it.
# tools/release/sign_sums.sh DIST [SOURCE_DIR] SOURCE_DIR: the checkout whose kUpdatePublicKeyHex must match
# No secret: a warning while the app has no key yet, an error once it has one.
set -euo pipefail
diff --git a/tools/release/staged_run.py b/tools/release/staged_run.py
new file mode 100755
index 00000000..daddec57
--- /dev/null
+++ b/tools/release/staged_run.py
@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The one Packages run a release may promote for a commit (docs/releasing.md, "Build once, promote").
+
+ staged_run.py --sha SHA [--repo R] [--max-days N] [--actors a,b] [--wait]
+
+Prints the run id and exits 0 when a run of .github/workflows/packages.yml in this repository
+ - was triggered by a push to the branch `staging` (scripts/merge-queue.sh staging), for exactly SHA: never a
+ pull_request, never a workflow_dispatch, never a fork,
+ - was pushed and (re)run by a maintainer (actor and triggering_actor in --actors),
+ - finished with success, at most --max-days ago (default 7; artifacts are kept 14),
+ - still has every package artifact and the recorded checksums (staged-sums), none expired.
+Exits 3 when no Packages run was pushed to staging for SHA at all (release.yml then builds from the tag: the
+--rebuild path), 1 when there are such runs but none may be promoted (the reasons on stderr). --wait waits for a run
+in progress. scripts/release.sh (steps ci and tag) and release.yml (job locate) both use it.
+"""
+import argparse
+import json
+import subprocess
+import sys
+import time
+from datetime import datetime, timedelta, timezone
+
+WORKFLOW = ".github/workflows/packages.yml"
+ARTIFACTS = {
+ "linux-x86_64", "linux-arm64", "flatpak-x86_64", "flatpak-aarch64", "vfx-vfx2026-x86_64", "vfx-vfx2026-arm64",
+ "vfx-vfx2027-x86_64", "vfx-vfx2027-arm64", "macos", "windows", "staged-sums",
+}
+
+
+def ts(s):
+ return datetime.fromisoformat(s.replace("Z", "+00:00"))
+
+
+def candidates(runs, sha, repo):
+ """Runs pushed to staging for exactly sha, from this repository's own packages.yml."""
+ return [r for r in runs if r.get("path") == WORKFLOW and r.get("head_sha") == sha and r.get("head_branch") == "staging"
+ and r.get("event") == "push" and (r.get("head_repository") or {}).get("full_name") == repo
+ and (r.get("repository") or {}).get("full_name") == repo]
+
+
+def choose(runs, artifacts, sha, repo, actors, now, max_days):
+ """(run id, 0) | (None, 3, why) | (None, 1, why) | (None, 2, why: in progress). artifacts: {run id: [artifact]}."""
+ cs = candidates(runs, sha, repo)
+ if not cs:
+ return None, 3, f"no Packages run pushed to staging for {sha[:12]}"
+ why = []
+ for r in sorted(cs, key=lambda r: r["created_at"], reverse=True):
+ rid = r["id"]
+ if r.get("status") != "completed":
+ why.append(f"run {rid} is {r.get('status')}")
+ continue
+ if r.get("conclusion") != "success":
+ why.append(f"run {rid} {r.get('conclusion')}")
+ continue
+ who = {(r.get("actor") or {}).get("login"), (r.get("triggering_actor") or {}).get("login")}
+ if not who <= actors:
+ why.append(f"run {rid} was pushed or rerun by {', '.join(sorted(map(str, who - actors)))}, not a maintainer")
+ continue
+ age = now - ts(r["created_at"])
+ if age > timedelta(days=max_days):
+ why.append(f"run {rid} is {age.days} days old (at most {max_days})")
+ continue
+ arts = artifacts.get(rid, [])
+ have = {a["name"] for a in arts if not a.get("expired")}
+ missing = ARTIFACTS - have
+ if missing:
+ why.append(f"run {rid} lacks artifacts {', '.join(sorted(missing))} (expired or never built)")
+ continue
+ return rid, 0, ""
+ pending = any(r.get("status") != "completed" for r in cs)
+ return None, 2 if pending else 1, "; ".join(why)
+
+
+def gh(path):
+ out = subprocess.run(["gh", "api", path], check=True, capture_output=True, text=True).stdout
+ return json.loads(out)
+
+
+def live(sha, repo):
+ runs = gh(f"repos/{repo}/actions/workflows/packages.yml/runs?head_sha={sha}&branch=staging&event=push&per_page=20")["workflow_runs"]
+ arts = {r["id"]: gh(f"repos/{repo}/actions/runs/{r['id']}/artifacts?per_page=100")["artifacts"]
+ for r in candidates(runs, sha, repo) if r.get("conclusion") == "success"}
+ return runs, arts
+
+
+def self_test():
+ sha, repo, now = "a" * 40, "o/r", ts("2026-11-05T12:00:00Z")
+ me = {"login": "islandmed"}
+
+ def run(**k):
+ r = {"id": 1, "path": WORKFLOW, "head_sha": sha, "head_branch": "staging", "event": "push", "status": "completed",
+ "conclusion": "success", "head_repository": {"full_name": repo}, "repository": {"full_name": repo},
+ "actor": me, "triggering_actor": me, "created_at": "2026-11-04T12:00:00Z"}
+ r.update(k)
+ return r
+ full = {1: [{"name": n} for n in ARTIFACTS]}
+ cases = {
+ "good": ([run()], full, 0),
+ "none": ([], {}, 3),
+ "dispatch": ([run(event="workflow_dispatch")], full, 3),
+ "pull request": ([run(event="pull_request")], full, 3),
+ "fork": ([run(head_repository={"full_name": "evil/r"})], full, 3),
+ "other branch": ([run(head_branch="main")], full, 3),
+ "other workflow": ([run(path=".github/workflows/ci.yml")], full, 3),
+ "other commit": ([run(head_sha="b" * 40)], full, 3),
+ "failed": ([run(conclusion="failure")], full, 1),
+ "in progress": ([run(status="in_progress", conclusion=None)], full, 2),
+ "stranger": ([run(actor={"login": "mallory"})], full, 1),
+ "stranger rerun": ([run(triggering_actor={"login": "mallory"})], full, 1),
+ "old": ([run(created_at="2026-10-20T12:00:00Z")], full, 1),
+ "expired": ([run()], {1: [{"name": n, "expired": n == "macos"} for n in ARTIFACTS]}, 1),
+ "no sums": ([run()], {1: [{"name": n} for n in ARTIFACTS - {"staged-sums"}]}, 1),
+ "newer failed, older ok": ([run(id=2, conclusion="failure", created_at="2026-11-05T11:00:00Z"), run()], full, 0),
+ }
+ bad = []
+ for name, (runs, arts, want) in cases.items():
+ got = choose(runs, arts, sha, repo, {"islandmed"}, now, 7)
+ if got[1] != want:
+ bad.append(f"{name}: want {want}, got {got}")
+ for b in bad:
+ print("self-test FAIL", b)
+ print("self-test", "failed" if bad else "ok")
+ return 1 if bad else 0
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--sha")
+ ap.add_argument("--repo", default="islandmed/SculptForge")
+ ap.add_argument("--max-days", type=int, default=7)
+ ap.add_argument("--actors", default="islandmed")
+ ap.add_argument("--wait", action="store_true", help="wait (up to 2 hours) for a staging run in progress")
+ ap.add_argument("--self-test", action="store_true")
+ a = ap.parse_args()
+ if a.self_test:
+ return self_test()
+ if not a.sha or len(a.sha) != 40:
+ ap.error("--sha takes a full 40-hex commit SHA")
+ actors = set(a.actors.split(","))
+ end = time.time() + 7200
+ while True:
+ runs, arts = live(a.sha, a.repo)
+ rid, code, why = choose(runs, arts, a.sha, a.repo, actors, datetime.now(timezone.utc), a.max_days)
+ if code == 2 and a.wait and time.time() < end:
+ print(f" waiting for the staging Packages run ({why}) ...", file=sys.stderr)
+ time.sleep(60)
+ continue
+ break
+ if code == 0:
+ print(rid)
+ return 0
+ print(why, file=sys.stderr)
+ return 1 if code == 2 else code
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/release/verify_staged.py b/tools/release/verify_staged.py
new file mode 100755
index 00000000..edf3faa6
--- /dev/null
+++ b/tools/release/verify_staged.py
@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Checks the packages a release is about to publish (release.yml, jobs verify and publish). Refuses on any mismatch.
+
+ verify_staged.py DIST SUMS --run ID --sha SHA [--staged] [--repo R] [--sums-only]
+
+1. Checksums: DIST holds exactly the files SUMS lists (SHA256SUMS.staged.txt, written by packages.yml's job sums in
+ the run that built them), and each file's SHA-256, computed here, is the one listed.
+2. Provenance (skipped with --sums-only): each file has a GitHub artifact attestation (actions/attest-build-provenance
+ in packages.yml), checked with `gh attestation verify`: signed by this repository's packages.yml, for exactly SHA,
+ in run ID; with --staged also from refs/heads/staging and a push (the merge queue's staging run).
+"""
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def sha256(p):
+ h = hashlib.sha256()
+ with open(p, "rb") as f:
+ for b in iter(lambda: f.read(1 << 20), b""):
+ h.update(b)
+ return h.hexdigest()
+
+
+def read_sums(text):
+ out = {}
+ for line in text.splitlines():
+ if not line.strip():
+ continue
+ digest, name = line.split(None, 1)
+ out[name.lstrip("*")] = digest.lower()
+ return out
+
+
+def check_sums(dist, sums):
+ """Problems: files missing, extra or with another SHA-256 than recorded."""
+ have = {p.name for p in Path(dist).iterdir() if p.is_file()}
+ errs = [f"{n}: recorded but not downloaded" for n in sorted(set(sums) - have)]
+ errs += [f"{n}: not in the recorded checksums" for n in sorted(have - set(sums))]
+ errs += [f"{n}: SHA-256 {d} here, {sums[n]} recorded" for n in sorted(have & set(sums))
+ if (d := sha256(Path(dist) / n)) != sums[n]]
+ return errs
+
+
+def attested(certs, run, staged):
+ """True when one attestation's certificate is from run `run` (and, staged, a push)."""
+ for c in certs:
+ if f"/actions/runs/{run}/" not in c.get("runInvocationURI", ""):
+ continue
+ if staged and c.get("buildTrigger") != "push":
+ continue
+ return True
+ return False
+
+
+def check_attestation(path, repo, run, sha, staged):
+ cmd = ["gh", "attestation", "verify", str(path), "--repo", repo, "--signer-workflow", f"{repo}/.github/workflows/packages.yml",
+ "--source-digest", sha, "--format", "json"]
+ if staged:
+ cmd += ["--source-ref", "refs/heads/staging"]
+ p = subprocess.run(cmd, capture_output=True, text=True)
+ if p.returncode != 0:
+ return f"{path.name}: no valid attestation ({(p.stderr or p.stdout).strip().splitlines()[-1:] or ['gh failed']})"
+ certs = [r["verificationResult"]["signature"]["certificate"] for r in json.loads(p.stdout)]
+ if not attested(certs, run, staged):
+ return f"{path.name}: attested, but not by run {run}{' on a push to staging' if staged else ''}"
+ return None
+
+
+def self_test():
+ import tempfile
+ bad = []
+ with tempfile.TemporaryDirectory() as d:
+ (Path(d) / "a.deb").write_bytes(b"deb")
+ (Path(d) / "b.dmg").write_bytes(b"dmg")
+ good = {"a.deb": sha256(Path(d) / "a.deb"), "b.dmg": sha256(Path(d) / "b.dmg")}
+ cases = {
+ "good": (good, 0),
+ "changed": ({**good, "b.dmg": "0" * 64}, 1),
+ "missing": ({**good, "c.exe": "0" * 64}, 1),
+ "extra": ({"a.deb": good["a.deb"]}, 1),
+ }
+ for name, (sums, n) in cases.items():
+ if bool(check_sums(d, sums)) != bool(n):
+ bad.append(f"sums {name}: {check_sums(d, sums)}")
+ if read_sums("ab x\ncd *y\n") != {"x": "ab", "y": "cd"}:
+ bad.append("read_sums")
+ run = "https://github.com/o/r/actions/runs/42/attempts/1"
+ certs = {
+ "staged push": ([{"runInvocationURI": run, "buildTrigger": "push"}], True, True),
+ "other run": ([{"runInvocationURI": run.replace("42", "43"), "buildTrigger": "push"}], True, False),
+ "run id prefix": ([{"runInvocationURI": run.replace("42", "421"), "buildTrigger": "push"}], True, False),
+ "dispatch": ([{"runInvocationURI": run, "buildTrigger": "workflow_dispatch"}], True, False),
+ "rebuild dispatch": ([{"runInvocationURI": run, "buildTrigger": "workflow_dispatch"}], False, True),
+ "none": ([], False, False),
+ }
+ for name, (c, staged, want) in certs.items():
+ if attested(c, "42", staged) != want:
+ bad.append(f"attested {name}")
+ for b in bad:
+ print("self-test FAIL", b)
+ print("self-test", "failed" if bad else "ok")
+ return 1 if bad else 0
+
+
+def main():
+ if "--self-test" in sys.argv:
+ return self_test()
+ ap = argparse.ArgumentParser()
+ ap.add_argument("dist")
+ ap.add_argument("sums")
+ ap.add_argument("--run", required=True)
+ ap.add_argument("--sha", required=True)
+ ap.add_argument("--repo", default="islandmed/SculptForge")
+ ap.add_argument("--staged", action="store_true")
+ ap.add_argument("--sums-only", action="store_true")
+ a = ap.parse_args()
+ sums = read_sums(Path(a.sums).read_text(encoding="utf-8"))
+ errs = ["no recorded checksums"] if not sums else check_sums(a.dist, sums)
+ if not errs and not a.sums_only:
+ errs = [e for p in sorted(Path(a.dist).iterdir()) if (e := check_attestation(p, a.repo, a.run, a.sha, a.staged))]
+ for e in errs:
+ print(f"::error::{e}")
+ if errs:
+ print(f"REFUSED: {len(errs)} problem(s); nothing is published")
+ return 1
+ print(f"{len(sums)} files: SHA-256 as recorded by run {a.run}" + ("" if a.sums_only else ", each attested by packages.yml for " + a.sha[:12]))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/test/impacted.py b/tools/test/impacted.py
index e462b428..cf1b1aab 100644
--- a/tools/test/impacted.py
+++ b/tools/test/impacted.py
@@ -43,7 +43,9 @@ HAND_MAP = [
("scripts/merge-queue.sh", "ci_no_revert"),
("tests/ui/whats_new.sfui", "release_pin_whats_new release_script_beta"),
("tests/release_beta_test.sh", "release_script_beta"),
- ("tools/release/*", "release_notes release_notes_fragments release_script_beta release_pin_whats_new"),
+ ("tools/release/*", "release_notes release_notes_fragments release_script_beta release_pin_whats_new release_workflows"
+ " release_workflows_self_test release_paperwork release_staged_run release_verify_staged"),
+ (".github/workflows/*", "release_workflows release_script_beta"),
("packaging/windows/*", "ui_windows_dpi_2560 ui_windows_dpi_2160 ui_ui_scale_900"),
("addons/blender/*", "blender_exchange blender_addon_package blender_addon"),
("integrations/maya/*", "maya_shelf_script ui_maya_bridge"),