Harden release integration gates

Author: bhack

.github/workflows/ci.yml

@@ -11,6 +11,10 @@ on:
         description: Run the experimental Flatpak PipeWire routing smoke test
         type: boolean
         default: false
+      live_ui_runtime_smoke:
+        description: Run the live GTK/AT-SPI/PipeWire smoke test
+        type: boolean
+        default: false
       smoke_only:
         description: Skip ordinary CI work and run only the requested experimental smoke job
         type: boolean
@@ -131,7 +135,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_gates.py|tools/release_preflight.py|tools/release_runtime_gate.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|tools/run_live_ui_runtime_smoke_ci.sh)
                 test=true
                 ;;
             esac
@@ -479,3 +483,55 @@ jobs:
           MINI_EQ_FLATPAK_INSTALL_REF: ${{ inputs.flatpak_runtime_install_ref }}
           MINI_EQ_FLATPAK_EXPECT_VERSION: ${{ inputs.flatpak_runtime_expected_version }}
         run: tools/run_flatpak_runtime_smoke_ci.sh
+
+  live-ui-runtime-smoke:
+    needs: changes
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.live_ui_runtime_smoke }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+
+    steps:
+      - name: Require change detection
+        if: ${{ needs.changes.result != 'success' }}
+        run: exit 1
+
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install live UI runtime dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            appstream \
+            at-spi2-core \
+            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 \
+            pipewire-bin \
+            pkg-config \
+            python3 \
+            python3-cairo \
+            python3-dev \
+            python3-gi \
+            python3-numpy \
+            python3-pip \
+            python3-pyatspi \
+            python3-setuptools \
+            python3-venv \
+            wireplumber
+
+      - name: Build source environment and run live UI smoke
+        run: tools/run_live_ui_runtime_smoke_ci.sh

.github/workflows/release.yml

@@ -47,6 +47,11 @@ on:
         required: true
         type: boolean
         default: false
+      force_live_ui_runtime_smoke:
+        description: Run the live GTK/AT-SPI/PipeWire smoke even when app-sensitive files did not change.
+        required: true
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -139,12 +144,55 @@ jobs:
           fi
 
           python3 tools/release_runtime_gate.py \
+            --scope flatpak \
             --tag "$TAG_NAME" \
             --release-requested "$release_requested" \
             --force "$FORCE_FLATPAK_RUNTIME_SMOKE" \
             --github-output "$GITHUB_OUTPUT" \
             --github-summary "$GITHUB_STEP_SUMMARY"
 
+  live-ui-risk:
+    name: Detect live UI 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 app and UI runtime-sensitive changes
+        id: detect
+        env:
+          CREATE_GITHUB_RELEASE: ${{ inputs.create_github_release }}
+          DRY_RUN: ${{ inputs.dry_run }}
+          FORCE_LIVE_UI_RUNTIME_SMOKE: ${{ inputs.force_live_ui_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 \
+            --scope live-ui \
+            --tag "$TAG_NAME" \
+            --release-requested "$release_requested" \
+            --force "$FORCE_LIVE_UI_RUNTIME_SMOKE" \
+            --github-output "$GITHUB_OUTPUT" \
+            --github-summary "$GITHUB_STEP_SUMMARY"
+
   flatpak-runtime-smoke:
     name: Flatpak routing runtime smoke
     needs: runtime-risk
@@ -172,6 +220,57 @@ jobs:
       - name: Build and run Flatpak routing runtime smoke
         run: tools/run_flatpak_runtime_smoke_ci.sh
 
+  live-ui-runtime-smoke:
+    name: Live UI runtime smoke
+    needs: live-ui-risk
+    if: ${{ needs['live-ui-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 live UI runtime dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            appstream \
+            at-spi2-core \
+            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 \
+            pipewire-bin \
+            pkg-config \
+            python3 \
+            python3-cairo \
+            python3-dev \
+            python3-gi \
+            python3-numpy \
+            python3-pip \
+            python3-pyatspi \
+            python3-setuptools \
+            python3-venv \
+            wireplumber
+
+      - name: Build source environment and run live UI smoke
+        run: tools/run_live_ui_runtime_smoke_ci.sh
+
   runtime-gate:
     name: Require runtime smoke gate
     needs:
@@ -199,6 +298,33 @@ jobs:
             echo "Flatpak routing runtime smoke was not required for this dispatch."
           fi
 
+  live-ui-gate:
+    name: Require live UI smoke gate
+    needs:
+      - live-ui-risk
+      - live-ui-runtime-smoke
+    if: ${{ always() }}
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Require live-ui-risk job
+        if: ${{ needs['live-ui-risk'].result != 'success' }}
+        run: exit 1
+
+      - name: Require live UI smoke
+        if: ${{ needs['live-ui-risk'].outputs.required == 'true' && needs['live-ui-runtime-smoke'].result != 'success' }}
+        run: |
+          echo "::error::Live GTK/AT-SPI/PipeWire runtime smoke is required for this release and did not pass."
+          exit 1
+
+      - name: Confirm live UI gate
+        run: |
+          if [ "${{ needs['live-ui-risk'].outputs.required }}" = "true" ]; then
+            echo "Required live UI runtime smoke passed."
+          else
+            echo "Live UI runtime smoke was not required for this dispatch."
+          fi
+
   preflight:
     name: Release preflight
     needs: validate-inputs
@@ -252,6 +378,7 @@ jobs:
     needs:
       - validate-inputs
       - runtime-gate
+      - live-ui-gate
       - preflight
     runs-on: ubuntu-24.04
 

AGENTS.md

@@ -87,6 +87,10 @@ PipeWire/WirePlumber graph with synthetic playback and AT-SPI UI driving:
 MINI_EQ_RUN_LIVE_UI=1 .venv/bin/python -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 ```
 
+The live UI smoke is opt-in locally because it needs nested GNOME Shell,
+AT-SPI, PipeWire, and WirePlumber, but it is a blocking `Release` workflow gate
+for app-sensitive publish dispatches.
+
 For manual GNOME Shell extension testing against an installed Flatpak build,
 run the nested devkit smoke. It loads the extension from this checkout and
 launches the installed Flatpak app in the same isolated nested display and

docs/development.md

@@ -149,6 +149,11 @@ python3 tools/check_live_ui_runtime.py --timeout 35 --cycles 1
 MINI_EQ_RUN_LIVE_UI=1 python3 -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 ```
 
+These integration smokes are intentionally separate from the default pytest
+suite because they require nested GNOME Shell, AT-SPI services, PipeWire, and
+WirePlumber. The release workflow promotes the live UI smoke to a blocking gate
+for app-sensitive publish dispatches.
+
 ## Local Flatpak Build
 
 The Flatpak manifest uses the GNOME runtime. It does not ship a full PipeWire

docs/release.md

@@ -14,6 +14,10 @@ Run the narrowest gate that covers the release risk:
 - **Always:** version metadata, release preflight, GitHub release dry run or
   release workflow, TestPyPI install validation, PyPI publish, post-publish
   verification, then Flathub stable PR.
+- **When application code, UI code, or runtime-sensitive packaging changed:**
+  live GTK/AT-SPI/PipeWire smoke. Public release workflow dispatches run this
+  as a blocking job for app-sensitive changes before building publishable
+  artifacts.
 - **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. Public release
@@ -73,6 +77,22 @@ on widget internals when a unit test can cover the state transition directly.
 When in doubt, add a small state-level unit test first, then one AT-SPI smoke
 assertion for the visible contract.
 
+The automated release gates are confidence checks, not a proof that every user
+graph behaves correctly. Treat their claims narrowly:
+
+- Unit and seam tests verify deterministic model, routing, metadata, and UI
+  state transitions.
+- The release preflight verifies source cleanliness, package build/install,
+  dependency importability, metadata, and the full default pytest suite.
+- The Flatpak routing smoke verifies the installed Flatpak can route and
+  restore a synthetic stream in an isolated PipeWire/WirePlumber graph.
+- The live UI smoke verifies the real GTK app can be driven through AT-SPI
+  while PipeWire routing, output following, monitor capture, preset reset, and
+  shutdown are exercised.
+- Manual real-session audio testing is still required for changes that depend
+  on host devices, real music playback, WirePlumber policy, or analyzer
+  behavior users can perceive.
+
 ## Prepare Version
 
 Set the release version once for the shell session:
@@ -192,21 +212,26 @@ run the app interactively with real music before release. Exercise
 enable/disable, output switching, preset changes, analyzer display, shutdown,
 and stream restoration against the actual desktop audio graph.
 
-Before the manual real-music pass, run the opt-in live UI smoke. It starts a
-private PipeWire/WirePlumber graph, synthetic playback, nested headless GNOME
-Shell, the real Mini EQ GTK process, and AT-SPI UI controls:
+Before the manual real-music pass, run the live UI smoke. It starts a private
+PipeWire/WirePlumber graph, synthetic playback, nested headless GNOME Shell,
+the real Mini EQ GTK process, and AT-SPI UI controls:
 
 ```bash
 python3 tools/check_live_ui_runtime.py --timeout 35 --cycles 1
 MINI_EQ_RUN_LIVE_UI=1 python3 -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 ```
 
+The `Release` workflow runs this live UI smoke as a blocking job for app and UI
+runtime-sensitive publish dispatches. The pytest wrapper remains opt-in for
+local development so ordinary unit test runs stay fast and do not require
+nested GNOME Shell or AT-SPI services.
+
 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. 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.
+copy of the Flatpak routing smoke and live UI smoke gates for public TestPyPI,
+PyPI, and GitHub release dispatches.
 
 ## Package Channels
 

tests/test_github_workflows.py

@@ -32,6 +32,19 @@ def test_release_workflow_blocks_publish_on_runtime_gate() -> None:
     assert "runtime-gate" in release_yml.partition("build:")[2].partition("runs-on:")[0]
 
 
+def test_release_workflow_blocks_publish_on_live_ui_gate() -> None:
+    release_yml = workflow_text("release.yml")
+
+    assert "force_live_ui_runtime_smoke" in release_yml
+    assert "--scope live-ui" in release_yml
+    assert "live-ui-risk:" in release_yml
+    assert "live-ui-runtime-smoke:" in release_yml
+    assert "live-ui-gate:" in release_yml
+    assert "tools/run_live_ui_runtime_smoke_ci.sh" in release_yml
+    assert "needs['live-ui-runtime-smoke'].result != 'success'" in release_yml
+    assert "live-ui-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")
 
@@ -46,3 +59,5 @@ def test_ci_scope_treats_release_workflow_and_release_gate_tools_as_tested_chang
     assert ".github/workflows/*.yml)" in ci_yml
     assert "tools/release_gates.py" in ci_yml
     assert "tools/release_runtime_gate.py" in ci_yml
+    assert "live_ui_runtime_smoke" in ci_yml
+    assert "tools/run_live_ui_runtime_smoke_ci.sh" in ci_yml