Skip to content

fix(pr-validation): make the breaking-change comment read as information - #907

Merged
bedatty merged 3 commits into
developfrom
fix/breaking-change-comment-clarity
Oct 15, 2026
Merged

bedatty merged 3 commits into
developfrom
fix/breaking-change-comment-clarity

Conversation

@bedatty

@bedatty bedatty commented Oct 15, 2026

Copy link
Copy Markdown
Contributor
Lerian

GitHub Actions Shared Workflows


Description

Rewrites the pull request comment posted by the breaking-change approval gate (#904). Observed on #906, the waiting comment opened with a siren and spent four paragraphs explaining itself, with no link anywhere.

A breaking change is often deliberate. A comment that shouts about it teaches people to scroll past it — which is the one thing a gate cannot afford.

Before — 18 lines, 0 links. After — 9 lines, 4 links:

Breaking change — needs a decision

f8d5506 carries a breaking change, so merging makes the next release a major version. That is often deliberate — this just asks someone to confirm it.

➡️ Approve or reject

Who can: @LerianStudio/g_github_devops

Gated by rule develop <- '*' · author acknowledgement missing

Not intended? Drop the ! and any BREAKING CHANGE: footer from the commits and push again — the gate clears itself. How this works

What changed:

  • Tone — "needs a decision" rather than "approval required", and the text says outright that the break is often intended.
  • Four links where there were none — the offending commit, the pending deployment, the reviewers, and the docs.
  • Who can approve — the reader's obvious next question, previously buried in Settings → Environments, now on the third line.
  • Everything else is a footnote — scope rule, acknowledgement state and how to undo the break fit in two <sub> lines: there for whoever needs them, out of the way of whoever does not.

The approved and rejected states shrank the same way (3 and 5 lines).

Reviewers render as links, never as @mentions. The pending deployment already notifies exactly those people; a mention would ping the whole team a second time for the same thing.

Affected: src/notify/breaking-change-approval-reporter (new reviewers, server-url, docs-url inputs), breaking-change-approval.yml (passes the reviewers through).

Type of Change

  • feat: New workflow or new input/output/step in an existing workflow
  • fix: Bug fix in a workflow (incorrect behavior, broken step, wrong condition)
  • perf: Performance improvement (e.g. caching, parallelism, reduced steps)
  • refactor: Internal restructuring with no behavior change
  • docs: Documentation only (README, docs/, inline comments)
  • ci: Changes to self-CI (workflows under .github/workflows/ that run on this repo)
  • chore: Dependency bumps, config updates, maintenance
  • test: Adding or updating tests
  • BREAKING CHANGE: Callers must update their configuration after this PR

Breaking Changes

None. The three new composite inputs are optional with defaults, and no workflow input, output or job name changes.

Testing

  • YAML syntax validated locally
  • Triggered a real workflow run on a caller repository using @this-branch or the beta tag
  • Verified all existing inputs still work with default values
  • Confirmed no secrets or tokens are printed in logs
  • Checked that unrelated workflows are not affected

All three comment states were rendered locally from the composite's own shell body and read end to end — that output is what the Description quotes.

actionlint, composite-schema, yamllint and typos clean. 66 wiring tests pass, including a new one that pins the four links and refuses a bare @mention creeping back.

Caller repo / workflow run: the comment this replaces is visible on #906.

Related Issues

The waiting comment opened with a siren and spent four paragraphs
explaining itself. A breaking change is often deliberate, and a comment
that shouts teaches people to scroll past it — which is the one thing a
gate cannot afford.

Now: what was found, a link straight to the decision, and who can make
it. Everything else — the scope rule, the acknowledgement state, how to
undo the break — is one small line at the bottom. Eighteen lines down to
nine.

Four things are links now where there were none: the offending commit,
the pending deployment, the reviewers, and the docs. "Who can approve
this" was the obvious next question and the answer was buried in
Environment settings nobody thinks to open.

Reviewers render as links, never as @mentions: the pending deployment
already notifies exactly those people.
@bedatty
bedatty requested a review from a team as a code owner October 15, 2026 20:17
@coderabbitai

coderabbitai Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository: LerianStudio/github-actions-shared-workflows/.coderabbit.yml
  • Review profile: ASSERTIVE
  • Plan: Essentials
  • Run ID: 0f4ee168-6496-47c2-b5e0-e0fa1d67ea3f
📥 Commits

Reviewing files that changed from the base of the PR and between 8db3d02 and 84a9db4.

📒 Files selected for processing: 3
  • src/validate/breaking-change-guard/test-workflow.py
  • src/validate/environment-protection/README.md
  • src/validate/environment-protection/action.yml

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Walkthrough

The workflow passes configured reviewers, or reviewers derived from base-branch CODEOWNERS, to the approval reporter. The reporter accepts reviewer and URL inputs, generates linked references, and updates its comments for waiting, approval, rejection, and unresolved decisions.

Changes

Breaking-change approval reporting

Layer / File(s) Summary
Reviewer inputs and links
.github/workflows/breaking-change-approval.yml, src/notify/breaking-change-approval-reporter/action.yml, src/notify/breaking-change-approval-reporter/README.md
The workflow passes configured reviewers or falls back to CODEOWNERS reviewers. The action adds reviewer, server URL, and documentation URL inputs, then builds linked reviewer names and a commit link.
Approval comment content
src/notify/breaking-change-approval-reporter/action.yml, src/notify/breaking-change-approval-reporter/README.md, src/validate/breaking-change-guard/test-workflow.py
Comments use revised wording for each decision state and compact gate context. Waiting comments include links and guidance. The README documents the content, and a test checks links and confirms that reviewer teams are not mentioned.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 84a9d

The change makes the breaking-change approval comments more informative, and reviewer information is now read reliably. No actionable merge-blocking risk remains in the supplied context.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 1 files. (2 skipped: 2 … Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly identifies the primary change: revising the breaking-change approval comment. It is concise and related to the changeset.
Description check Passed The description includes the required sections and explains the behavior changes, affected components, breaking-change status, testing performed, and the absence of a real caller workflow run. The Rel…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 1 files. (2 skipped: 2 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@lerian-studio lerian-studio added size/S PR changes 50–199 lines documentation Improvements or additions to documentation workflow Changes to one or more reusable workflow files notify Changes to notification composite actions (src/notify/) validate Changes to PR validation composite actions (src/validate/) composite Changes to any composite action manifest (src/**/*.yml) labels Oct 15, 2026
@lerian-studio

lerian-studio commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

🔍 PR Validation Summary

✅ PR Mergeable — no blocking failures

Check Status Blocking
Source Branch ✅ success yes
PR Title ✅ success yes
PR Description ✅ success yes
Breaking Change Guard ✅ success yes
Commit Signatures ✅ success yes
PR Size ✅ success no
Auto Labels ✅ success no
PR Metadata ✅ success no

🔍 View workflow run

@lerian-studio

lerian-studio commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

🔍 Lint Analysis

Check Files Scanned Status
YAML Lint 3 file(s) ✅ success
Action Lint 1 file(s) ✅ success
Pinned Actions 3 file(s) ✅ success
Markdown Link Check 2 file(s) ✅ success
Spelling Check 6 file(s) ✅ success
Shell Check 3 file(s) ✅ success
README Check 3 file(s) ✅ success
Composite Schema 2 file(s) ✅ success
Deployment Matrix no changes ⏭️ skipped

🔍 View full scan logs

@lerian-studio

lerian-studio commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

🛡️ CodeQL Analysis Results

Languages analyzed: actions

Found 1 issue(s): 1 Medium

Severity Rule File Message
🟡 Medium actions/untrusted-checkout/medium .github/workflows/breaking-change-approval.yml:260 Potential unsafe checkout of untrusted pull request on non-privileged workflow.

🔍 View full scan logs | 🛡️ Security tab

@lerian-studio

This comment has been minimized.

@lerian-studio lerian-studio added the review-ready Required checks passed — CodeRabbit is cleared to review label Oct 15, 2026
@coderabbitai

This comment has been minimized.

coderabbitai[bot]

This comment was marked as resolved.

Addresses the CodeRabbit review on #907.

environment-protection now reads back who the Environment is actually
gated by and exposes it, and the reporter prefers that over the
configured list. The two differ whenever the Environment already existed
or was edited since — and naming the wrong approvers is worse than
naming none, which is what the comment does when neither is available.

Also from the review:

  the `reviewers` description still said "rendered as GitHub mentions",
  written before the switch to links and never updated

  the README gave `docs-url` as "the gate's docs page" where .coderabbit.yml
  asks for input tables to match action.yml exactly

  the example's links all pointed at `(#)`

  the no-bare-mention test asserted one forbidden spelling, so it passed
  by accident and would keep passing if the mention were written any
  other way. It now checks that every `@${owner}/` sits inside Markdown
  link text — verified by injecting a bare mention and watching it fail
@lerian-studio

This comment has been minimized.

@coderabbitai

This comment has been minimized.

coderabbitai[bot]

This comment was marked as resolved.

… unknown

Addresses the second CodeRabbit review on #907.

The composite read the Environment twice: once for the protection rules,
once for the reviewers, with the second call swallowing failure. That
allowed a state of "protected, reviewers unknown" — and an empty
reviewer list is indistinguishable from "this Environment has none", so
the reporter fell back to the configured list and could name people who
cannot actually approve. Which is the very thing the previous commit set
out to fix.

The suggestion was to carry the read failure as a distinct status.
Removing the state is better than reporting it: one GET now answers both
questions, so either both are known or the step fails. It also drops a
call to an API this job already talks to twice.

Test pins it to exactly one read.
@lerian-studio lerian-studio added size/M PR changes 200–499 lines and removed size/S PR changes 50–199 lines labels Oct 15, 2026
@lerian-studio

Copy link
Copy Markdown
Contributor

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@bedatty
bedatty merged commit f94dba7 into develop Oct 15, 2026
48 checks passed
@github-actions
github-actions Bot deleted the fix/breaking-change-comment-clarity branch October 15, 2026 21:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

composite Changes to any composite action manifest (src/**/*.yml) documentation Improvements or additions to documentation notify Changes to notification composite actions (src/notify/) review-ready Required checks passed — CodeRabbit is cleared to review size/M PR changes 200–499 lines validate Changes to PR validation composite actions (src/validate/) workflow Changes to one or more reusable workflow files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants