feat(examples): add PR bump preview example

examples/pr-bump-preview.yaml

@@ -0,0 +1,97 @@
+# Post (or update) a sticky comment on every PR with the version bump
+# that would happen if the PR were merged. Useful for catching unexpected
+# version bumps before merging.
+#
+# Trigger: pull_request_target so the workflow has pull-requests: write
+# permission. The job is gated to same-repo PRs only — fork PRs are
+# skipped because `cz bump` can render Jinja templates from the checked-out
+# workspace whenever `update_changelog_on_bump` is set in config, and we
+# don't want to execute fork-controlled templates with the workflow's
+# elevated permissions.
+name: PR bump preview
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  bump-preview:
+    if: >
+      ${{
+        github.event.pull_request.draft == false &&
+        github.event.pull_request.head.repo.full_name ==
+          github.event.pull_request.base.repo.full_name
+      }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out PR head
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          fetch-tags: true
+          # Defense in depth: don't write the workflow token to .git/config.
+          persist-credentials: false
+
+      - uses: commitizen-tools/setup-cz@main
+        with:
+          set-git-config: false
+
+      - name: Run cz bump --dry-run
+        id: dry-run
+        run: |
+          set +e
+          output="$(cz bump --dry-run --yes 2>&1)"
+          status=$?
+          set -e
+          {
+            echo "status=${status}"
+            echo "output<<__CZ_BUMP_PREVIEW__"
+            printf '%s\n' "${output}"
+            echo "__CZ_BUMP_PREVIEW__"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Build comment body
+        env:
+          STATUS: ${{ steps.dry-run.outputs.status }}
+          OUTPUT: ${{ steps.dry-run.outputs.output }}
+        run: |
+          {
+            # Hidden marker used by create-or-update-comment to find and
+            # replace the previous preview instead of stacking comments.
+            echo "<!-- commitizen-bump-preview -->"
+            echo "## 🔍 Commitizen bump preview"
+            echo ""
+            case "${STATUS}" in
+              0)
+                echo "Merging this PR will produce the following bump:"
+                echo ""
+                echo '```'
+                printf '%s\n' "${OUTPUT}"
+                echo '```'
+                ;;
+              21)
+                # NoneIncrementExit — see commitizen exit codes.
+                echo "No commits in this PR are eligible for a version bump."
+                ;;
+              *)
+                echo "⚠️ \`cz bump --dry-run\` exited with status \`${STATUS}\`:"
+                echo ""
+                echo '```'
+                printf '%s\n' "${OUTPUT}"
+                echo '```'
+                ;;
+            esac
+          } > comment.md
+
+      - uses: peter-evans/create-or-update-comment@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body-path: comment.md
+          body-includes: "<!-- commitizen-bump-preview -->"
+          edit-mode: replace