feat: add revision guard draft conversion flow

[NssGourav]

Description:

Implement the first event-driven Revision Guard slice for the Python SDK review flow.

This PR handles the CHANGES_REQUESTED path by converting a ready PR back to draft and cleaning up managed review/queue labels, while keeping the implementation lightweight and flexible around evolving label logic.

• Add a revision-guard review-event workflow for pull_request_review.submitted
• Convert PRs to draft when a review is submitted with changes_requested
• Remove managed review/queue labels during that transition
• Keep managed-label handling configurable instead of hardcoding current label behavior
• Add focused tests for bot-authored PRs, already draft PRs, managed-label cleanup, and configurable labels

Related issue(s):

Part of #2264

Notes for reviewer:

This PR intentionally covers only the event-driven draft-conversion slice of Revision Guard.

It does not include the broader cron side requirements checklist/reporting work. The scope here is limited to the minimal to the aligned direction:

• CHANGES_REQUESTED -> draft
• managed label cleanup
• no extra notification-style reason comment

Validation run locally:

• node --test .github/scripts/revision-guard/index.test.js

Checklist

• Documented (Code comments, README, etc.)
• Tested (unit, integration, etc.)

[aceppaluni]

Hi @NssGourav Can you link the issue this is solving?

[NssGourav]

Hi @NssGourav Can you link the issue this is solving?

Thanks, this PR is intended to solve part of #2264.

More specifically, it implements the event driven CHANGES_REQUESTED -> draft + managed label cleanup slice from the Revision Guard direction we aligned on, while keeping the broader cron side checklist,requirements work separate.

I’ll update the PR description to link it clearly to 2264.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a revision-guard GitHub Action: helpers for managed-label parsing, draft/bot detection and conversion, label filtering/removal, a handler that converts PRs to draft on "changes_requested" reviews and removes managed labels, accompanying tests, and a workflow that triggers the handler.

Changes

Revision Guard Automation

Layer / File(s)	Summary
Label constants and draft utilities .github/scripts/revision-guard/helpers/constants.js, .github/scripts/revision-guard/helpers/draft.js	Defines DEFAULT_MANAGED_LABELS and parseManagedLabels; implements isBotAuthor, isDraft, and convertToDraft (GraphQL mutation).
Label filtering and removal .github/scripts/revision-guard/helpers/labels.js	Implements getManagedLabels() (env parsing), getPresentManagedLabels(prLabels, managedLabels) (normalize/filter), and removeManagedLabels(github, {owner,repo,issueNumber,labels}) which calls github.rest.issues.removeLabel and ignores 404s.
Helper module aggregation .github/scripts/revision-guard/helpers/index.js	Re-exports constants, draft, and label helper functions from the helpers directory.
Revision guard handler orchestration .github/scripts/revision-guard/index.js	Exports async revisionGuard({github,context,core}) handler that gates on changes_requested reviews, skips bots/drafts, converts PRs to draft, computes present managed labels, and removes them while logging progress.
Tests and workflow trigger .github/scripts/revision-guard/index.test.js, .github/workflows/revision-guard.yml	Adds tests covering draft conversion, bot skip, draft skip, and env-configurable managed labels; workflow triggers on pull_request_review submitted events with changes_requested, checks out .github/scripts at base SHA, and runs the handler.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add revision guard draft conversion flow' accurately summarizes the main change—adding a workflow that converts PRs to draft when a changes_requested review is received.
Description check	✅ Passed	The description clearly explains the revision guard feature, implementation scope, managed label handling, and includes test coverage details, all of which align with the changeset.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e411f76b-0725-4f2b-9c8d-78c3834a5b64

📥 Commits

Reviewing files that changed from the base of the PR and between 312db19 and 966864c.

📒 Files selected for processing (7)

• .github/scripts/revision-guard/helpers/constants.js
• .github/scripts/revision-guard/helpers/draft.js
• .github/scripts/revision-guard/helpers/index.js
• .github/scripts/revision-guard/helpers/labels.js
• .github/scripts/revision-guard/index.js
• .github/scripts/revision-guard/index.test.js
• .github/workflows/revision-guard.yml

[darshit2308]

All the 3 coderabbit suggestions are blockers i think, and must be resolved before merging.
I have left another bug in the inline comments, please go through them.
Rest looks good to me.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: cb898582-3029-4601-9b4a-81d2090aea96

📥 Commits

Reviewing files that changed from the base of the PR and between 966864c and ef4d924.

📒 Files selected for processing (4)

• .github/scripts/revision-guard/helpers/constants.js
• .github/scripts/revision-guard/index.js
• .github/scripts/revision-guard/index.test.js
• .github/workflows/revision-guard.yml

[NssGourav]

Community Workflow Overview

Hey everyone 👋

Just wanted to leave a quick explanation of how this PR behaves end-to-end since the workflow + script interaction can be a little difficult to follow at first glance.

This change is mainly focused on improving the contributor review flow when a reviewer requests changes on a PR.

---

What Happens When "Request Changes" Is Submitted

When a reviewer clicks Request Changes, GitHub triggers the pull_request_review.submitted event, which starts the revision-guard.yml workflow.

The workflow then goes through the following steps:

1. Validation & Safety Checks

   • Confirms the webhook payload is valid
   • Ensures the review state is actually changes_requested
   • Skips bot authored PRs
   • Skips PRs that are already in draft mode

   If any of these checks fail, the workflow exits safely without making changes.

2. Convert PR Back to Draft

   • The PR is converted back to Draft using a GraphQL mutation.
   • This is the primary action of the workflow.

3. Cleanup Managed Labels

   After draft conversion, the workflow removes labels related to merge/review readiness, including:

   • queue:junior-committer
   • queue:committers
   • queue:maintainers
   • status: ready-to-merge
   • status: failed checks
   • open to community review

   If label cleanup fails for any reason, the error is logged but the workflow itself does not fail since the important draft conversion already completed.

---

Cases That Are Intentionally Skipped

Situation	Behavior
Review is approved or commented	No action taken
PR author is a bot	Skipped
PR is already draft	Skipped
Invalid webhook payload	Exits safely with logs

---

Configurability

Additional labels can be managed through the REVISION_GUARD_MANAGED_LABELS env var. Custom labels are merged with the defaults, not replacing them, so the default cleanup behavior is always preserved.

---

Validation

All the above cases are covered by unit tests and validated locally:

node --test .github/scripts/revision-guard/index.test.js

▶ revision-guard index
  ✔ converts a ready PR to draft and removes only managed labels
  ✔ skips bot-authored PRs
  ✔ skips already-draft PRs
  ✔ uses configurable managed labels and still removes defaults
✔ revision-guard index — 4 pass, 0 fail

Happy to answer any questions on the design!

[NssGourav]

Fork testing completed successfully in NssGourav/hiero-sdk-python.

I followed the fork-testing flow by deploying the revision-guard workflow to my fork main, then created a separate dummy PR to trigger the real pull_request_review.submitted event safely.

During testing, I found that GITHUB_TOKEN cannot convert a PR to draft through GitHub’s GraphQL convertPullRequestToDraft mutation because it fails with Resource not accessible by integration. I updated the workflow to use REVIEWBOT_TOKEN when available, with GITHUB_TOKEN as a fallback, and added a clear log hint for missing token configuration.

Final validation:

• Test PR: Test token-backed revision guard draft conversion NssGourav/hiero-sdk-python#9
• Workflow run: https://github.com/NssGourav/hiero-sdk-python/actions/runs/27095387555
• Submitted a CHANGES_REQUESTED review from another account.
• Confirmed the Revision Guard - Review Events / guard job passed.
• Confirmed the test PR was converted to draft.

Relevant workflow logs:
Converted PR #9 to draft.
No managed labels to remove for PR #9.

[exploreriii]

Hi @NssGourav
I think this is pretty good, thank you for polishing this up.

I think the next challenge will be making decisions on how to organise this given the .github surface area will likely grow, and we've already experienced some pains when code is duplicated or it grew overly independently. We do need to ensure a good test surface too, this may require a little refactoring. i think these are the primary concerns.

I'm not happy with pushing the idea of drafting a pr unless it is realistically feasible, in whcih case we can be open to alternatives.

[NssGourav]

I’ve addressed the draft-conversion feasibility and CI test coverage feedback in the latest push: draft conversion is now optional/best-effort with REVIEWBOT_TOKEN, managed-label cleanup remains the reliable baseline, and revision-guard tests now run through a dedicated workflow.

I still need to follow up on the remaining structure/shared helper feedback and the reviewer permission gating discussion.

[exploreriii]

Hi @NssGourav
You have written some good code but this PR is not feasible in its current form. We should confirm the current approach does not work, consider archiving the issue, or attempt to resolve it in a different way

[exploreriii]

Note you are using the trigger pull_request_review https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows

Because of that trigger, PR's from a fork to this repo will operate with reduced permissions.
Passing reviewbot token here will not necessarily work, since i believe it will only allow you to pass the github token with read only permissions due to this trigger

https://github.com/orgs/community/discussions/55940

As a result, the things you are wanting to do are not feasible through this approach

As previously suggested, i think, a cron job may be able to do something similar to your intention

But if its not possible, we should argue for archiving the issue

[NssGourav]

i get that, and it's true , that's not an easy thing to do..

[exploreriii]

You are triggering the workflow to run based on fork PRs to this repo, but you never test it in these cases. So, the tests won't run in the majority of cases

The repo already has a single JS test setup: Jest, rooted at .github/scripts with testMatch: tests/jest/**/*.test.js, executed by test-scripts.yml. Conforming to this would be ideal

[NssGourav]

Hi @NssGourav You have written some good code but this PR is not feasible in its current form. We should confirm the current approach does not work, consider archiving the issue, or attempt to resolve it in a different way

Hi @exploreriii thanks for the appreciation of the work, i understand what you say regarding the current approach and i think now this issue is not a medium level task, through our convo i see that it has escalated to Advance task, i have to observe try different methods to solve it.

[github-actions]

Hi @NssGourav,

This pull request has had no activity for 10 days. Are you still working on it?
To keep the PR active, you can:

• Push a new commit.
• Comment /working on the linked issue (not this PR).

If you're no longer working on this, please comment /unassign on the linked issue to release it for others. Otherwise, this PR may be closed due to inactivity.

Reach out on discord or join our office hours if you need assistance.

• Discord
• Office Hours

From the Python SDK Team