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.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
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.ymlindex 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: reuseif: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}+ permissions: # the attestation: a signed statement of what this run built+ contents: read+ id-token: write+ attestations: writeruns-on: ${{ matrix.os }}strategy:fail-fast: false@@ -156,12 +163,24 @@ jobs:build/*.tar.gzbuild/*.AppImagebuild/*.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: reuseif: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}+ permissions: # the attestation: a signed statement of what this run built+ contents: read+ id-token: write+ attestations: writeruns-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/*.flatpakvfx:name: ${{ matrix.label }} ${{ matrix.arch }}needs: reuseif: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}+ permissions: # the attestation: a signed statement of what this run built+ contents: read+ id-token: write+ attestations: writeruns-on: ${{ matrix.os }}container: ${{ matrix.image }}strategy:@@ -291,11 +318,21 @@ jobs:path: |build/*.rpmbuild/*.tar.gz+ retention-days: 14+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2+ with:+ subject-path: |+ build/*.rpm+ build/*.tar.gzmacos:name: macOS (universal .dmg)needs: reuseif: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}+ permissions: # the attestation: a signed statement of what this run built+ contents: read+ id-token: write+ attestations: writeruns-on: ${{ vars.SF_RUNNER_MAC || 'macos-15' }}steps:- uses: actions/checkout@v7@@ -347,11 +384,19 @@ jobs:with:name: macospath: build/*.dmg+ retention-days: 14+ - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2+ with:+ subject-path: build/*.dmgwindows:name: Windows x64 (installer, .zip)needs: reuseif: ${{ !cancelled() && needs.reuse.outputs.run-id == '' }}+ permissions: # the attestation: a signed statement of what this run built+ contents: read+ id-token: write+ attestations: writeruns-on: ${{ vars.SF_RUNNER_WIN || 'windows-2022' }}steps:- uses: actions/checkout@v7@@ -408,3 +453,28 @@ jobs:path: |build/*.exebuild/*.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: 14diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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.1with: { 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 0fi- # 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+ fici=$(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; }donefi- 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: readactions: 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: writeuses: ./.github/workflows/packages.ymlwith: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* onlypermissions:contents: writeactions: 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.04environment: member-releasepermissions:@@ -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 scriptrun: |V=${TAG#v}diff --git a/CMakeLists.txt b/CMakeLists.txtindex 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.mdindex 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) whilethe 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 # resumescripts/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.## Runnersdiff --git a/scripts/merge-queue.sh b/scripts/merge-queue.shindex 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" ]; thenbash -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;;esacdiff --git a/scripts/release.sh b/scripts/release.shindex 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 pipefailREPO=islandmed/SculptForgeINSIDERS_REPO=islandmed/sculptforge-insiders # members' betas (release.yml publishes there with INSIDERS_REPO_TOKEN)+MEMBER_ENV=member-releaseAUTHOR_NAME=islandmed[email protected] # never a personal address in outside reposOMARCHY_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 versionshift-FROM=bump ONLY= STAGED=+FROM=bump ONLY= STAGED= MODE=promote MODE_FLAG=while [ $# -gt 0 ]; docase $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 ;;esacdone[[ " ${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$VTODAY=$(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"+ fiif [ -n "$PRE" ]; then # a beta: members only, through the private repository; nothing of the site, no packagesgh 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+ fiif [ -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 @@ PYok "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_mainpreflightlocal 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)"+ returnfi+ 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; filocal shasha=$(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)"+ ficonfirm "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" ] && breaksleep 10done- [ -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_readylocal nn=$(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.shindex 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 pipefailROOT=$(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 bumpgrep -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.sfuiquiet scripts/release.sh 9.0.0-beta.1 --only checkgrep -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 dogrep -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,EOFgrep -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 bumpgrep -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"], feedassert "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.pyindex 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 invisiblethere 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 PathTOKEN = "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: readjobs:+ locate:+ steps:+ - run: python3 tools/release/staged_run.py --sha "$sha"build:runs-on: ubuntu-24.04steps:- 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 distpublish-members:+ needs: [locate, build, verify, smoke]if: ${{ contains(needs.locate.outputs.tag, '-') }}environment: member-releasepermissions:contents: readsteps:+ - run: python3 tools/release/verify_staged.py dist sums --sums-only- name: Publishenv: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.shindex 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 pipefaildiff --git a/tools/release/staged_run.py b/tools/release/staged_run.pynew file mode 100755index 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.pynew file mode 100755index 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.pyindex 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"),