Harden release runtime gates

Author: bhack

.github/workflows/ci.yml

@@ -121,7 +121,7 @@ jobs:
 
           while IFS= read -r path; do
             case "$path" in
-              .github/workflows/ci.yml)
+              .github/workflows/*.yml)
                 test=true
                 tooling=true
                 pwg=true
@@ -131,7 +131,7 @@ jobs:
               README.md|pyproject.toml|MANIFEST.in|src/*|tests/*|data/*|extensions/*)
                 test=true
                 ;;
-              tools/check_gnome_shell_extension.py|tools/pack_gnome_shell_extension.sh|tools/prepare_release.py|tools/release_status.py)
+              tools/check_gnome_shell_extension.py|tools/pack_gnome_shell_extension.sh|tools/prepare_release.py|tools/release_gates.py|tools/release_preflight.py|tools/release_runtime_gate.py|tools/release_status.py)
                 test=true
                 ;;
             esac
@@ -149,13 +149,13 @@ jobs:
             esac
 
             case "$path" in
-              .github/workflows/ci.yml|tools/check_pipewire_gobject.py|src/mini_eq/pipewire_backend.py|src/mini_eq/analyzer.py)
+              .github/workflows/*.yml|tools/check_pipewire_gobject.py|tools/release_gates.py|tools/release_runtime_gate.py|src/mini_eq/pipewire_backend.py|src/mini_eq/analyzer.py)
                 pwg=true
                 ;;
             esac
 
             case "$path" in
-              .github/workflows/ci.yml|io.github.bhack.mini-eq.yaml|python3-dependencies.yaml|flatpak/*|src/*|data/*|pyproject.toml|MANIFEST.in|tools/check_pipewire_gobject.py)
+              .github/workflows/*.yml|io.github.bhack.mini-eq.yaml|python3-dependencies.yaml|flatpak/*|src/*|data/*|pyproject.toml|MANIFEST.in|tools/check_pipewire_gobject.py|tools/release_gates.py|tools/release_runtime_gate.py)
                 flatpak=true
                 ;;
             esac

.github/workflows/release.yml

@@ -42,6 +42,11 @@ on:
         required: true
         type: boolean
         default: false
+      force_flatpak_runtime_smoke:
+        description: Run the Flatpak routing runtime smoke even when runtime-sensitive files did not change.
+        required: true
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -99,9 +104,155 @@ jobs:
             echo "::warning::publishing PyPI without creating the GitHub release uses a separate build from release assets"
           fi
 
+  runtime-risk:
+    name: Detect runtime smoke gate
+    needs: validate-inputs
+    runs-on: ubuntu-24.04
+
+    outputs:
+      required: ${{ steps.detect.outputs.required }}
+      base_tag: ${{ steps.detect.outputs.base_tag }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.target }}
+          fetch-depth: 0
+
+      - name: Detect runtime-sensitive changes
+        id: detect
+        env:
+          CREATE_GITHUB_RELEASE: ${{ inputs.create_github_release }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          FORCE_FLATPAK_RUNTIME_SMOKE: ${{ inputs.force_flatpak_runtime_smoke }}
+          PUBLISH_PYPI: ${{ inputs.publish_pypi }}
+          PUBLISH_TESTPYPI: ${{ inputs.publish_testpypi }}
+          TAG_NAME: ${{ inputs.tag_name }}
+        run: |
+          set -euo pipefail
+
+          release_requested=false
+          if { [ "$CREATE_GITHUB_RELEASE" = "true" ] || [ "$PUBLISH_TESTPYPI" = "true" ] || [ "$PUBLISH_PYPI" = "true" ]; } \
+            && [ "$DRY_RUN" = "false" ]; then
+            release_requested=true
+          fi
+
+          python3 tools/release_runtime_gate.py \
+            --tag "$TAG_NAME" \
+            --release-requested "$release_requested" \
+            --force "$FORCE_FLATPAK_RUNTIME_SMOKE" \
+            --github-output "$GITHUB_OUTPUT" \
+            --github-summary "$GITHUB_STEP_SUMMARY"
+
+  flatpak-runtime-smoke:
+    name: Flatpak routing runtime smoke
+    needs: runtime-risk
+    if: ${{ needs['runtime-risk'].outputs.required == 'true' }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.target }}
+
+      - name: Install Flatpak and PipeWire test dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            dbus-user-session \
+            flatpak \
+            jq \
+            pipewire \
+            pipewire-bin \
+            wireplumber
+
+      - name: Build and run Flatpak routing runtime smoke
+        run: tools/run_flatpak_runtime_smoke_ci.sh
+
+  runtime-gate:
+    name: Require runtime smoke gate
+    needs:
+      - runtime-risk
+      - flatpak-runtime-smoke
+    if: ${{ always() }}
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Require runtime-risk job
+        if: ${{ needs['runtime-risk'].result != 'success' }}
+        run: exit 1
+
+      - name: Require Flatpak routing smoke
+        if: ${{ needs['runtime-risk'].outputs.required == 'true' && needs['flatpak-runtime-smoke'].result != 'success' }}
+        run: |
+          echo "::error::Flatpak routing runtime smoke is required for this release and did not pass."
+          exit 1
+
+      - name: Confirm runtime gate
+        run: |
+          if [ "${{ needs['runtime-risk'].outputs.required }}" = "true" ]; then
+            echo "Required Flatpak routing runtime smoke passed."
+          else
+            echo "Flatpak routing runtime smoke was not required for this dispatch."
+          fi
+
+  preflight:
+    name: Release preflight
+    needs: validate-inputs
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.target }}
+          fetch-depth: 0
+
+      - name: Install release preflight dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            appstream \
+            build-essential \
+            dbus-user-session \
+            desktop-file-utils \
+            gir1.2-adw-1 \
+            gir1.2-gtk-4.0 \
+            git \
+            gnome-shell \
+            gobject-introspection \
+            libebur128-1 \
+            libgirepository1.0-dev \
+            libglib2.0-dev \
+            libpipewire-0.3-dev \
+            libspa-0.2-modules \
+            meson \
+            ninja-build \
+            pipewire \
+            pkg-config \
+            python3 \
+            python3-cairo \
+            python3-dev \
+            python3-gi \
+            python3-numpy \
+            python3-pip \
+            python3-setuptools \
+            python3-venv \
+            wireplumber
+
+      - name: Run release preflight
+        run: docker/run-release-preflight.sh
+
   build:
     name: Build release artifacts
-    needs: validate-inputs
+    needs:
+      - validate-inputs
+      - runtime-gate
+      - preflight
     runs-on: ubuntu-24.04
 
     steps:

docs/release.md

@@ -16,7 +16,9 @@ Run the narrowest gate that covers the release risk:
   verification, then Flathub stable PR.
 - **When PipeWire, routing, analyzer, Flatpak permissions, runtime dependencies,
   or shutdown changed:** local Flatpak install, Flatpak runtime smoke, and
-  interactive real-music testing before merge or release.
+  interactive real-music testing before merge or release. Public release
+  workflow dispatches also run the isolated Flatpak routing smoke as a blocking
+  job when runtime-sensitive files changed since the previous release tag.
 - **When background mode, Start at Login, hidden-window lifecycle, or Shell
   control changed:** one clean-permission Flatpak portal smoke in a real GNOME
   session.
@@ -201,7 +203,10 @@ MINI_EQ_RUN_LIVE_UI=1 python3 -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 
 There is an optional hosted Flatpak runtime smoke path in the `CI` workflow.
 Use it as extra signal or for smoke-harness work; keep the local runtime smoke
-as the release check when app/runtime routing behavior changed.
+as the release check when app/runtime routing behavior changed. The `Release`
+workflow also runs release preflight as a blocking job and has its own blocking
+copy of the Flatpak routing smoke gate for public TestPyPI, PyPI, and GitHub
+release dispatches.
 
 ## Package Channels
 

tests/test_check_flatpak_runtime.py

@@ -21,3 +21,19 @@ def test_flatpak_runtime_smoke_accepts_flathub_test_refs(app_ref: str) -> None:
         app_ref,
         "--check-deps",
     ]
+
+
+def test_flatpak_runtime_smoke_includes_extra_flatpak_run_args(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(
+        "MINI_EQ_FLATPAK_RUN_ARGS",
+        "--filesystem=/tmp/mini-eq-runtime/pipewire-0:ro --env=PIPEWIRE_RUNTIME_DIR=/tmp/mini-eq-runtime",
+    )
+
+    assert check_flatpak_runtime.flatpak_run_command("io.github.bhack.mini-eq//master", "--check-deps") == [
+        "flatpak",
+        "run",
+        "--filesystem=/tmp/mini-eq-runtime/pipewire-0:ro",
+        "--env=PIPEWIRE_RUNTIME_DIR=/tmp/mini-eq-runtime",
+        "io.github.bhack.mini-eq//master",
+        "--check-deps",
+    ]

tests/test_github_workflows.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def workflow_text(path: str) -> str:
+    return (ROOT / ".github/workflows" / path).read_text(encoding="utf-8")
+
+
+def test_workflow_expressions_use_bracket_access_for_hyphenated_needs() -> None:
+    offenders: list[str] = []
+    pattern = re.compile(r"needs\.[A-Za-z0-9_]*-[A-Za-z0-9_-]*")
+
+    for workflow in (ROOT / ".github/workflows").glob("*.yml"):
+        for line_number, line in enumerate(workflow.read_text(encoding="utf-8").splitlines(), start=1):
+            if pattern.search(line):
+                offenders.append(f"{workflow.relative_to(ROOT)}:{line_number}:{line.strip()}")
+
+    assert offenders == []
+
+
+def test_release_workflow_blocks_publish_on_runtime_gate() -> None:
+    release_yml = workflow_text("release.yml")
+
+    assert "tools/release_runtime_gate.py" in release_yml
+    assert "flatpak-runtime-smoke:" in release_yml
+    assert "runtime-gate:" in release_yml
+    assert "needs['flatpak-runtime-smoke'].result != 'success'" in release_yml
+    assert "runtime-gate" in release_yml.partition("build:")[2].partition("runs-on:")[0]
+
+
+def test_release_workflow_blocks_publish_on_release_preflight() -> None:
+    release_yml = workflow_text("release.yml")
+
+    assert "preflight:" in release_yml
+    assert "docker/run-release-preflight.sh" in release_yml
+    assert "preflight" in release_yml.partition("build:")[2].partition("runs-on:")[0]
+
+
+def test_ci_scope_treats_release_workflow_and_release_gate_tools_as_tested_changes() -> None:
+    ci_yml = workflow_text("ci.yml")
+
+    assert ".github/workflows/*.yml)" in ci_yml
+    assert "tools/release_gates.py" in ci_yml
+    assert "tools/release_runtime_gate.py" in ci_yml