Update Changelog on new tag

.github/workflows/config-reference.yaml

@@ -1,8 +1,8 @@
 ---
 # Automates step 8 of the release process in CONTRIBUTING.md: when a release
-# tag is pushed, regenerate the versioned NativeLink configuration reference
-# (web/apps/docs) from that tag and open a PR against main with auto-merge
-# enabled.
+# tag is pushed, regenerate the canonical changelog plus the versioned
+# NativeLink configuration reference (web/apps/docs) from that tag and open a PR
+# against main with auto-merge enabled.
 #
 # The generator needs the tag to exist (it builds the config schema from a
 # `git worktree` of the tag), which is why this runs on tag push rather than
@@ -13,9 +13,9 @@
 #   - A `WORKFLOW_PR_TOKEN` secret (fine-grained PAT or GitHub App token with
 #     contents:write + pull-requests:write). PRs created with the default
 #     GITHUB_TOKEN do not trigger CI workflows, so required checks would never
-#     report and auto-merge would never fire. Without the secret this workflow
-#     still opens the PR; it just needs a human to merge it.
-name: Regenerate config reference
+#     report and auto-merge would never fire. Some repositories also block the
+#     default GITHUB_TOKEN from creating pull requests at all.
+name: Regenerate release docs
 
 on:
   push:
@@ -26,7 +26,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Existing release tag to regenerate the config reference for (e.g. v1.6.1).'
+        description: 'Existing release tag to regenerate release docs for (e.g. v1.6.1).'
         required: true
         type: string
 
@@ -61,6 +61,25 @@ jobs:
           fi
           echo "tag=${TAG}" >> "${GITHUB_OUTPUT}"
 
+      - name: Validate PR token
+        env:
+          WORKFLOW_PR_TOKEN: ${{ secrets.WORKFLOW_PR_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [[ -n "${WORKFLOW_PR_TOKEN}" ]]; then
+            exit 0
+          fi
+
+          cat >> "${GITHUB_STEP_SUMMARY}" <<'EOF'
+          ## Missing WORKFLOW_PR_TOKEN
+
+          This workflow must push the generated branch and open a pull request
+          with a token that can trigger normal CI. Add a repository secret named
+          `WORKFLOW_PR_TOKEN` with `contents:write` and `pull-requests:write`.
+          EOF
+          echo "::error::WORKFLOW_PR_TOKEN is required; the default GITHUB_TOKEN cannot reliably create CI-triggering pull requests."
+          exit 1
+
       - name: Checkout
         uses: >- # v6.0.2
           actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
@@ -69,6 +88,7 @@ jobs:
           # release tag itself, so it needs the full history and all tags.
           ref: main
           fetch-depth: 0
+          token: ${{ secrets.WORKFLOW_PR_TOKEN }}
 
       - name: Prepare Worker
         uses: ./.github/actions/prepare-nix
@@ -82,41 +102,54 @@ jobs:
             bun install && bun --filter @nativelink/docs gen:config-reference ${{ steps.resolve.outputs.tag }}
           "
 
+      - name: Regenerate changelog
+        env:
+          TAG: ${{ steps.resolve.outputs.tag }}
+        run: |
+          nix develop --impure --command bash -c '
+            set -euo pipefail
+            # End the range at the release tag so post-tag commits on main do
+            # not become a duplicate section for the same version.
+            ROOT_COMMIT=$(git rev-list --max-parents=0 "${TAG}" | tail -1)
+            git cliff --tag "${TAG}" --output CHANGELOG.md "${ROOT_COMMIT}..${TAG}"
+          '
+
       - name: Lint generated docs
         run: |
           nix develop --impure --command bash -c "
+            vale CHANGELOG.md
             vale web/apps/docs/content/docs/reference/nativelink-config/*.mdx
           "
 
       - name: Open auto-merge PR
         env:
-          GH_TOKEN: ${{ secrets.WORKFLOW_PR_TOKEN || github.token }}
+          GH_TOKEN: ${{ secrets.WORKFLOW_PR_TOKEN }}
           TAG: ${{ steps.resolve.outputs.tag }}
         run: |
           set -euo pipefail
           # The generator also creates new untracked pages (the previous
           # latest release gets its own versioned page), so check the whole
           # docs tree, not just tracked modifications.
-          if [[ -z "$(git status --porcelain -- web/apps/docs)" ]]; then
-            echo "Config reference already up to date for ${TAG}; nothing to do."
+          if [[ -z "$(git status --porcelain -- CHANGELOG.md web/apps/docs)" ]]; then
+            echo "Release docs already up to date for ${TAG}; nothing to do."
             exit 0
           fi
 
           BRANCH="docs/config-reference-${TAG}"
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git switch -c "${BRANCH}"
-          git add web/apps/docs
-          git commit -m "docs(config-reference): regenerate for NativeLink ${TAG}"
-          git push --force origin "${BRANCH}"
+          git add CHANGELOG.md web/apps/docs
+          git commit -m "docs(release): regenerate for NativeLink ${TAG}"
+          git push --force-with-lease origin "HEAD:${BRANCH}"
 
           PR_URL=$(gh pr list --head "${BRANCH}" --base main --state open --json url --jq '.[0].url // empty')
           if [[ -z "${PR_URL}" ]]; then
             PR_URL=$(gh pr create \
               --base main \
               --head "${BRANCH}" \
-              --title "docs(config-reference): regenerate for NativeLink ${TAG}" \
-              --body "Automated regeneration of the NativeLink configuration reference for ${TAG} (CONTRIBUTING.md release step 8). Generated by the \`${{ github.workflow }}\` workflow.")
+              --title "docs(release): regenerate for NativeLink ${TAG}" \
+              --body "Automated regeneration of the NativeLink changelog and configuration reference for ${TAG} (CONTRIBUTING.md release step 8). Generated by the \`${{ github.workflow }}\` workflow.")
           fi
           echo "PR: ${PR_URL}"
 

CONTRIBUTING.md

@@ -399,7 +399,7 @@ most automatically generated changelogs provide.
    - `Cargo.toml`
    - `nativelink-*/Cargo.toml`
 
-2. Run `git cliff --tag=0.x.y > CHANGELOG.md` to update the changelog. You might
+2. Run `git cliff --tag=v0.x.y > CHANGELOG.md` to update the changelog. You might
    need to make manual adjustments to `cliff.toml` if `git-cliff` doesn't put a
    commit in the right subsection.
 
@@ -437,22 +437,26 @@ most automatically generated changelogs provide.
    git push upstream v0.x.y
    ```
 
-8. Regenerate the latest config reference docs now that the upstream tag exists.
+8. Regenerate the release docs now that the upstream tag exists.
    Pushing the tag upstream triggers the
-   [`Regenerate config reference`](.github/workflows/config-reference.yaml)
-   workflow, which regenerates the docs and opens a PR against `main` with
-   auto-merge enabled. Check that the PR appeared and merged; if the workflow
-   failed, either re-run it from `Actions → Regenerate config reference → Run
-   workflow` (entering the tag) or fall back to the manual procedure below.
-
-   Passing the new tag updates `web/apps/docs/lib/config-versions.ts`, which
+   [`Regenerate release docs`](.github/workflows/config-reference.yaml)
+   workflow, which regenerates `CHANGELOG.md` plus the config reference docs and
+   opens a PR against `main` with auto-merge enabled. Check that the PR appeared
+   and merged; if the workflow failed, either re-run it from `Actions →
+   Regenerate release docs → Run workflow` (entering the tag) or fall back to the
+   manual procedure below.
+
+   Passing the new tag updates `CHANGELOG.md` from the exact commit range ending
+   at the tag. It also updates `web/apps/docs/lib/config-versions.ts`, which
    determines the latest version shown in the docs UI, rewrites
    `web/apps/docs/content/docs/reference/nativelink-config/index.mdx` from that
    tag, and creates a versioned page for the previous latest release. You do not
    need to regenerate every historical version.
 
    ```bash
    git fetch --tags upstream
+   ROOT_COMMIT=$(git rev-list --max-parents=0 v0.x.y | tail -1)
+   git cliff --tag v0.x.y --output CHANGELOG.md "${ROOT_COMMIT}..v0.x.y"
    cd web
    bun --filter @nativelink/docs gen:config-reference v0.x.y
    cd ..
@@ -465,7 +469,7 @@ most automatically generated changelogs provide.
    the generated docs update:
 
    ```bash
-   nix develop -c vale web/apps/docs/content/docs/reference/nativelink-config/*.mdx
+   nix develop -c vale CHANGELOG.md web/apps/docs/content/docs/reference/nativelink-config/*.mdx
    ```
 
 9. The images for the release are now being created. Go to the