ci(release): automate changelog promotion (2026.6.15.0-7E63)

Author: RealWhyKnot

.github/RELEASE_WORKFLOW.md

@@ -173,6 +173,19 @@ body via `gh release view --json body` and compares it byte-for-byte
 This catches GitHub-side normalisation surprises (which are rare but real)
 without letting a malformed body sit on the release indefinitely.
 
+## Changelog promotion
+
+The workflow promotes `## Unreleased` to the tagged section before the build
+so the embedded `CHANGELOG.md` matches the shipped release. Before promotion,
+it also replays the commit range since the previous stable tag into
+`## Unreleased`; that keeps the release notes correct when the tag job starts
+before the push-triggered changelog appender has committed back to main.
+
+After the release publishes, the stashed promoted `CHANGELOG.md` is committed
+back to main with GitHub's `createCommitOnBranch` mutation. This is the same
+verified-commit path used by `changelog-append.yml` and avoids the old
+promotion-branch PR flow.
+
 ## Failure modes + remediations
 
 | Symptom | Fix |
@@ -182,7 +195,7 @@ without letting a malformed body sit on the release indefinitely.
 | `Voice or internal-only-vocabulary patterns in release body` | Amend the offending commit subject. Or `[skip changelog]` it if the term is genuinely unavoidable. |
 | `Generate-ReleaseNotes.ps1 returned empty output` | The script failed silently or the slice was empty. Check the workflow log for warnings; if the slice really is empty, the empty-slice guard would have already thrown -- so this is a script bug. |
 | `Release body still differs after auto-correct` | A GitHub-side issue. Compare the input file in the runner artifacts against what `gh release view` returns. Often a trailing-whitespace or unicode-form difference. |
-| `Open promotion PR ... pull request create failed` | Repo setting `Allow GitHub Actions to create and approve pull requests` is OFF. The release publishes correctly; only the `## Unreleased` -> tagged-section promotion fails. Cosmetic; flip the setting if you want it. |
+| `createCommitOnBranch returned GraphQL errors` | Main moved after the workflow read its head, or GitHub rejected the file update. Re-run the workflow after main settles; if it repeats, inspect the GraphQL error text and push the same CHANGELOG.md promotion in the next source commit. |
 
 ## Updating the workflow
 

.github/scripts/Test-UpdateChangelog.ps1

@@ -39,6 +39,13 @@ function Assert-Contains {
     }
 }
 
+function Assert-NotContains {
+    param([string]$Text, [string]$Unexpected)
+    if ($Text.Contains($Unexpected)) {
+        throw "Expected text not to contain '$Unexpected'."
+    }
+}
+
 try {
     New-Item -ItemType Directory -Force -Path $TempRoot | Out-Null
     Push-Location $TempRoot
@@ -79,6 +86,13 @@ _No notable changes since the last release._
     $notes = (& $Updater -Mode Notes -ForVersion -Version 'v2026.6.4.0' -RepoRoot $TempRoot) -join "`n"
     Assert-Contains -Text $notes -Expected '**mesh:** Test changelog append'
 
+    & $Updater -Mode Promote -Version 'v2026.6.5.0' -RepoRoot $TempRoot -Repo 'RealWhyKnot/WKVRCProxy'
+    if ($LASTEXITCODE -ne 0) { throw "Update-Changelog empty Promote failed with exit code $LASTEXITCODE" }
+
+    $emptyPromoted = [System.IO.File]::ReadAllText((Join-Path $TempRoot 'CHANGELOG.md'), $Utf8NoBom)
+    Assert-Contains -Text $emptyPromoted -Expected '_No user-visible changes in this release._'
+    Assert-NotContains -Text $emptyPromoted -Unexpected 'Maintenance release'
+
     Write-Host 'Update-Changelog tests passed.'
 }
 finally {

.github/scripts/Test-WorkflowSyntax.ps1

@@ -115,6 +115,15 @@ if (Test-Path -LiteralPath $releaseWorkflow) {
     if ($releaseText -notmatch 'gh release create \$tag \$zip \$integrity') {
         $errors.Add('release.yml does not upload both the zip and integrity TSV assets.') | Out-Null
     }
+    if ($releaseText -match 'gh pr create|Open promotion PR|promote-changelog') {
+        $errors.Add('release.yml contains the deprecated changelog-promotion PR path.') | Out-Null
+    }
+    if ($releaseText -notmatch 'Preloading changelog entries from') {
+        $errors.Add('release.yml does not preload changelog entries before promotion.') | Out-Null
+    }
+    if ($releaseText -notmatch 'Commit promoted CHANGELOG\.md back to main \(verified\)') {
+        $errors.Add('release.yml does not commit promoted CHANGELOG.md back through the verified path.') | Out-Null
+    }
 }
 
 if ($errors.Count -gt 0) {

.github/scripts/Update-Changelog.ps1

@@ -394,10 +394,9 @@ if ($Mode -eq 'Promote') {
         if ($l -match '^\s*- ' -or $l -match '^###\s+') { $hasReal = $true; break }
     }
     if (-not $hasReal) {
-        # Empty section: the released version still gets an entry, just
-        # with a stub note. This keeps the heading -> release-page link
-        # alive so users browsing the changelog can click through.
-        $bodyLines = @('', '_Maintenance release; see commit log for details._', '')
+        # Empty section: the released version still gets an entry, but avoid
+        # describing the release type when there were no changelog bullets.
+        $bodyLines = @('', '_No user-visible changes in this release._', '')
     }
 
     # Build the new file:

.github/workflows/ci.yml

@@ -3,9 +3,8 @@ name: CI
 on:
   push:
     branches: [main]
-    # Negations re-include CHANGELOG.md so the auto-merged
-    # release-promotion PR clears its required status check (release.yml opens
-    # it after every tag push).
+    # Negations re-include CHANGELOG.md so changelog-only pulls and commits
+    # still exercise the required status check.
     paths-ignore:
       - '**.md'
       - '!CHANGELOG.md'

.github/workflows/release.yml

@@ -12,19 +12,16 @@ name: Release
 #
 # Changelog promotion: before the build runs, .github/scripts/Update-Changelog.ps1 renames the
 # "## Unreleased" heading in CHANGELOG.md to "## [vTAG] - DATE", linking
-# to this release. After the GitHub release is created the promoted file is pushed to a
-# release/promote-changelog-<tag> branch and a PR is opened with auto-merge so main eventually
-# carries the promotion (squashed in by github-actions[bot] once CI passes). Direct push does
-# not work on protected main: the dotnet-build-+-test required check is missing on bot pushes,
-# so branch protection rejects them.
+# to this release. After the GitHub release is created, the promoted file is
+# committed back to main through the verified createCommitOnBranch path so main
+# carries the same CHANGELOG.md that shipped in the release artifact.
 on:
   push:
     tags:
       - 'v*'
 
 permissions:
   contents: write
-  pull-requests: write   # release step opens a PR for the changelog promotion
 
 # Share a concurrency group with changelog-append so the appender can't run
 # during a release build and add entries to main's Unreleased that the release
@@ -45,8 +42,8 @@ jobs:
         with:
           fetch-depth: 0
           fetch-tags: true
-          # GITHUB_TOKEN is enough: the promotion-PR step pushes the bot's
-          # branch (not main) and uses gh to open + auto-merge the PR.
+          # GITHUB_TOKEN is enough for release publishing and the verified
+          # createCommitOnBranch mutations used after publish.
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Detect beta tag
@@ -89,7 +86,18 @@ jobs:
         env:
           GITHUB_REPOSITORY: ${{ github.repository }}
         run: |
-          ./.github/scripts/Update-Changelog.ps1 -Mode Promote -Version '${{ github.ref_name }}'
+          $tag = '${{ github.ref_name }}'
+          $prevTag = ''
+          $prevOutput = & git describe --tags --abbrev=0 --exclude '*-*' "$tag^" 2>$null
+          if ($LASTEXITCODE -eq 0 -and $prevOutput) {
+            $prevTag = [string]$prevOutput
+            Write-Host "Preloading changelog entries from $prevTag..$tag before promotion."
+            ./.github/scripts/Update-Changelog.ps1 -Mode Append -Range "$prevTag..$tag"
+          } else {
+            Write-Host "No previous stable tag found before $tag; promoting the existing Unreleased section."
+          }
+
+          ./.github/scripts/Update-Changelog.ps1 -Mode Promote -Version $tag
           # Stash the promoted file so we can re-apply it on main after the
           # release. Doing it now (before build.ps1 mutates the worktree) means
           # the bytes we push back to main are exactly what shipped in the exe.
@@ -402,66 +410,80 @@ jobs:
           fi
           echo "Hash append commit: $new_oid (verified)"
 
-      - name: Open promotion PR + enable auto-merge
+      - name: Commit promoted CHANGELOG.md back to main (verified)
         if: ${{ steps.beta.outputs.is_beta != 'true' }}
-        # We can't push directly to main: branch protection requires the
-        # "dotnet build + test" status check, which a bot push bypasses (so
-        # the push is rejected). Instead we open a PR off the tag and let
-        # auto-merge squash it once CI goes green. ci.yml has CHANGELOG.md
-        # carved out of paths-ignore so the required
-        # check actually runs on changelog-only PRs.
-        #
+        # Uses the same createCommitOnBranch pattern as changelog-append.yml
+        # and the wrapper-hash step so the commit lands verified on main.
         # Done last so a build/release failure doesn't leave a phantom
-        # "promotion PR open but never released" state.
+        # changelog promotion for a release that never shipped.
         shell: bash
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
           TAG_NAME: ${{ github.ref_name }}
         run: |
           set -euo pipefail
-          git config user.name  'github-actions[bot]'
-          git config user.email 'github-actions[bot]@users.noreply.github.com'
-
-          branch="release/promote-changelog-${TAG_NAME}"
-          git checkout -b "$branch"
 
           # Replay the stashed file (captured before build.ps1 ran) so the
           # bytes we put on main are exactly what shipped in the embedded exe.
           cp .changelog-stash/CHANGELOG.md CHANGELOG.md
 
-          if [[ -z "$(git status --porcelain CHANGELOG.md)" ]]; then
-            echo "Nothing to promote — main is already in promoted state."
+          main_oid=$(gh api "repos/$GITHUB_REPOSITORY/branches/main" --jq '.commit.sha')
+          main_changelog_blob=$(gh api "repos/$GITHUB_REPOSITORY/contents/CHANGELOG.md?ref=$main_oid" --jq '.sha' 2>/dev/null || echo "")
+          local_changelog_blob=$(git hash-object CHANGELOG.md)
+
+          if [[ "$main_changelog_blob" == "$local_changelog_blob" ]]; then
+            echo "main already carries the promoted changelog -- nothing to commit."
             exit 0
           fi
 
-          # [skip changelog] keeps changelog-append from re-bulleting this commit
-          # if the squash trigger ever races past the bot-actor filter.
-          git add CHANGELOG.md
-          git commit -m "docs(changelog): promote Unreleased -> ${TAG_NAME} [skip changelog]"
-          git push origin "$branch"
-
-          pr_body="Promotion PR opened by .github/workflows/release.yml after publishing **${TAG_NAME}**. Mirrors the embedded \`CHANGELOG.md\` that shipped inside the exe back onto \`main\` so the next push starts with a fresh \`## Unreleased\` section. Auto-merge enabled -- will squash once \`dotnet build + test\` passes."
-          if pr_url="$(gh pr create \
-            --base main \
-            --head "$branch" \
-            --title "docs(changelog): promote Unreleased -> ${TAG_NAME}" \
-            --body "$pr_body" \
-            2>pr-create.err)"; then
-            echo "Opened: $pr_url"
-
-            # --auto queues the merge; it actually fires once required checks pass.
-            # Use --subject so the squash commit subject keeps the [skip changelog]
-            # marker (the appender also filters by bot actor, but belt-and-braces).
-            if ! gh pr merge "$pr_url" \
-              --auto \
-              --squash \
-              --delete-branch \
-              --subject "docs(changelog): promote Unreleased -> ${TAG_NAME} [skip changelog]" \
-              2>pr-merge.err; then
-              cat pr-merge.err >&2
-              echo "::warning::Release published, but auto-merge could not be enabled for promotion PR $pr_url."
-            fi
-          else
-            cat pr-create.err >&2
-            echo "::warning::Release published, but GitHub Actions could not create the promotion PR. Branch '$branch' was pushed; promote CHANGELOG.md manually."
+          changelog_b64=$(base64 -w 0 CHANGELOG.md)
+          headline="docs(changelog): promote Unreleased -> ${TAG_NAME} [skip changelog]"
+          body=$(printf '%s\n%s' \
+            "Promotes the CHANGELOG.md section published for ${TAG_NAME}." \
+            'Mirrors the file that shipped in the release artifact back to main.')
+
+          payload=$(jq -n \
+            --arg repo "$GITHUB_REPOSITORY" \
+            --arg branch "main" \
+            --arg headline "$headline" \
+            --arg body "$body" \
+            --arg oid "$main_oid" \
+            --arg changelog "$changelog_b64" \
+            '{
+              query: "mutation($input: CreateCommitOnBranchInput!) { createCommitOnBranch(input: $input) { commit { oid url } } }",
+              variables: {
+                input: {
+                  branch: { repositoryNameWithOwner: $repo, branchName: $branch },
+                  message: { headline: $headline, body: $body },
+                  fileChanges: {
+                    additions: [
+                      { path: "CHANGELOG.md", contents: $changelog }
+                    ]
+                  },
+                  expectedHeadOid: $oid
+                }
+              }
+            }')
+
+          response=$(printf '%s' "$payload" | gh api graphql --input -)
+          echo "$response" | jq .
+
+          if echo "$response" | jq -e '.errors // empty' >/dev/null; then
+            echo "::error::createCommitOnBranch returned GraphQL errors"
+            exit 1
+          fi
+
+          new_oid=$(echo "$response" | jq -r '.data.createCommitOnBranch.commit.oid')
+          if [[ -z "$new_oid" || "$new_oid" == "null" ]]; then
+            echo "::error::createCommitOnBranch did not return a commit oid"
+            exit 1
+          fi
+
+          verified=$(gh api "repos/$GITHUB_REPOSITORY/commits/$new_oid" --jq '.commit.verification.verified')
+          if [[ "$verified" != "true" ]]; then
+            echo "::error::Commit $new_oid is not verified (got: $verified)"
+            gh api "repos/$GITHUB_REPOSITORY/commits/$new_oid" --jq '.commit.verification'
+            exit 1
           fi
+          echo "Changelog promotion commit: $new_oid (verified)"

CHANGELOG.md

@@ -11,15 +11,15 @@ Release entries are listed newest first. This changelog starts with the first pu
 
 ## Unreleased
 
-### Fixed
-- **vrc:** Arm native fallback on playback failure (4c506cd)
-- **updater:** Recover release update flow (a70a452)
+_No notable changes since the last release._
 
 ---
 
 ## [v2026.6.15.0](https://github.com/RealWhyKnot/WKVRCProxy/releases/tag/v2026.6.15.0) - 2026-06-15
 
-_Maintenance release; see commit log for details._
+### Fixed
+- **vrc:** Arm native fallback on playback failure (4c506cd)
+- **updater:** Recover release update flow (a70a452)
 
 ---