Track upstream branches as pinned releases on an unattended lane

Since publishing moved to CI on merge, a package whose PKGBUILD never
changes while its source moves was never rebuilt: omarchy-dev and
omarchy-settings-dev followed quattro through "#branch=" and a pkgver()
function, and nothing in this repository changed when quattro did. The
host timers that used to notice are off, so edge fell days behind.

The rule now: no git source without a commit or tag pin
(tests/pinned-sources.sh, run in CI). A package that has to follow a
branch declares a git_branch upstream watch, and the pin moves through
the same PR/build/publish path as every other version bump.

Watch (helpers/upstream-watch.py)
  git_branch gains tag_pattern: the newest release tag in the pinned
  commit's own history, exposed as {tag}/{version}/{distance}, so a
  branch build is versioned <tag>.r<n>.g<sha>, above the release it
  follows and below the next one. One blobless clone per branch per
  run, shared by every package on it. min_release_age selects the
  newest commit older than the window, so a push burst builds once.

Lane (helpers/package-metadata.sh, bin/sync-upstream --lane)
  "auto_merge": true moves a package from the reviewed 6-hourly sync
  PR to the unattended lane. Packages pinned from the same branch move
  together: a failure on one restores the others and fails the group,
  so the dev pair can never ship from two quattro commits.

Tracker (.github/workflows/track-branches.yml)
  Every two hours: pin, open one PR with a GitHub App token, enable
  auto-merge. Branch protection still gates the merge on result,
  self-tests and build-isolation. A tip that fails to build stays an
  open red PR until the next tick supersedes it. The App is required:
  a PR opened with GITHUB_TOKEN has its checks held for approval and
  its auto-merge would not fire publish.yml.

The reviewed workflows (sync-upstream, sync-rebuilds) open their PRs
with the same App so their builds start without a maintainer clicking
"Approve workflows to run"; without the App they fall back to
GITHUB_TOKEN and behave as before.

Recipes
  The dev pair pins _commit and a real sha256sum, keeps the OMARCHY_SRC
  override, and drops pkgver(). Its r-number stays the branch's total
  commit count because the published history used it and pacman must
  never see the version go down. omasnap-git is new: omacom/omasnap
  main, versioned <tag>.r<distance>.g<sha>, provides/conflicts omasnap.

.github/workflows/sync-rebuilds.yml

@@ -68,11 +68,27 @@ jobs:
             echo "has_changes=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # App token rather than GITHUB_TOKEN so the PR's build and test runs
+      # start without a maintainer approving them (see sync-upstream.yml).
+      - name: Mint the bot token
+        if: steps.changes.outputs.has_changes == 'true'
+        id: app
+        env:
+          PKGS_BOT_APP_ID: ${{ secrets.PKGS_BOT_APP_ID }}
+        # Without the App configured this falls back to GITHUB_TOKEN below,
+        # which still opens the PR; a maintainer then has to approve its
+        # workflow runs by hand, as before.
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.PKGS_BOT_APP_ID }}
+          private-key: ${{ secrets.PKGS_BOT_PRIVATE_KEY }}
+        continue-on-error: true
+
       - name: Create Pull Request
         if: steps.changes.outputs.has_changes == 'true'
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ steps.app.outputs.token || secrets.GITHUB_TOKEN }}
           commit-message: 'chore: rebuild against updated dependencies'
           title: 'chore: rebuild against updated dependencies'
           body: |

.github/workflows/sync-upstream.yml

@@ -47,11 +47,13 @@ jobs:
               useradd -m -u "$HOST_UID" -g "$HOST_GID" runner
               chown -R runner:runner /workspace/pkgbuilds
 
+              # The reviewed lane only: packages marked auto_merge ride
+              # track-branches.yml, which merges without a human.
               if [[ -n "${PACKAGES:-}" ]]; then
                 read -r -a package_args <<< "$PACKAGES"
-                runuser -u runner -- ./bin/sync-upstream "${package_args[@]}"
+                runuser -u runner -- ./bin/sync-upstream --lane reviewed "${package_args[@]}"
               else
-                runuser -u runner -- ./bin/sync-upstream
+                runuser -u runner -- ./bin/sync-upstream --lane reviewed
               fi
             '
         env:
@@ -70,11 +72,30 @@ jobs:
             echo "has_changes=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # A PR opened with GITHUB_TOKEN gets its build and test runs held
+      # until a maintainer clicks "Approve workflows to run"; one opened by
+      # the App builds on its own, so the reviewer sees a green (or red) PR
+      # instead of a pending one. The App only opens the PR: merging stays
+      # a human decision in this lane.
+      - name: Mint the bot token
+        if: ${{ !cancelled() && steps.changes.outputs.has_changes == 'true' }}
+        id: app
+        env:
+          PKGS_BOT_APP_ID: ${{ secrets.PKGS_BOT_APP_ID }}
+        # Without the App configured this falls back to GITHUB_TOKEN below,
+        # which still opens the PR; a maintainer then has to approve its
+        # workflow runs by hand, as before.
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.PKGS_BOT_APP_ID }}
+          private-key: ${{ secrets.PKGS_BOT_PRIVATE_KEY }}
+        continue-on-error: true
+
       - name: Create Pull Request
         if: ${{ !cancelled() && steps.changes.outputs.has_changes == 'true' }}
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ steps.app.outputs.token || secrets.GITHUB_TOKEN }}
           commit-message: 'chore: sync upstream releases'
           title: 'chore: sync upstream releases'
           body: |

.github/workflows/test.yml

@@ -58,6 +58,7 @@ jobs:
               python tests/neovim-clipboard-tmux.py
               ./tests/partial-release.sh
               ./tests/published-build-plan.sh
+              ./tests/pinned-sources.sh
               ./tests/controller.sh
               ./tests/artifact-helpers.sh
               ./tests/limine-mkinitcpio-hook.sh

.github/workflows/track-branches.yml

@@ -0,0 +1,177 @@
+name: Track upstream branches
+
+# The unattended lane. Packages marked "auto_merge": true follow a moving
+# upstream branch (omarchy-dev and omarchy-settings-dev on quattro, omasnap-git
+# on main) rather than tagged releases, so nothing in this repository changes
+# when their source does. This workflow makes each new branch tip a commit pin
+# in the recipe, which publish.yml then treats like any other version bump:
+# the PR builds on the droplets, auto-merge lands it when `result` is green,
+# and the merge publishes the artifacts. A tip that fails to build stays an
+# unmerged red PR that the next tick supersedes.
+#
+# The PR is opened with a GitHub App token, not GITHUB_TOKEN: a pull request
+# created with the workflow token gets its CI runs held for manual approval,
+# and an auto-merge it enabled would not fire the publish workflow. The App
+# needs Contents: write and Pull requests: write on this repository; its id
+# and private key live in the PKGS_BOT_APP_ID / PKGS_BOT_PRIVATE_KEY secrets.
+
+on:
+  schedule:
+    # Every 2 hours, off the hour to dodge the scheduling backlog at :00
+    - cron: '35 */2 * * *'
+  workflow_dispatch:
+    inputs:
+      packages:
+        description: 'Specific packages to track (space-separated, leave empty for every auto_merge package)'
+        required: false
+        default: ''
+
+# One tracker at a time: two runs racing on auto/track-branches would each
+# force-push their own pin over the other's.
+concurrency:
+  group: track-branches
+  cancel-in-progress: false
+
+jobs:
+  track:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      # Same container as the reviewed sync: vercmp decides whether a pin is
+      # an upgrade with the comparator pacman uses on users' machines.
+      - name: Pin tracked branches to their current tips
+        id: sync
+        run: |
+          docker run --rm \
+            -e PACKAGES="$PACKAGES" \
+            -e UPSTREAM_GITHUB_TOKEN="$UPSTREAM_GITHUB_TOKEN" \
+            -e HOST_UID="$(id -u)" \
+            -e HOST_GID="$(id -g)" \
+            -v "$PWD/bin:/workspace/bin:ro" \
+            -v "$PWD/helpers:/workspace/helpers:ro" \
+            -v "$PWD/pkgbuilds:/workspace/pkgbuilds" \
+            -w /workspace \
+            archlinux:base-devel bash -lc '
+              set -euo pipefail
+
+              pacman -Syu --noconfirm git jq python libarchive
+
+              groupadd -g "$HOST_GID" runner
+              useradd -m -u "$HOST_UID" -g "$HOST_GID" runner
+              chown -R runner:runner /workspace/pkgbuilds
+
+              if [[ -n "${PACKAGES:-}" ]]; then
+                read -r -a package_args <<< "$PACKAGES"
+                runuser -u runner -- ./bin/sync-upstream --lane auto-merge "${package_args[@]}"
+              else
+                runuser -u runner -- ./bin/sync-upstream --lane auto-merge
+              fi
+            '
+        env:
+          PACKAGES: ${{ github.event.inputs.packages }}
+          UPSTREAM_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check for changes
+        if: ${{ !cancelled() && steps.sync.outcome != 'skipped' }}
+        id: changes
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+            git status --porcelain
+            {
+              echo "### Pinned"
+              git diff --unified=0 -- 'pkgbuilds/*/PKGBUILD' | grep -E '^\+(pkgver|_commit)=' | sed 's/^+/- /'
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      # No fallback to GITHUB_TOKEN here: a PR it opened would sit with its
+      # checks held, and an auto-merge it enabled would land without running
+      # publish.yml. Better to fail loudly than to pin quietly.
+      - name: Require the bot App
+        if: ${{ !cancelled() && steps.changes.outputs.has_changes == 'true' }}
+        env:
+          PKGS_BOT_APP_ID: ${{ secrets.PKGS_BOT_APP_ID }}
+        run: |
+          if [[ -z "$PKGS_BOT_APP_ID" ]]; then
+            echo "::error::PKGS_BOT_APP_ID / PKGS_BOT_PRIVATE_KEY are not set. Create a GitHub App with Contents: write and Pull requests: write, install it on this repository, and store its id and private key as those secrets."
+            exit 1
+          fi
+
+      - name: Mint the bot token
+        if: ${{ !cancelled() && steps.changes.outputs.has_changes == 'true' }}
+        id: app
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.PKGS_BOT_APP_ID }}
+          private-key: ${{ secrets.PKGS_BOT_PRIVATE_KEY }}
+
+      # The PR title names what moved, so the merged history reads like a
+      # changelog: "Track upstream branches: omarchy-dev 4.0.0.r6520.g1a2b3c4, ...".
+      - name: Describe the pins
+        if: ${{ !cancelled() && steps.changes.outputs.has_changes == 'true' }}
+        id: describe
+        run: |
+          title=$(git diff --unified=0 -- 'pkgbuilds/*/PKGBUILD' \
+            | awk '/^\+\+\+ b\/pkgbuilds\//{split($2,p,"/"); pkg=p[3]} /^\+pkgver=/{sub(/^\+pkgver=/,""); printf "%s %s, ", pkg, $0}' \
+            | sed 's/, $//')
+          echo "title=Track upstream branches: ${title}" >> "$GITHUB_OUTPUT"
+
+      - name: Open or update the tracking PR
+        if: ${{ !cancelled() && steps.changes.outputs.has_changes == 'true' }}
+        id: pr
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          token: ${{ steps.app.outputs.token }}
+          commit-message: ${{ steps.describe.outputs.title }}
+          title: ${{ steps.describe.outputs.title }}
+          body: |
+            Automated pin of packages that follow a moving upstream branch
+            (`"auto_merge": true` in `.omarchy/package.json`). Each package's
+            `_commit` now points at the branch tip that has been there for at
+            least its `min_release_age`.
+
+            This PR auto-merges once the build checks pass. A failing build
+            leaves it open; the next tracker run replaces it with the newer tip.
+          branch: auto/track-branches
+          delete-branch: true
+          labels: automated
+
+      # Auto-merge, not a direct merge: branch protection still has to see
+      # `result`, `self-tests` and `build-isolation` green, and this lane
+      # inherits every rule the reviewed lane has except the human.
+      - name: Enable auto-merge
+        if: ${{ !cancelled() && steps.pr.outputs.pull-request-number != '' }}
+        env:
+          GH_TOKEN: ${{ steps.app.outputs.token }}
+          PR: ${{ steps.pr.outputs.pull-request-number }}
+        run: |
+          # Idempotent across re-runs of an updated PR: enabling twice errors.
+          if [[ "$(gh pr view "$PR" -R "${{ github.repository }}" --json autoMergeRequest --jq '.autoMergeRequest != null')" == true ]]; then
+            echo "auto-merge already enabled on #$PR"
+            exit 0
+          fi
+          # A PR whose checks all reused existing artifacts can be clean
+          # before this step runs; GitHub then refuses --auto, so merge it.
+          gh pr merge --auto --merge "$PR" -R "${{ github.repository }}" \
+            || gh pr merge --merge "$PR" -R "${{ github.repository }}"
+
+      - name: Notify Basecamp on failure
+        if: failure() && env.BASECAMP_CHATBOT_URL != ''
+        env:
+          BASECAMP_CHATBOT_URL: ${{ secrets.BASECAMP_CHATBOT_URL }}
+        run: |
+          curl -s -o /dev/null \
+            -H "Content-Type: application/json" \
+            -d "$(jq -n --arg content \
+              "🔴 <strong>Branch tracking failed</strong><br><a href=\"${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\">View run</a>" \
+              '{content: $content}')" \
+            "$BASECAMP_CHATBOT_URL"