Feature(Workflow): New beta tests workflow (#587)

* feat(desktop): add beta version browser with downgrade support

* ci: run CI on push to develop and add merge_group trigger

Add `develop` to push branches so merges run the full test suite
post-merge, and add the `merge_group` trigger to make CI merge-queue
ready. Harden the i18n gate on push/merge_group by making the compile
step fail hard instead of continuing (auto-translate commit-back only
makes sense on pull_request events).

* fix(release): parse full semver pre-releases and unify version logic

Rewrite the release version model around real semver pre-release
identifiers instead of the ad-hoc {beta, staging} fields, so historical
tags like v0.7.0-rc.* and v0.4.0-electron parse and order correctly.

- scripts/release-version.mjs is now the single source of truth for
  parsing and comparing release versions; the desktop release catalog
  delegates to it (via a new @root alias to the repo root) instead of
  duplicating the regex and comparator
- add isBetaVersion/betaNumberOf helpers and restrict the issue-template
  beta slots to -beta tags, keeping rc/electron pre-releases out of the
  dropdown
- ship a release-version.d.mts declaration so the Electron main process
  can type-check the shared .mjs module

* feat(release): add beta release provenance

* refactor: split components in diferent files

* feat(release): show cover art and metadata in beta version browser

- parse release presentation (title, description, cover image) from
  release notes and expose it through the desktop release catalog and
  preload type definitions
- redesign the beta version browser with cover thumbnails, a search
  hero, direction badges, and dedicated loading/empty/search states
- replace the downgrade confirmation modal with a discreet popover
  (no overlay)
- group all beta-only browser components under components/updates/beta
  and add ScrollArea and DotGrid UI primitives
- scroll beta browser content through the new ScrollArea and add
  staggered entrance animations
- update i18n catalogs (en, es, fr, pt-BR, sq) and remove the
  superseded BETA_RELEASE_PROVENANCE spec

* feat: add version size on card

* fix(release): fail staging listener on conflicting PR instead of silent
skip

* refactor(release): trigger PR staging manually and require a green CI
run

* refactor(staging): unify PR staging into a single branch-driven workflow

* feat: add skip notarize

* feat: add skip notorize to macos

* feat: add publish pre-release step

* fix: PR detecting and add pre-release cleanup

* feat(staging): dispatch staging by PR number from develop

* fix(staging): run cleanup via pull_request_target from develop

* refactor: remove useless code and deadcode

* fix(beta): address PR review findings in beta update flow

- Rank numbered betas (beta.N) above per-PR staging builds (beta-<slug>)
  of the same core in compareReleaseVersions, so staging builds no
  longer
  sort above real betas or get auto-selected by the updater's upgrade
  pick
- Restrict release-notes images to the trusted GitHub host allowlist
  (shared trustedAssetUrl), closing a tracking-pixel vector from
  attacker-influenceable beta tags
- Use isLoading instead of isPending in BetaVersionsView so the loading
  flag clears when the versions query is disabled (empty state
  reachable)
- Validate TRIGGER_SHA and TAG in compose-release-notes before they
  reach
  git as bare arguments, preventing option-injection
- Document the load-bearing host-pinning at the runtime setFeedURL call

Author: zignaggo

.github/rulesets/protect-release-tags.json

@@ -0,0 +1,23 @@
+{
+  "name": "Protect release tags",
+  "target": "tag",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/tags/v*"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    { "type": "creation" },
+    { "type": "update" },
+    { "type": "deletion" }
+  ],
+  "bypass_actors": [
+    {
+      "actor_id": 5,
+      "actor_type": "RepositoryRole",
+      "bypass_mode": "always"
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -2,11 +2,13 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, develop]
   pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  merge_group:
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
   test:
@@ -31,6 +33,8 @@ jobs:
 
   i18n:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
@@ -62,7 +66,7 @@ jobs:
       - name: Check translations are up to date
         id: compile
         run: pnpm --filter @adt/studio compile --strict
-        continue-on-error: true
+        continue-on-error: ${{ github.event_name == 'pull_request' }}
       - name: Warn about missing translations
         if: steps.compile.outcome == 'failure'
         run: |

.github/workflows/release.yml

@@ -5,15 +5,24 @@ on:
     branches: [main, develop]
   workflow_dispatch:
     inputs:
-      tag:
-        description: 'Release tag (e.g. v0.8.0 on main, v0.8.0-beta.1 on develop)'
+      release_type:
+        description: "Version increment"
         required: true
+        default: beta
+        type: choice
+        options:
+          - beta
+          - beta-minor
+          - beta-major
+          - patch
+          - minor
+          - major
 
 permissions:
   contents: read
 
 concurrency:
-  group: release-${{ github.ref_name }}
+  group: release
   cancel-in-progress: false
 
 # Opt JS actions into Node 24 ahead of the June 2026 default — silences the
@@ -47,52 +56,47 @@ jobs:
           echo "Total tags: $(git tag --list | wc -l)"
           git tag --list | sort -V
 
-      - name: Extract tag
+      - name: Calculate release version
         id: tag
         env:
           EVENT_NAME: ${{ github.event_name }}
-          INPUT_TAG: ${{ inputs.tag }}
+          INPUT_RELEASE_TYPE: ${{ inputs.release_type }}
           BRANCH: ${{ github.ref_name }}
         run: |
           MSG=""
           if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
-            TAG="$INPUT_TAG"
+            RELEASE_TYPE="$INPUT_RELEASE_TYPE"
           else
             MSG=$(git log -1 --pretty=%s)
             shopt -s nocasematch
-            if [[ "$MSG" =~ ^release:[[:space:]]*([^[:space:]]+) ]]; then
-              TAG="${BASH_REMATCH[1]}"
+            if [[ "$MSG" =~ ^release:[[:space:]]*(major|minor|patch|beta-minor|beta-major|beta)[[:space:]]*$ ]]; then
+              RELEASE_TYPE="${BASH_REMATCH[1],,}"
             fi
             shopt -u nocasematch
           fi
-          if [[ -z "$TAG" ]]; then
-            echo "::error::Could not extract tag. event=$EVENT_NAME input='$INPUT_TAG' subject='$MSG'"
+          if [[ -z "$RELEASE_TYPE" ]]; then
+            echo "::error::Could not resolve release type. event=$EVENT_NAME input='$INPUT_RELEASE_TYPE' subject='$MSG'"
             exit 1
           fi
-          [[ "$TAG" =~ ^v ]] || TAG="v$TAG"
-          # Validate charset before propagating downstream. This both rejects
-          # malformed tags and blocks shell / GITHUB_OUTPUT injection via the tag.
-          if [[ ! "$TAG" =~ ^v[0-9A-Za-z.+_-]+$ ]]; then
-            echo "::error::Invalid tag format: $TAG"
+          if [[ "$BRANCH" == "develop" && "$RELEASE_TYPE" != beta* ]]; then
+            echo "::error::develop only ships beta releases. Select beta, beta-minor, or beta-major."
             exit 1
           fi
-          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
-            echo "::error::Tag $TAG already exists on origin. Bump the version."
+          if [[ "$BRANCH" == "main" && "$RELEASE_TYPE" == beta* ]]; then
+            echo "::error::main only ships stable releases. Select patch, minor, or major."
             exit 1
           fi
-          if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-beta(\.[0-9]+)?$ ]]; then
+          VERSION=$(node scripts/calculate-release-version.mjs "$RELEASE_TYPE")
+          TAG="v$VERSION"
+          if [[ "$RELEASE_TYPE" == beta* ]]; then
             PRERELEASE=true
-          elif [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            PRERELEASE=false
           else
-            echo "::error::Tag $TAG must be either vX.Y.Z (stable) or vX.Y.Z-beta[.N]."
-            exit 1
+            PRERELEASE=false
           fi
-          if [[ "$BRANCH" == "main" && "$PRERELEASE" == "true" ]]; then
-            echo "::error::main only ships stable tags (got $TAG). Use vX.Y.Z."
+          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
+            echo "::error::Calculated tag $TAG already exists on origin."
             exit 1
           fi
-          VERSION="${TAG#v}"
           DOCKER_TAGS="ghcr.io/unicef/adt-studio:$TAG"
           if [[ "$PRERELEASE" == "false" ]]; then
             DOCKER_TAGS="$DOCKER_TAGS"$'\n'"ghcr.io/unicef/adt-studio:latest"
@@ -116,7 +120,7 @@ jobs:
             echo "$DOCKER_TAGS"
             echo "EOF"
           } >> "$GITHUB_OUTPUT"
-          echo "Resolved tag: $TAG (version: $VERSION, prerelease: $PRERELEASE)"
+          echo "Resolved tag: $TAG (type: $RELEASE_TYPE, prerelease: $PRERELEASE)"
 
       - uses: pnpm/action-setup@v4
 
@@ -165,6 +169,7 @@ jobs:
       contents: read
     env:
       APP_VERSION: ${{ needs.prepare.outputs.version }}
+      SKIP_NOTARIZE: ${{ vars.SKIP_NOTARIZE }}
     steps:
       - uses: actions/checkout@v4
 
@@ -206,9 +211,8 @@ jobs:
           APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
 
-
       - name: Acquire Azure code signing token
-        if: matrix.os == 'windows-latest'
+        if: matrix.os == 'windows-latest' && env.SKIP_NOTARIZE != 'true'
         shell: bash
         env:
           AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
@@ -236,7 +240,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: '21'
+          java-version: "21"
 
       - name: Cache jsign.jar
         if: matrix.os == 'windows-latest'
@@ -309,6 +313,7 @@ jobs:
     timeout-minutes: 15
     permissions:
       contents: write
+      pull-requests: read
     outputs:
       tag: ${{ needs.prepare.outputs.tag }}
       version: ${{ needs.prepare.outputs.version }}
@@ -317,6 +322,11 @@ jobs:
       - uses: actions/checkout@v4
         with:
           token: ${{ secrets.RELEASE_PAT }}
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
 
       - name: Restore staged release metadata
         uses: actions/download-artifact@v4
@@ -331,6 +341,23 @@ jobs:
           path: dist
           merge-multiple: true # flatten the per-OS artifacts into one dir
 
+      - name: Compose beta release notes
+        if: needs.prepare.outputs.prerelease == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ needs.prepare.outputs.tag }}
+          REPO: ${{ github.repository }}
+          BRANCH: ${{ github.ref_name }}
+          TRIGGER_SHA: ${{ github.sha }}
+        run: |
+          rm -f release-notes.tmp release-notes.md
+          if node scripts/compose-release-notes.mjs > release-notes.tmp && [ -s release-notes.tmp ]; then
+            mv release-notes.tmp release-notes.md
+          else
+            rm -f release-notes.tmp release-notes.md
+            echo "::warning::Could not compose release notes; gh release create will generate them."
+          fi
+
       - name: Commit release metadata and push tag
         id: commit
         env:
@@ -369,9 +396,13 @@ jobs:
           [[ "$PRERELEASE" == "true" ]] && PRERELEASE_FLAG="--prerelease"
           START_TAG_FLAG=()
           [[ -n "$PREV_TAG" ]] && START_TAG_FLAG=(--notes-start-tag "$PREV_TAG")
+          NOTES_ARGS=(--generate-notes "${START_TAG_FLAG[@]}")
+          if [[ "$PRERELEASE" == "true" && -s release-notes.md ]]; then
+            NOTES_ARGS=(--notes-file release-notes.md)
+          fi
           gh release create "$TAG" --repo "$REPO" \
             --title "ADT Studio $TAG" \
-            --generate-notes "${START_TAG_FLAG[@]}" $PRERELEASE_FLAG \
+            "${NOTES_ARGS[@]}" $PRERELEASE_FLAG \
             dist/* \
             docker-compose.yml \
             scripts/windows-setup-and-run.bat

.github/workflows/staging-cleanup.yml

@@ -0,0 +1,58 @@
+name: Staging cleanup
+
+on:
+  pull_request_target:
+    types: [closed]
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: "Pull request number whose staging release to delete"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+concurrency:
+  group: staging-cleanup-pr-${{ github.event.pull_request.number || inputs.pr }}
+  cancel-in-progress: false
+
+jobs:
+  cleanup:
+    if: >-
+      ${{ github.event_name == 'workflow_dispatch'
+          || github.event.pull_request.base.ref == 'develop' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Delete staging pre-release and branch
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number || inputs.pr }}
+        run: |
+          if [[ ! "$PR" =~ ^[0-9]+$ ]]; then
+            echo "No valid PR number ('$PR'); nothing to clean up."
+            exit 0
+          fi
+          SLUG="pr-$PR"
+          STAGING_BRANCH="staging/$SLUG"
+
+          RELEASES=$(gh release list --repo "$REPO" --limit 200 --json tagName \
+            --jq '.[].tagName' | { grep -E -- "-beta-${SLUG}$" || true; })
+          if [[ -z "$RELEASES" ]]; then
+            echo "No staging pre-release found for '$SLUG'; skipping."
+          else
+            for release in $RELEASES; do
+              echo "Deleting staging pre-release $release"
+              gh release delete "$release" --repo "$REPO" --yes --cleanup-tag || true
+            done
+          fi
+
+          if gh api "repos/$REPO/git/refs/heads/$STAGING_BRANCH" >/dev/null 2>&1; then
+            echo "Deleting staging branch $STAGING_BRANCH"
+            gh api -X DELETE "repos/$REPO/git/refs/heads/$STAGING_BRANCH" >/dev/null || true
+          else
+            echo "No staging branch '$STAGING_BRANCH' found; skipping."
+          fi