fix(ci): gate gh-pages commit on e2e-install, add x-skip-launch-check to ghostty

Structural fix: update-index.yml now runs e2e-install BEFORE committing to
gh-pages (prepare → e2e-install → commit-index). A failing launch check blocks
the index commit — the stale/broken index is never published to the remote.

Root cause fix: add x-skip-launch-check: true to ghostty manifest. GUI apps
that require Wayland/X11 exit 1 immediately in headless CI (gnome-49 has no
display). timeout 5 only produces exit 124 (PASS) if the app stays alive;
instant exit 1 is treated as failure. ghostty always exits 1 headlessly.

Documented in skills/app-gotchas.md under 'GUI apps — x-skip-launch-check'.

Assisted-by: Claude Sonnet 4.6 via OpenCode

Author: castrojo

.github/workflows/update-index.yml

@@ -3,35 +3,40 @@ name: Sync Flatpak Remote Index
 # Triggered after each "Build → Sign → Publish Flatpak OCI" run completes successfully.
 # Running as a separate workflow serialises all gh-pages pushes — no race
 # between concurrent app builds writing to the same branch.
+#
+# Job order enforces a strict gate:
+#   prepare → e2e-install → commit-index
+#
+# The gh-pages index is only committed AFTER e2e-install passes.
+# This prevents the index from pointing at a broken image that cannot be installed.
 
 on:
   workflow_run:
     workflows: ["Build → Sign → Publish Flatpak OCI"]
     types: [completed]
 
-# Top-level: deny all. This job only needs to write gh-pages and read packages.
+# Top-level: deny all. Jobs request only what they need.
 permissions: {}
 
 jobs:
-  update-index:
+  # ── Prepare: build updated index content and derive e2e matrix ────────────
+  # Downloads per-arch digest artifacts from the triggering build run,
+  # runs update-index.py against ghcr.io, and uploads the result as an artifact.
+  # Does NOT commit to gh-pages yet — that happens only after e2e-install passes.
+  prepare:
     if: >-
       github.event.workflow_run.conclusion == 'success' &&
       (github.event.workflow_run.event == 'push' ||
        github.event.workflow_run.event == 'merge_group' ||
        github.event.workflow_run.event == 'workflow_dispatch')
     runs-on: ubuntu-24.04
     permissions:
-      contents: write
+      contents: read
       packages: read
       actions: read
     outputs:
       matrix: ${{ steps.matrix.outputs.matrix }}
       has_entries: ${{ steps.matrix.outputs.has_entries }}
-    # Serialise gh-pages pushes — prevents race if two workflow_run events fire
-    # before the first has committed.
-    concurrency:
-      group: gh-pages-update
-      cancel-in-progress: false
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -85,18 +90,12 @@ jobs:
               --tags "latest"
           done
 
-      - name: Commit and push index
-        run: |
-          cd pages
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add index/static
-          if git diff --cached --quiet; then
-            echo "index unchanged, skipping commit"
-          else
-            git commit -m "chore(index): update from build ${{ github.event.workflow_run.run_number }} [skip ci]"
-            git push
-          fi
+      - name: Upload prepared index as artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: prepared-index-${{ github.run_id }}
+          path: pages/index/static
+          retention-days: 1
 
       - name: Build app+arch matrix from digest artifacts
         id: matrix
@@ -123,13 +122,15 @@ jobs:
           echo "matrix=${MATRIX}" >> "$GITHUB_OUTPUT"
           echo "has_entries=$(echo "${MATRIX}" | python3 -c 'import sys,json; d=json.load(sys.stdin); print("true" if d.get("include") else "false")')" >> "$GITHUB_OUTPUT"
 
-  # ── E2E install test (runs AFTER gh-pages index is fresh) ─────────────────
+  # ── E2E install test ──────────────────────────────────────────────────────
+  # Gate: runs BEFORE gh-pages is updated. The index is only committed if this passes.
+  # Installs from ghcr.io directly (images are live there regardless of gh-pages state).
+  #
   # Launch check: exit 0 = clean exit (PASS), exit 124 = timeout/headless GUI (PASS), other = FAIL
-  # Runs AFTER update-index so the install test always uses the freshly-pushed image from
-  # the live gh-pages index — eliminates the stale-digest class of bugs.
+  # Apps that cannot launch headless must set x-skip-launch-check: true in their manifest.
   e2e-install:
-    needs: [update-index]
-    if: needs.update-index.outputs.has_entries == 'true'
+    needs: [prepare]
+    if: needs.prepare.outputs.has_entries == 'true'
     runs-on: ${{ matrix.arch == 'aarch64' && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}
     permissions:
       packages: read
@@ -138,7 +139,7 @@ jobs:
       options: --privileged
     strategy:
       fail-fast: false
-      matrix: ${{ fromJson(needs.update-index.outputs.matrix) }}
+      matrix: ${{ fromJson(needs.prepare.outputs.matrix) }}
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
@@ -159,3 +160,46 @@ jobs:
         run: |
           APP_ID=$(just metadata '${{ matrix.app }}' app-id 2>/dev/null || echo "")
           [[ -n "${APP_ID}" ]] && flatpak uninstall --system --noninteractive "${APP_ID}" || true
+
+  # ── Commit index to gh-pages ──────────────────────────────────────────────
+  # Only runs after e2e-install passes — the gate is enforced by needs: [e2e-install].
+  # Downloads the prepared index artifact from the prepare job and commits it.
+  # Serialised via concurrency group to prevent races between concurrent builds.
+  commit-index:
+    needs: [prepare, e2e-install]
+    if: |
+      always() &&
+      needs.prepare.result == 'success' &&
+      needs.e2e-install.result == 'success'
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+      actions: read
+    concurrency:
+      group: gh-pages-update
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          ref: gh-pages
+
+      - name: Sync gh-pages before writing
+        run: git fetch origin gh-pages && git rebase origin/gh-pages
+
+      - name: Download prepared index artifact
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: prepared-index-${{ github.run_id }}
+          path: index/static
+
+      - name: Commit and push index
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add index/static
+          if git diff --cached --quiet; then
+            echo "index unchanged, skipping commit"
+          else
+            git commit -m "chore(index): update from build ${{ github.event.workflow_run.run_number }} [skip ci]"
+            git push
+          fi

flatpaks/ghostty/manifest.yaml

@@ -4,6 +4,7 @@ runtime-version: "49"
 sdk: org.gnome.Sdk
 default-branch: stable
 x-chunkah-max-layers: "8"
+x-skip-launch-check: true  # GUI app: requires Wayland/X11 display; exits 1 in headless CI
 command: ghostty
 finish-args:
   - --device=all  # Required: GPU access (Vulkan/Metal) and PTY device access for terminal

skills/app-gotchas.md

@@ -145,3 +145,18 @@ not appear in the installed Flatpak unless the upstream bundle already includes
 
 Applies to: **goose** (bundle-repack path). All other apps use `manifest.yaml`
 (flatpak-builder) and install metainfo directly.
+
+## GUI apps — x-skip-launch-check required
+
+Any app that requires a Wayland or X11 display will exit 1 immediately in headless CI (gnome-49 container has no display server). The `timeout 5 flatpak run` launch check treats exit 1 as FAIL, not as PASS. It only passes on exit 0 (clean self-exit) or exit 124 (timeout — app stayed running).
+
+**Symptom:** `e2e-install` fails with `WARNING: Gtk: Failed to open display` / `ERROR: <app-id> launch failed (exit 1)`.
+
+**Fix:** add `x-skip-launch-check: true` to the app's `manifest.yaml` (or `release.yaml`).
+
+Apps that need this flag: any GTK, Qt, Electron, or other GUI app that opens a window on startup. CLI apps and apps with `--version`/`--help` exit paths do not need it.
+
+**Structural safeguard:** `update-index.yml` runs `e2e-install` before committing to gh-pages (`prepare → e2e-install → commit-index`). A failing launch check blocks the index commit — the stale index is never published. But fixing `x-skip-launch-check` is still required; the structural gate is a last resort, not a substitute.
+
+**Known apps with this flag:**
+- `ghostty` — GTK4/Wayland terminal, exits 1 with "Failed to open display" in CI