Fix Flatpak branch stability for updates

Author: leumor

.github/workflows/build-cryptad-flatpak.yml

@@ -28,6 +28,9 @@ on:
         description: "Resolved version used for this build"
         value: ${{ jobs.build.outputs.version }}
 
+env:
+  FLATPAK_BRANCH: stable
+
 jobs:
   build:
     runs-on: ${{ matrix.runner }}
@@ -89,12 +92,12 @@ jobs:
             __VERSION__=${{ steps.prepare.outputs.version }}
           preview_lines: "120"
 
-      - name: Install Flatpak tooling and runtimes
+      - name: Install Flatpak tooling, yq, and runtimes
         run: |
           set -euo pipefail
-          echo "::group::Install flatpak + flatpak-builder"
+          echo "::group::Install flatpak + flatpak-builder + yq"
           sudo apt-get update
-          sudo apt-get install -y flatpak flatpak-builder
+          sudo apt-get install -y flatpak flatpak-builder yq
           echo "::endgroup::"
           echo "::group::Configure flathub remote"
           # Add flathub to the user installation (match --user usage later)
@@ -105,6 +108,16 @@ jobs:
           flatpak --user --noninteractive install -y flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08
           echo "::endgroup::"
 
+      - name: Verify rendered Flatpak branch
+        run: |
+          set -euo pipefail
+          ACTUAL_BRANCH="$(yq -r '.branch' flatpak/cryptad.yaml)"
+          if [ "$ACTUAL_BRANCH" != "$FLATPAK_BRANCH" ]; then
+            echo "::error::Expected Flatpak manifest branch '$FLATPAK_BRANCH' but found '$ACTUAL_BRANCH'"
+            exit 1
+          fi
+          echo "::notice::Verified Flatpak manifest branch: $ACTUAL_BRANCH"
+
       - name: Build Flatpak (manifest)
         env:
           FLATPAK_DEFAULT_ARCH: ${{ matrix.flatpak_arch }}
@@ -122,16 +135,23 @@ jobs:
           set -euo pipefail
           VERSION='${{ steps.prepare.outputs.version }}'
           APPID='network.crypta.cryptad'
-          BRANCH="v${VERSION}"
+          BRANCH="${FLATPAK_BRANCH}"
           # Canonical arch naming for artifact filenames
           case "${{ matrix.flatpak_arch }}" in
             x86_64) CANON_ARCH=amd64 ;;
             aarch64) CANON_ARCH=arm64 ;;
             *) CANON_ARCH='${{ matrix.flatpak_arch }}' ;;
           esac
           echo "::group::Export repo"
-          # Export to the same branch we'll bundle (defaults to 'master' if omitted)
+          # Export to the same stable branch we'll bundle so all releases share one ref.
           flatpak build-export --arch=${{ matrix.flatpak_arch }} repo builddir "$BRANCH"
+          EXPECTED_REF="app/${APPID}/${{ matrix.flatpak_arch }}/${BRANCH}"
+          if ! ostree refs --repo=repo | grep -Fx "$EXPECTED_REF" >/dev/null; then
+            echo "::error::Expected exported Flatpak ref '$EXPECTED_REF' was not created"
+            ostree refs --repo=repo | sed 's/^/::error::[ref] /'
+            exit 1
+          fi
+          echo "::notice::Verified exported Flatpak ref: $EXPECTED_REF"
           echo "::endgroup::"
           echo "::group::Create bundle"
           BUNDLE="cryptad-v${VERSION}-${CANON_ARCH}.flatpak"

AGENTS.md

@@ -119,7 +119,7 @@ Diagnostics:
 Path: `flatpak/cryptad.yaml.template`
 
 Key points:
-- `id: network.crypta.cryptad`, `branch: v__VERSION__`.
+- `id: network.crypta.cryptad`, `branch: stable`.
 - `runtime: org.freedesktop.Platform`, `runtime-version: '24.08'`, `sdk: org.freedesktop.Sdk`.
 - `command: cryptad-launcher` (GUI entry) with `finish-args` for network, wayland/x11, IPC, DRI, and `env: CRYPTAD_ALLOW_ROOT=1`.
 - Single `modules` entry unpacks `cryptad-jlink-v__VERSION__.tar.gz` to `/app` with `--strip-components=1` to ensure `/app/bin/cryptad` exists.
@@ -161,11 +161,12 @@ High‑level flow:
   4) Build upstream dist; write absolute tarball path to `.tarball-path`.
   5) Repack payload to `flatpak/local/cryptad-jlink-v<version>.tar.gz`.
   6) Render `flatpak/cryptad.yaml` and `flatpak/network.crypta.cryptad.metainfo.xml` from templates.
+     - Assert with `yq` that the rendered manifest branch is `stable`.
   7) Render shared desktop file (`Exec=cryptad-launcher`, `Icon=network.crypta.cryptad`).
   8) Install Flatpak tooling; add Flathub remote to the user scope; install freedesktop runtime+SDK 24.08.
   9) Build with `flatpak-builder --user --arch=<matrix>`.
- 10) Export repo to branch `v<version>` and bundle as `cryptad-flatpak-v<version>-<arch>.flatpak`.
- 11) Upload artifact per arch: `cryptad-flatpak-<version>-x86_64` or `...-aarch64`.
+ 10) Export repo to branch `stable`, verify the exported ref, and bundle as `cryptad-v<version>-<arch>.flatpak`.
+ 11) Upload artifact per arch: `cryptad-flatpak-<version>-amd64` or `...-arm64`.
 
 ## Rationale and Lessons Learned
 

README.md

@@ -111,7 +111,7 @@ Artifacts:
 ## Flatpak (Freedesktop 24.08)
 
 Template: `flatpak/cryptad.yaml.template`
-- `id: network.crypta.cryptad`, `branch: v__VERSION__`
+- `id: network.crypta.cryptad`, `branch: stable`
 - Runtime/SDK: `org.freedesktop.Platform` / `org.freedesktop.Sdk` (24.08)
 - GUI command: `cryptad-launcher`; `finish-args` include network, wayland/x11,
   IPC/DRI, and `CRYPTAD_ALLOW_ROOT=1`
@@ -120,7 +120,7 @@ Template: `flatpak/cryptad.yaml.template`
 - Installs desktop file and 512×512 hicolor icon, plus AppStream metadata
 
 The workflow installs Flatpak tooling, adds Flathub to the user scope, installs
-freedesktop 24.08 runtime+SDK, builds, exports branch `v<version>`, and bundles.
+freedesktop 24.08 runtime+SDK, builds, exports branch `stable`, and bundles.
 
 Artifacts:
 - GitHub artifact names: `cryptad-flatpak-<version>-amd64`, `cryptad-flatpak-<version>-arm64`

flatpak/cryptad.yaml.template

@@ -1,5 +1,5 @@
 id: network.crypta.cryptad
-branch: v__VERSION__
+branch: stable
 runtime: org.freedesktop.Platform
 runtime-version: '24.08'
 sdk: org.freedesktop.Sdk