chore: add promote, back-sync, and trunk-lock workflows

Author: adonis-sh

.github/workflows/stlc-promote.yml

@@ -0,0 +1,70 @@
+name: Promote SDKs
+
+# Promote staging to production by fast-forwarding production `main` up to the
+# staging trunk, preserving commit SHAs. Because the SHAs are preserved,
+# production `main` and staging `main` stay identical and linear, the sealed
+# custom-code commit stays an ancestor of both, and there is no divergence to
+# heal on the next `stlc build`.
+#
+# Manual dispatch (workflow_dispatch): spec/codegen changes accumulate on
+# staging `main`, and a maintainer promotes the batch in one fast-forward when
+# ready to cut a release. Optionally gate each run behind a required-reviewer
+# approval — see the `environment` note on the job below. release-please then
+# opens its version/changelog PR on production on top.
+on:
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  promote:
+    runs-on: ubuntu-latest
+    if: github.repository == 'sentdm/sent-dm-python-staging'
+    # Optional: add required reviewers on each promote run before the fast-forward push. 
+    # With no reviewers it only scopes secrets/variables and adds no gate, so the manual dispatch
+    # above is the only checkpoint. Remove this line if you don't use it.
+    environment: production
+    env:
+      PRODUCTION_REPO: sentdm/sent-dm-python
+      GH_TOKEN: ${{ secrets.PRODUCTION_REPO_TOKEN }}
+    steps:
+      - name: Check out staging
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Fetch production main
+        run: |
+          git remote add production \
+            "https://x-access-token:${GH_TOKEN}@github.com/${PRODUCTION_REPO}.git"
+          git fetch production main
+
+      - name: Check whether production already has staging's content
+        id: diff
+        run: |
+          # After a release, production carries release-please's version/changelog 
+          # commits that staging lacks. Ask whether merging staging into production 
+          # would change production's tree: if not, production already has staging's content.
+          MERGED=$(git merge-tree --write-tree production/main origin/main) || MERGED=conflict
+          PRODUCTION_TREE=$(git rev-parse 'production/main^{tree}')
+          if [ "$MERGED" = "$PRODUCTION_TREE" ]; then
+            echo "Production already contains staging's content. Nothing to promote."
+            echo "synced=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "synced=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Promote staging to production (fast-forward)
+        if: steps.diff.outputs.synced == 'false'
+        run: |
+          # Refuse unless production/main is an ancestor of staging/main. If it
+          # isn't, the trunks have forked (someone advanced production out of
+          # band without back-syncing first) and a fast-forward is unsafe.
+          if ! git merge-base --is-ancestor production/main origin/main; then
+            echo "::error title=Promote blocked::production/main is not an ancestor of staging main. Back-sync production into staging first."
+            exit 1
+          fi
+          git push production origin/main:refs/heads/main
+          echo "Fast-forwarded production/main to staging/main."

.github/workflows/stlc-sync-from-production.yml

@@ -0,0 +1,74 @@
+name: Sync from production
+
+# Bring production's commits back onto staging `main` by fast-forwarding.
+# This keeps staging and production identical and linear so the next `stlc build` 
+# reseals against the released state.
+#
+# Triggered by the production-side release dispatch and by a periodic poll.
+on:
+  schedule:
+    # Polls for non-release production changes. If you take frequent 
+    # community PRs, tighten this or add an eager `on: push: [main]`
+    # dispatch on production alongside the release one.
+    - cron: '17 */6 * * *'
+  workflow_dispatch: {}
+  repository_dispatch:
+    types: [prod-released]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: stlc-sync-from-production
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    if: github.repository == 'sentdm/sent-dm-python-staging'
+    env:
+      PRODUCTION_REPO: sentdm/sent-dm-python
+    steps:
+      - name: Check out staging
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Fetch production main
+        run: |
+          # Production is public, so the built-in token reads it with no
+          # credential. If your production repo is private, add a remote with
+          # PRODUCTION_REPO_TOKEN instead (the same token the promote uses).
+          git remote add production "https://github.com/${PRODUCTION_REPO}.git"
+          git fetch production main
+
+      - name: Check whether production has content staging lacks
+        id: diff
+        run: |
+          # Inverse of the promote guard: would merging production into 
+          # staging change staging's tree? If not, staging already has
+          # production's content.
+          MERGED=$(git merge-tree --write-tree origin/main production/main) || MERGED=conflict
+          STAGING_TREE=$(git rev-parse 'origin/main^{tree}')
+          if [ "$MERGED" = "$STAGING_TREE" ]; then
+            echo "Staging already has production's content. Nothing to pull back."
+            echo "behind=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "behind=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Sync production to staging (fast-forward)
+        if: steps.diff.outputs.behind == 'true'
+        run: |
+          # Refuse unless staging/main is an ancestor of production/main. If it
+          # isn't, the trunks have forked (staging advanced out of band while a
+          # production change was unsynced) and a fast-forward is unsafe.
+          # 
+          # The trunk-sync lock (trunk-sync-lock.yml) is what normally
+          # prevents this by freezing staging merges until the back-sync lands.
+          if ! git merge-base --is-ancestor origin/main production/main; then
+            echo "::error title=Back-sync blocked::staging main is not an ancestor of production/main."
+            exit 1
+          fi
+          git push origin production/main:refs/heads/main
+          echo "Fast-forwarded staging/main to production/main."

.github/workflows/trunk-sync-lock.yml

@@ -0,0 +1,69 @@
+name: Trunk sync lock
+
+# Posts a `trunk-synced` commit status to open PRs targeting staging `main`:
+# red while production is ahead of staging (a release hasn't been synced back
+# yet), green once they are in sync. 
+#
+# You should make `trunk-synced` a required status check on staging `main` 
+# to block merges onto a stale trunk during the release
+# window.
+#
+# This only gates PRs, not direct pushes. The back-sync bypasses this check
+# by pushing to staging `main` directly. If staging `main` also requires a pull
+# request, give the back-sync's identity ruleset-bypass so it can push. Never 
+# route the back-sync through a PR gated by this check, or it deadlocks.
+#
+# First-run note: GitHub treats a status check as "required" only once it has
+# been reported at least once. At setup time staging and production are
+# identical, so trigger this workflow once (push a PR or use the Run workflow
+# button) BEFORE adding `trunk-synced` to the required checks, so the first
+# status is green rather than missing.
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  workflow_run:
+    workflows: ["Sync from production"]
+    types: [completed]
+  repository_dispatch:
+    types: [prod-released]
+  workflow_dispatch: {}
+  schedule:
+    - cron: '*/30 * * * *'
+
+permissions:
+  contents: read
+  statuses: write
+  pull-requests: read
+
+jobs:
+  lock:
+    runs-on: ubuntu-latest
+    if: github.repository == 'sentdm/sent-dm-python-staging'
+    env:
+      PRODUCTION_REPO: sentdm/sent-dm-python
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Evaluate sync state and post status to open main PRs
+        run: |
+          set -euo pipefail
+          # Production is public; the built-in token reads it with no credential.
+          git remote add production "https://github.com/${PRODUCTION_REPO}.git"
+          git fetch --no-tags production main
+          if git merge-base --is-ancestor production/main HEAD; then
+            state=success; desc="staging main is in sync with production"
+          else
+            state=failure; desc="production is ahead — wait for the back-sync before merging"
+          fi
+          echo "trunk-synced => $state ($desc)"
+          shas=$(gh pr list --repo "$GITHUB_REPOSITORY" --base main --state open --json headRefOid --jq '.[].headRefOid')
+          if [ -z "$shas" ]; then echo "no open PRs targeting main"; exit 0; fi
+          for sha in $shas; do
+            gh api -X POST "repos/$GITHUB_REPOSITORY/statuses/$sha" \
+              -f state="$state" -f context="trunk-synced" -f description="$desc" >/dev/null
+            echo "posted trunk-synced=$state to $sha"
+          done