Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Add DESKTOP_RELEASE_REQUIRED_PLATFORMS escape valve (transiently broken platform) (#3188)

mike-inkeepee102a052977
diff --git a/.github/scripts/build-smoke-alert-payload.test.mjs b/.github/scripts/build-smoke-alert-payload.test.mjs
index 46f488441..d2ab3e53a 100644
--- a/.github/scripts/build-smoke-alert-payload.test.mjs
+++ b/.github/scripts/build-smoke-alert-payload.test.mjs
@@ -130,15 +130,17 @@ describe('parseArgs', () => {
});
describe('workflow wiring', () => {
- test('the alert job is failure-conditioned, not success-conditioned', () => {
- // Under the fan-out topology the failure() lives at the ALERT JOB level
- // (a failed packaging job skips finalize, so a failure()-step inside it
- // could never fire); the step keeps only the stable-only channel gate.
+ test('the alert job fires on a blocked release, never on success', () => {
+ // The blocked-release predicate lives at the ALERT JOB level (a failed
+ // packaging job skips finalize, so a failure()-step inside finalize
+ // could never fire). It keys on finalize's result rather than bare
+ // failure() so a degraded-mode cut that still publishes does not page;
+ // the step keeps only the stable-only channel gate.
const alertJob = desktopRelease.slice(
desktopRelease.indexOf('\n alert:'),
desktopRelease.indexOf('- name: Alert on a blocked release'),
);
- expect(alertJob).toContain('if: failure()');
+ expect(alertJob).toContain("needs.finalize.result != 'success'");
expect(alertJob).not.toContain('if: success()');
expect(alertStep()).not.toContain('if: success()');
});
diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjs
index e95701518..f83d7bcc9 100644
--- a/.github/scripts/release-cascade-shape.test.mjs
+++ b/.github/scripts/release-cascade-shape.test.mjs
@@ -75,18 +75,28 @@ describe('the stable gate is upstream of everything that ships', () => {
expect(smoke).toBeLessThan(indexOfStep(names, 'Announce stable release to Discord'));
});
- test('nothing downstream of the gate opts out of the implicit success() guard', () => {
- // A downstream step carrying `if: always()` would run even after the gate
- // refused — which is exactly how a gate stops gating.
+ test('no shipping STEP opts out of the implicit success() guard', () => {
+ // A downstream step carrying `if: always()` / `!cancelled()` would run
+ // even after the gate refused — which is exactly how a gate stops
+ // gating. JOB-level `!cancelled()` predicates are a different animal:
+ // the required-platforms valve needs them, and each one re-asserts the
+ // success of everything it actually gates on — they are pinned exactly
+ // in the fan-in DAG describe below. Step-level ifs sit at 8-space
+ // indentation; job-level at 4.
const afterGate = desktopRelease.slice(
desktopRelease.indexOf('- name: Smoke the packaged DMG'),
);
- const shipping = afterGate.slice(
- 0,
- afterGate.indexOf('- name: Alert on a blocked release'), // failure-conditioned by design
- );
- expect(shipping).not.toContain('if: always()');
- expect(shipping).not.toContain('!cancelled()');
+ const shipping = afterGate.slice(0, afterGate.indexOf('- name: Alert on a blocked release'));
+ const stepIfs = [...shipping.matchAll(/^ {8}if: (.+)$/gm)].map((m) => m[1].trim());
+ expect(stepIfs.length).toBeGreaterThan(0);
+ for (const condition of stepIfs) {
+ expect(condition, `step-level if opts out of success(): ${condition}`).not.toContain(
+ 'always()',
+ );
+ expect(condition, `step-level if opts out of success(): ${condition}`).not.toContain(
+ '!cancelled()',
+ );
+ }
});
test('every shipping step with an explicit if: spells success() itself', () => {
@@ -101,13 +111,13 @@ describe('the stable gate is upstream of everything that ships', () => {
desktopRelease.indexOf('- name: Smoke the packaged DMG'),
);
const shipping = afterGate.slice(0, afterGate.indexOf('- name: Alert on a blocked release'));
- const conditions = [...shipping.matchAll(/^\s*if: (.+)$/gm)].map((m) => m[1].trim());
- // Two conditions in this span are gates, not shipping: the smoke gate's
- // own channel scope, and the alert JOB's failure() header (the span ends
- // at the alert step's name, which sits after its job header). Everything
- // else ships and must be success()-gated.
+ // Step-level ifs only (8-space indent) — job-level predicates are the
+ // required-platforms valve, pinned exactly in the fan-in DAG describe.
+ const conditions = [...shipping.matchAll(/^ {8}if: (.+)$/gm)].map((m) => m[1].trim());
+ // One condition in this span is a gate, not shipping: the smoke gate's
+ // own channel scope. Everything else ships and must be success()-gated.
const shippingConditions = conditions.filter(
- (c) => c !== "steps.channel.outputs.channel == 'latest'" && c !== 'failure()',
+ (c) => c !== "steps.channel.outputs.channel == 'latest'",
);
expect(shippingConditions.length).toBeGreaterThan(0);
for (const condition of shippingConditions) {
@@ -180,6 +190,45 @@ describe('the fan-in publication DAG gates every platform', () => {
expect(assert).toBeLessThan(upload);
expect(upload).toBeLessThan(verify);
});
+
+ test('the required-platforms valve gates exactly what it may skip — and mac has no bypass', () => {
+ // publish-assets may proceed past a FAILED platform only when that
+ // platform is absent from the required set; the mac result is asserted
+ // unconditionally (the stable smoke gate rides on build-macos), and
+ // prepare refuses a required-set that omits mac at the variable level.
+ const pa = desktopRelease.slice(
+ desktopRelease.indexOf('\n publish-assets:'),
+ desktopRelease.indexOf('\n finalize:'),
+ );
+ expect(pa).toContain("needs.build-macos.result == 'success'");
+ expect(pa).toContain(
+ "needs.build-windows.result == 'success' || !contains(needs.prepare.outputs.required, 'windows')",
+ );
+ expect(pa).toContain(
+ "needs.build-linux.result == 'success' || !contains(needs.prepare.outputs.required, 'linux')",
+ );
+ expect(pa).not.toContain("contains(needs.prepare.outputs.required, 'mac')");
+ const fin = desktopRelease.slice(
+ desktopRelease.indexOf('\n finalize:'),
+ desktopRelease.indexOf('\n alert:'),
+ );
+ expect(fin).toContain("needs.publish-assets.result == 'success'");
+ expect(fin).toContain("needs.build-macos.result == 'success'");
+ expect(desktopRelease).toContain("must include 'mac'");
+ });
+
+ test('the alert pages on a blocked RELEASE, not on any failed job', () => {
+ // Under a degraded required-set a non-required platform can fail while
+ // the release still publishes — paging on that would train readers to
+ // ignore the alert. finalize != success covers every blocked shape
+ // transitively.
+ const alertJob = desktopRelease.slice(
+ desktopRelease.indexOf('\n alert:'),
+ desktopRelease.indexOf('- name: Alert on a blocked release'),
+ );
+ expect(alertJob).toContain("needs.finalize.result != 'success'");
+ expect(alertJob).not.toContain('if: failure()');
+ });
});
describe('the moved dispatch keeps the contract release.yml consumes', () => {
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index 0eaebdeca..006b60adc 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -67,6 +67,12 @@ name: Desktop release
# GITHUB_TOKEN (auto-provided, contents:write scope) — used as GH_TOKEN
# for the fan-in `gh release upload` + the finalize/alert steps.
#
+# Operator escape valve: the DESKTOP_RELEASE_REQUIRED_PLATFORMS repo variable
+# (unset = mac,windows,linux) lets a TRANSIENTLY broken platform stop blocking
+# publication — see the "Resolve required platforms" step in prepare for the
+# full contract (mac can never be dropped; healthy non-required platforms
+# still ship; degraded cuts warn loudly; remove the variable once fixed).
+#
# Unsigned mode is explicitly REJECTED on macOS AND Windows. On macOS,
# auto-update refuses unsigned upgrades (Squirrel.Mac signature-verifies every
# update against the installed app's cert). On Windows nothing technically
@@ -150,6 +156,7 @@ jobs:
outputs:
channel: ${{ steps.channel.outputs.channel }}
version: ${{ steps.channel.outputs.version }}
+ required: ${{ steps.required.outputs.required }}
steps:
- name: Link to triggering run
# Back-link: promote-stable forwards its run URL in
@@ -231,6 +238,45 @@ jobs:
echo "::notice::Building LATEST channel from tag $RELEASE_TAG"
fi
+ # The operator escape valve for a TRANSIENTLY broken platform: the
+ # `DESKTOP_RELEASE_REQUIRED_PLATFORMS` repo variable (comma-separated
+ # subset of mac,windows,linux; unset = all three — fail-closed) names
+ # the platforms whose build failure blocks publication. Non-required
+ # platforms still BUILD every cut, and when their build succeeds their
+ # assets still ship — requiredness only changes what can block. `mac`
+ # can never be dropped: the stable DMG smoke gate (FR5b) and the npm
+ # dispatch hang off build-macos, so a mac-less release would ship
+ # unsmoked. A client on a platform missing from a cut simply 404s that
+ # cut's channel manifest and retries next interval — the same benign
+ # behavior as before that platform shipped at all. REMOVE the variable
+ # once the platform is fixed; every degraded cut warns loudly so a
+ # forgotten override stays visible.
+ - name: Resolve required platforms
+ id: required
+ env:
+ RAW: ${{ vars.DESKTOP_RELEASE_REQUIRED_PLATFORMS }}
+ run: |
+ set -euo pipefail
+ REQUIRED="${RAW:-mac,windows,linux}"
+ # Normalize: strip spaces, lowercase.
+ REQUIRED="$(tr -d ' ' <<<"$REQUIRED" | tr '[:upper:]' '[:lower:]')"
+ IFS=',' read -ra toks <<<"$REQUIRED"
+ for t in "${toks[@]}"; do
+ case "$t" in
+ mac|windows|linux) ;;
+ *) echo "::error::DESKTOP_RELEASE_REQUIRED_PLATFORMS contains unknown platform '$t' (allowed: mac, windows, linux)"; exit 1 ;;
+ esac
+ done
+ if ! grep -q "mac" <<<"$REQUIRED"; then
+ echo "::error::DESKTOP_RELEASE_REQUIRED_PLATFORMS must include 'mac' — the stable smoke gate and npm dispatch hang off the mac build, so a mac-less release would ship unverified."
+ exit 1
+ fi
+ echo "required=$REQUIRED" >> "$GITHUB_OUTPUT"
+ if [[ "$REQUIRED" != *windows* || "$REQUIRED" != *linux* ]]; then
+ echo "::warning::DEGRADED RELEASE MODE: required platforms = ${REQUIRED}. A non-required platform's build failure will NOT block publication. Remove the DESKTOP_RELEASE_REQUIRED_PLATFORMS variable once the platform is fixed."
+ echo "### ⚠️ Degraded release mode: required = ${REQUIRED}" >> "$GITHUB_STEP_SUMMARY"
+ fi
+
# The manual recovery path uploads to an existing Release; the cascade
# path's Release was just created by the upstream. Either way, failing
# here — before three platforms spend 30+ runner-minutes building — beats
@@ -1214,6 +1260,19 @@ jobs:
# 30-minute signed build; `--clobber` makes the retry idempotent.
publish-assets:
needs: [prepare, build-macos, build-windows, build-linux]
+ # Runs when every REQUIRED platform built (see prepare's "Resolve
+ # required platforms"). `!cancelled()` is load-bearing: with a
+ # non-required platform's job failed, the default success()-of-all-needs
+ # would skip this job and block the release the override exists to save.
+ # This predicate is only the fast gate — the inventory assert below is
+ # the deterministic backstop (a required platform's missing assets fail
+ # the must-have check even if this expression were wrong).
+ if: >-
+ !cancelled() &&
+ needs.prepare.result == 'success' &&
+ needs.build-macos.result == 'success' &&
+ (needs.build-windows.result == 'success' || !contains(needs.prepare.outputs.required, 'windows')) &&
+ (needs.build-linux.result == 'success' || !contains(needs.prepare.outputs.required, 'linux'))
runs-on: ubuntu-latest
# Sized to the upload retry envelope: 3 bounded 300s attempts + backoffs
# (see the upload step) plus download/verify overhead.
@@ -1232,6 +1291,12 @@ jobs:
RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}
CHANNEL: ${{ needs.prepare.outputs.channel }}
VERSION: ${{ needs.prepare.outputs.version }}
+ REQUIRED: ${{ needs.prepare.outputs.required }}
+ # A platform's asset group joins the expected inventory when it is
+ # required OR its build succeeded anyway (a healthy non-required
+ # platform still ships).
+ WINDOWS_BUILT: ${{ needs.build-windows.result == 'success' }}
+ LINUX_BUILT: ${{ needs.build-linux.result == 'success' }}
steps:
- name: Download all platform release assets
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v5.0.0
@@ -1256,6 +1321,10 @@ jobs:
- name: Define the expected asset inventory
run: |
set -euo pipefail
+ # Per-platform groups. mac is unconditional (always required); the
+ # windows/linux groups join when the platform is required OR its
+ # build succeeded anyway — so a degraded cut still ships every
+ # healthy platform, and the no-extras check below stays exact.
{
echo "EXPECTED_ASSETS<<OK_INVENTORY_EOF"
echo "OpenKnowledge-arm64.dmg"
@@ -1263,15 +1332,22 @@ jobs:
echo "OpenKnowledge-${VERSION}-arm64-mac.zip"
echo "OpenKnowledge-${VERSION}-arm64-mac.zip.blockmap"
echo "${CHANNEL}-mac.yml"
- echo "OpenKnowledge-Setup-x64.exe"
- echo "OpenKnowledge-Setup-arm64.exe"
- echo "${CHANNEL}.yml"
- echo "OpenKnowledge-amd64.deb"
- echo "OpenKnowledge-arm64.deb"
- echo "OpenKnowledge-x86_64.rpm"
- echo "OpenKnowledge-aarch64.rpm"
- echo "${CHANNEL}-linux.yml"
- echo "${CHANNEL}-linux-arm64.yml"
+ if [[ "$REQUIRED" == *windows* || "$WINDOWS_BUILT" == "true" ]]; then
+ echo "OpenKnowledge-Setup-x64.exe"
+ echo "OpenKnowledge-Setup-arm64.exe"
+ echo "${CHANNEL}.yml"
+ fi
+ if [[ "$REQUIRED" == *linux* || "$LINUX_BUILT" == "true" ]]; then
+ echo "OpenKnowledge-amd64.deb"
+ echo "OpenKnowledge-arm64.deb"
+ echo "OpenKnowledge-x86_64.rpm"
+ echo "OpenKnowledge-aarch64.rpm"
+ echo "${CHANNEL}-linux.yml"
+ echo "${CHANNEL}-linux-arm64.yml"
+ fi
+ # GITHUB_ENV's multiline syntax REQUIRES the closing delimiter
+ # line — without it the runner rejects the whole env file.
+ echo "OK_INVENTORY_EOF"
} >> "$GITHUB_ENV"
- name: Assert the complete cross-platform inventory
@@ -1371,6 +1447,14 @@ jobs:
# that).
finalize:
needs: [prepare, build-macos, publish-assets]
+ # `!cancelled()` for the same reason as publish-assets: under a degraded
+ # required-set, a non-required platform's failure elsewhere in the run
+ # must not skip finalization. The explicit success checks keep the real
+ # gates: verified inventory (publish-assets) + the smoke-bearing mac job.
+ if: >-
+ !cancelled() &&
+ needs.publish-assets.result == 'success' &&
+ needs.build-macos.result == 'success'
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
@@ -1639,11 +1723,14 @@ jobs:
# SKIPS finalize entirely — skipped steps can't alert.
alert:
needs: [prepare, build-macos, build-windows, build-linux, publish-assets, finalize]
- # Job-level failure() is true when any job in `needs` failed. prepare
- # failing before channel detection leaves the channel output empty; the
- # steps below treat that as "not stable" (FR5c skips, STUCK-DRAFT still
- # logs).
- if: failure()
+ # "The release did not publish" — not "some job failed": under a degraded
+ # required-set a non-required platform can fail while the release still
+ # publishes, and paging on that would train readers to ignore the alert.
+ # finalize != success covers every blocked shape transitively (prepare,
+ # a required build, publish-assets, or finalize itself). prepare failing
+ # before channel detection leaves the channel output empty; the steps
+ # below treat that as "not stable" (FR5c skips, STUCK-DRAFT still logs).
+ if: ${{ !cancelled() && needs.finalize.result != 'success' }}
runs-on: ubuntu-latest
timeout-minutes: 10
permissions: