fix(ci): changelog workflow must open a PR, not push to protected master (#68)

* fix(ci): deliver generated CHANGELOG.md via PR, not a direct push

The direct `git push origin HEAD:master` was rejected by the repository
ruleset ("Changes must be made through a pull request") — master is
protected, so the CI bot cannot push to it.

Replace the manual commit/push step with peter-evans/create-pull-request
(SHA-pinned, v8.1.1): generation + `test -s` verification stay; the
action pushes a fixed `automation/update-changelog` branch and opens or
updates a PR, and no-ops when nothing changed. Add `pull-requests: write`.

This makes the generated changelog comply with the same PR-only
governance the rest of the repo uses, with no privileged bypass on the
protected branch.

* docs(ci): document why GITHUB_TOKEN is intentional for the changelog PR

Copilot flagged that GITHUB_TOKEN-created PRs don't trigger CI/Sonar and
"may be unmergeable if branch protection requires them". Verified the
master ruleset: it requires only 1 approving review, NOT status checks.
So the changelog PR is mergeable after a human review; running CI on a
generated CHANGELOG.md is low value. Add an inline rationale so a PAT/App
token isn't swapped in later (a managed elevated secret for no benefit).
Comment-only.

Author: mambax7

.github/workflows/changelog.yml

@@ -12,13 +12,14 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: write          # push the automation branch
+  pull-requests: write     # open/update the changelog PR
 
 concurrency:
   # Fixed group (not keyed by ref): release-tag and manual-dispatch runs
-  # both push the default branch. Queue them (cancel-in-progress: false) so
-  # each run finishes and persists its CHANGELOG.md instead of a later run
-  # cancelling an in-flight one mid-push.
+  # both target the same automation branch / PR. Queue them
+  # (cancel-in-progress: false) so each run finishes and updates the PR
+  # instead of a later run cancelling an in-flight one mid-update.
   group: changelog
   cancel-in-progress: false
 
@@ -54,18 +55,33 @@ jobs:
       - name: Verify changelog was generated at the repo root
         run: test -s CHANGELOG.md
 
-      - name: Commit CHANGELOG.md if changed
-        run: |
-          # Stage first, then compare the index to HEAD. Plain
-          # `git diff --quiet` ignores untracked files, so on the first
-          # run (CHANGELOG.md brand-new) it falsely reported "no change"
-          # and the file was never committed. --cached sees new files too.
-          git add CHANGELOG.md
-          if git diff --cached --quiet -- CHANGELOG.md; then
-            echo "CHANGELOG.md unchanged — nothing to commit."
-            exit 0
-          fi
-          git config user.name  "xoops-ci"
-          git config user.email "ci@xoops.org"
-          git commit -m "docs(changelog): regenerate CHANGELOG.md [skip ci]"
-          git push origin HEAD:${{ github.event.repository.default_branch }}
+      - name: Open/update changelog pull request
+        # master is protected (changes must go through a PR), so the bot
+        # cannot push directly. Push a fixed automation branch and let this
+        # action open or update the PR; it no-ops when nothing changed.
+        # Pinned to a commit SHA (supply-chain hardening); comment tracks the tag.
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          # Intentional: GITHUB_TOKEN-created PRs do not trigger CI/Sonar
+          # (GitHub recursion-prevention). That is fine here — master's
+          # ruleset requires only 1 approving review, not status checks, and
+          # CI on a generated CHANGELOG.md is low value. A maintainer reviews
+          # and merges the changelog PR. Do not swap in a PAT/App token just
+          # to run checks — it adds a managed elevated secret for no benefit.
+          token: ${{ secrets.GITHUB_TOKEN }}
+          base: ${{ github.event.repository.default_branch }}
+          branch: automation/update-changelog
+          delete-branch: true
+          add-paths: CHANGELOG.md
+          commit-message: "docs(changelog): regenerate CHANGELOG.md"
+          committer: "xoops-ci <ci@xoops.org>"
+          author: "xoops-ci <ci@xoops.org>"
+          title: "docs(changelog): regenerate CHANGELOG.md"
+          body: |
+            Regenerated `CHANGELOG.md` from the commit history via
+            `git-cliff` (config: `cliff.toml`).
+
+            Opened by the **Changelog** workflow — `master` is protected
+            (changes must go through a PR), so the generated file is
+            delivered this way instead of a direct push. Safe to merge
+            once green; it only touches `CHANGELOG.md`.