ci(promote): replace push-based promotion with PR gate (ublue-os#1195)

Ok I think I got it this time, I can confirm this works via testing in
my personal repo. I am likely going to force this because we need the
action in the LTS branch anyway.

## Agent Notes follow: 

## Solution

Replace with `create-lts-pr.yml`, a PR-gate workflow:
- Fires on every push to `main` (and `workflow_dispatch`)
- Uses `git diff --quiet` (content diff, not commit graph) to detect new
content — survives squash-merges without false positives
- Passes the commit list as a `COMMIT_LIST` env var and uses `printf` to
build the PR body, safely handling commit messages containing double
quotes (e.g. `Revert "..."`)
- Auto-creates a draft PR from `main` → `lts`, or updates the existing
one
- Maintainer squash-merges the PR as the human approval gate
- No pre-flight check: branch protection is the guard against direct
`lts` commits

Also fixes `AGENTS.md`: corrects the release schedule (cron `0 6 * * 2`
= Tuesday 6am UTC, not Sunday 2am UTC) and updates all references to the
old workflow.

## Testing

Tested on the `castrojo/bluefin-lts` fork:
- ✅ Workflow fires on push and creates draft PR correctly
- ✅ PR body auto-updates on subsequent pushes without creating duplicate
PRs
- ✅ Commit messages with double quotes handled safely (the `Revert
"..."` case)
- ✅ Force-push after squash: workflow correctly updates existing PR

Assisted-by: Claude Sonnet 4.6 via GitHub Copilot

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: castrojo

.github/workflows/create-lts-pr.yml

@@ -0,0 +1,78 @@
+name: Create LTS Promotion PR
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: create-lts-pr
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Fetch lts
+        run: git fetch origin lts
+
+      - name: Check content diff
+        id: diff
+        run: |
+          if git diff --quiet origin/lts origin/main; then
+            echo "No content difference between lts and main. Nothing to promote."
+            echo "has_diff=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_diff=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build commit list
+        if: steps.diff.outputs.has_diff == 'true'
+        id: commits
+        run: |
+          LIST=$(git log origin/lts..origin/main --oneline)
+          {
+            echo "list<<EOF"
+            echo "$LIST"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create or update promote PR
+        if: steps.diff.outputs.has_diff == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          COMMIT_LIST: ${{ steps.commits.outputs.list }}
+        run: |
+          # Build body with printf so commit messages containing quotes are safe
+          BODY=$(printf '## Commits pending promotion to `lts`\n\n%s\n\n---\n_Squash-merge this PR to promote. The PR body updates automatically as `main` advances._\n' "${COMMIT_LIST}")
+
+          EXISTING=$(gh pr list \
+            --base lts \
+            --head main \
+            --state open \
+            --json number \
+            --jq '.[0].number' \
+            2>/dev/null || echo "")
+
+          if [ -n "$EXISTING" ]; then
+            echo "Updating existing promote PR #${EXISTING}"
+            printf '%s\n' "${BODY}" | gh pr edit "$EXISTING" --body-file - || true
+          else
+            echo "Creating new draft promote PR"
+            printf '%s\n' "${BODY}" | gh pr create \
+              --draft \
+              --base lts \
+              --head main \
+              --title "promote: main → lts" \
+              --body-file -
+          fi

.github/workflows/promote-to-lts.yml

@@ -120,8 +120,8 @@ This section is the authoritative reference for all CI/CD behavior. Read it comp
 | `build-regular-hwe.yml` | Caller — builds `bluefin` with HWE kernel |
 | `build-dx-hwe.yml` | Caller — builds `bluefin-dx` with HWE kernel |
 | `reusable-build-image.yml` | Reusable workflow — all 5 callers invoke this |
-| `scheduled-lts-release.yml` | Dispatcher — owns the weekly Sunday production release |
-| `promote-to-lts.yml` | Squash-pushes `main` → `lts` with pre-flight divergence check (see below) |
+| `scheduled-lts-release.yml` | Dispatcher — owns the weekly Tuesday production release |
+| `create-lts-pr.yml` | Opens a draft PR from `main` → `lts` when content differs; maintainer squash-merges as approval gate |
 | `generate-release.yml` | Creates a GitHub Release when `build-gdx.yml` completes on `lts` |
 
 ### Two Branches, Two Tag Namespaces
@@ -137,23 +137,24 @@ This section is the authoritative reference for all CI/CD behavior. Read it comp
 
 Promotion and production release are **intentionally decoupled**. There are two separate phases:
 
-**Phase 1 — Promotion (manual, no publishing):**
-1. A maintainer triggers `promote-to-lts.yml` via `workflow_dispatch`
-2. The workflow runs a **pre-flight check**: fails immediately if `lts` has any commits not reachable from `main`, printing those commits with instructions to land them in `main` first.
-3. The workflow performs a **squash merge** (`git merge --squash origin/main`) and pushes one clean commit to `lts`. There is no PR. Triggering `workflow_dispatch` is the human approval step.
-4. The push triggers a `push` event on `lts` — all 5 build workflows run as **validation builds** (`publish=false`). No images are published. This confirms the promoted code builds cleanly on `lts` before the next production release.
+**Phase 1 — Promotion (human-gated via PR):**
+1. Every push to `main` triggers `create-lts-pr.yml`
+2. The workflow checks `git diff --quiet origin/lts origin/main` (content diff, not commit graph — survives squash-merges)
+3. If content differs: a draft PR from `main` → `lts` is created (or the existing one is updated with the latest commit list)
+4. A maintainer reviews and **squash-merges** the PR — this is the human approval gate
+5. The squash-merge triggers a `push` event on `lts` — all 5 build workflows run as **validation builds** (`publish=false`). No images are published.
 
 **Phase 2 — Production release (automated or manual publishing):**
-1. `scheduled-lts-release.yml` fires at `0 2 * * 0` (Sunday 2am UTC), OR a maintainer manually triggers it
+1. `scheduled-lts-release.yml` fires at `0 6 * * 2` (Tuesday 6am UTC), OR a maintainer manually triggers it
 2. It dispatches all 5 build workflows via `gh workflow run --ref lts`
 3. Those are `workflow_dispatch` events on `lts` → `publish=true` → production tags pushed
 4. After `build-gdx.yml` completes on `lts`, `generate-release.yml` creates a GitHub Release
 
-**Why `promote-to-lts.yml` exists:** Automated tools (the old Pull app, AI agents) cannot distinguish merge direction — when they see `lts` is behind `main`, they attempt to "sync" and sometimes merge `lts` → `main`, polluting `main` with old production commits. The workflow enforces the correct direction by always targeting `lts` as the base.
+**Why `create-lts-pr.yml` exists:** Automated tools (the old Pull app, AI agents) cannot distinguish merge direction — when they see `lts` is behind `main`, they attempt to "sync" and sometimes merge `lts` → `main`, polluting `main` with old production commits. The PR-gate workflow enforces the correct direction: `main` → `lts` only, with a human squash-merge as the approval step.
 
 **NEVER merge `lts` into `main`.** The flow is always one-way: `main` → `lts`.
 
-**NEVER commit directly to `lts`.** All changes — including CI hotfixes — must land in `main` first. Direct commits to `lts` create divergence that causes the pre-flight check to fail and blocks future promotions.
+**NEVER commit directly to `lts`.** All changes — including CI hotfixes — must land in `main` first. Direct commits to `lts` will appear as phantom content in the PR diff and confuse reviewers.
 
 ### `publish` Input — How It Is Evaluated
 
@@ -252,7 +253,7 @@ When touching any condition in `reusable-build-image.yml`, use this reference:
 
 ### `schedule:` Triggers — Ownership Rule
 
-**`scheduled-lts-release.yml` is the sole owner of Sunday 2am UTC production builds.**
+**`scheduled-lts-release.yml` is the sole owner of Tuesday 6am UTC production builds.**
 
 The 5 build caller workflows (`build-regular.yml`, `build-dx.yml`, `build-gdx.yml`, `build-regular-hwe.yml`, `build-dx-hwe.yml`) must NOT have `schedule:` triggers. Any `schedule:` event on those workflows fires on `main` (the default branch), evaluates `publish=false`, publishes nothing, and wastes runner time.
 
@@ -264,8 +265,8 @@ If you see `schedule:` in any of the 5 build callers, remove it entirely. Do not
 - `build-gdx.yml` — GPU/AI Developer Experience (`bluefin-gdx` image)
 - `build-regular-hwe.yml` — HWE kernel variant of `bluefin`
 - `build-dx-hwe.yml` — HWE kernel variant of `bluefin-dx`
-- `scheduled-lts-release.yml` — Weekly production release dispatcher (sole owner of Sunday builds)
-- `promote-to-lts.yml` — Squash-pushes `main` into `lts` (with pre-flight divergence check)
+- `scheduled-lts-release.yml` — Weekly production release dispatcher (sole owner of Tuesday builds)
+- `create-lts-pr.yml` — Opens a draft PR from `main` → `lts` when content differs; maintainer squash-merges as approval gate
 - `generate-release.yml` — Creates GitHub Release after successful GDX build on `lts`
 
 ## Validation Scenarios