From aefbc990198f826bbf6990b94e023ad6a4215124 Mon Sep 17 00:00:00 2001
From: Linh Chu <linh.chu@cockroachlabs.com>
Date: Tue, 24 Mar 2026 21:15:03 -0400
Subject: [PATCH] pr-changelog-check: Add reusable PR changelog check workflow

This workflow provides a reusable way to validate CHANGELOG.md changes
in pull requests. It runs the changelog-check action in diff mode to
detect breaking changes and posts a comment on the PR indicating whether
breaking changes are present. The workflow updates existing comments
rather than creating duplicates, and fails if the changelog format is
invalid.

Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>
---
 .github/workflows/pr-changelog-check.yml | 99 ++++++++++++++++++++++++
 CHANGELOG.md                             |  2 +
 2 files changed, 101 insertions(+)
 create mode 100644 .github/workflows/pr-changelog-check.yml

diff --git a/.github/workflows/pr-changelog-check.yml b/.github/workflows/pr-changelog-check.yml
new file mode 100644
index 0000000..e7a15ae
--- /dev/null
+++ b/.github/workflows/pr-changelog-check.yml
@@ -0,0 +1,99 @@
+name: PR Changelog Check
+
+on:
+  workflow_call:
+    inputs:
+      base-ref:
+        description: 'Base branch reference for diff comparison'
+        required: true
+        type: string
+      pr-number:
+        description: 'Pull request number'
+        required: true
+        type: number
+    outputs:
+      has_breaking:
+        description: 'Whether the PR contains breaking changes'
+        value: ${{ jobs.pr-changelog-check.outputs.has_breaking }}
+
+jobs:
+  pr-changelog-check:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: write
+    outputs:
+      has_breaking: ${{ steps.changelog-check.outputs.has_breaking }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Needed for diff mode
+          persist-credentials: false
+
+      # Resolve the ref of this reusable workflow so we can checkout the
+      # actions repo at the exact version the caller requested.
+      - name: Get workflow ref
+        id: workflow-ref
+        uses: cockroachdb/actions/get-workflow-ref@v0
+        with:
+          workflow_name: cockroachdb/actions/.github/workflows/pr-changelog-check.yml
+
+      - name: Checkout actions repo
+        uses: actions/checkout@v6
+        with:
+          repository: cockroachdb/actions
+          ref: ${{ steps.workflow-ref.outputs.ref }}
+          path: actions-repo
+          persist-credentials: false
+
+      - name: Validate Changelog
+        id: changelog-check
+        uses: ./actions-repo/changelog-check
+        with:
+          check-mode: diff
+          base-ref: ${{ inputs.base-ref }}
+
+      - name: Find existing changelog comments
+        id: find-comments
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          cids="$(gh api "repos/${GITHUB_REPOSITORY}/issues/${{ inputs.pr-number }}/comments" \
+            --jq '[.[] | select((.body | contains("<!-- changelog-change-status -->")) and .user.login == "github-actions[bot]") | .id] | join(" ")')"
+
+          echo "comment-ids=$cids" >> "$GITHUB_OUTPUT"
+
+      - name: Comment on breaking changes
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ inputs.pr-number }}
+          COMMENT_IDS: ${{ steps.find-comments.outputs.comment-ids }}
+          HAS_BREAKING: ${{ steps.changelog-check.outputs.has_breaking }}
+        run: |
+          set -euo pipefail
+          marker='<!-- changelog-change-status -->'
+
+          if [[ "$HAS_BREAKING" == "true" ]]; then
+            msg='**This PR contains breaking changes.** Please ensure this is intentional and properly documented.'
+          else
+            msg='No breaking changes detected.'
+          fi
+
+          body_content="${marker}"$'\n'"${msg}"
+
+          if [[ -n "${COMMENT_IDS:-}" ]]; then
+            # Update all existing comments with the marker
+            for cid in $COMMENT_IDS; do
+              gh api -X PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${cid}" --raw-field "body=${body_content}"
+            done
+          else
+            # Create a new comment if none exist
+            gh api -X POST "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" --raw-field "body=${body_content}"
+          fi
+
+      - name: Fail if invalid
+        if: steps.changelog-check.outputs.is_valid != 'true'
+        run: |
+          echo "::error::CHANGELOG validation failed. Please fix the CHANGELOG.md format."
+          exit 1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c08c60..c1d4cd9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,8 @@ Breaking changes are prefixed with "Breaking Change: ".
 
 ### Added
 
+- `pr-changelog-check` workflow: reusable workflow that validates CHANGELOG.md
+  changes in PRs, detects breaking changes, and posts status comments.
 - `autotag-from-changelog` now exposes `tag_created` and `tag` outputs so
   callers can react to whether a new tag was pushed.
 - `expect_step_output` test helper for asserting GitHub Actions step outputs.