[Advanced]: Add Issue Moderator Workflows

[aceppaluni]

🧑‍🔬 Advanced Issue

Welcome! This is an Advanced Issue touching core SDK architecture.

It is designed for expert contributors who have demonstrated deep architectural understanding and a proven track record of high-quality contributions.

🐞 Problem Description

Currently community users are creating issues. While this is good, we would like to triage these issues before allowing contributors take them on.

We propose to add Issue Moderator Workflows to the Python SDK to assist our team with triaging and approving issues that are needed to improve the SDK.

Workflows should be added to the .github/workflows directory.

🛠️ Implementation Notes

Ideally, there will be two work flows.

The first workflow will take the issue and lock it from interaction until a team member is available to take a look.

The second workflow should correspond to the "approved" label and will run once this label is added. This opens the issue to interaction and allows a contributor to request assignment.

🧠 Advanced Contributors — Prerequisites & Expectations

Caution

Advanced issues are the highest-risk work in this project. We will reject PRs that do not meet these standards.

🏁 Concrete Prerequisites

• Advanced Language: Proficient with Python.
• Expertise: Deep architectural understanding of _Executable, Transaction, and Query base classes.
• Proven History: Successfully completed ≥ 10 intermediate issues in this repo.
• Consistency: ≥ 3–4 months of active, human-led contributions to this SDK.

Note

CI/CD Exception: For issues focused on GitHub Actions / Workflows, the repo-specific thresholds above may be waived if the contributor demonstrates advanced-level proficiency in CI/CD.

⚠️ AI Usage Policy

• Using AI to generate code for Advanced issues is strictly discouraged
• AI may be used to help explain file relationships, but cannot be the main source of research.
• Submitting AI-generated or unvalidated code is grounds for immediate closure

⏱️ Timeline & Workflow

• Typical time: ~1 month / ~50 hours.
• 🔴 Completing an advanced issue in 1–3 days is a red flag and will likely be rejected.
• Suggested: Post your proposed architectural approach as a comment and wait for explicit maintainer approval before writing any code.

🔬 Technical Domains

• API Client Architecture (request → serialization → execution → response mapping)
• Backward Compatibility (preserving method signatures, defaults, and return types)
• Protobuf Alignment (reading .proto files, _to_proto() / _from_proto() correctness)
• State & Immutability (correct usage of guards like _require_not_frozen)
• Execution Boundaries (retry logic, backoff, node selection, gRPC deadlines)
• Testing (unit, integration, mocking, test coverage for edge cases and failure modes)

🛡️ Quality & Review Standards

Advanced PRs must be "safe, maintainable, architecturally sound, and production-ready."

1. Architectural Fit: The solution must fit naturally into the existing SDK abstractions.
2. Security & Correctness: Evaluate all logic for injection risks, state corruption, or thread-safety issues.
3. Maintainability: Code must be short and clear enough for any other maintainer to debug without your assistance.
4. Backward Compatibility: Public API signatures must be preserved. If a breaking change is required, it must be explicitly managed through a deprecation cycle.
5. Comprehensive Testing: Must include unit and integration tests covering all new logic paths, edge cases, and failure modes. AI generated tests based on AI generated code is grounds for immediate rejection.

✅ PR Quality Checklist

Before opening your PR, the contributor must confirm:

• I have spent the majority of my time researching the problem and solution space extensively, including reviewing relevant code, documentation, and external resources.
• I understand the system-wide impact of these changes on affected modules and performance.
• The system design fits with current Hiero SDK architectural approaches.
• I have tested my changes extensively against both local and network environments.
• I have verified naming, types, and field ordering against pinned Protobufs.
• Every line of code is personally understood and explainable.

📚 Resources & Support

References:

• Hedera Protobufs

Python SDK References:

• SDK Project Structure
• Transaction Lifecycle
• Executable Architecture
• Hedera Protobufs (services)
• Browse closed advanced PRs — see how others did it

🆘 Stuck?

• Community Calls
• Discord

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Follow existing workflow patterns exactly, using bot-gfi-candidate-notification.yaml and bot-p0-issues-notify-team.yml as templates
• Implement lock/unlock via the GitHub REST API (issues.lock and issues.unlock) within github-script actions
• Use HTML comment markers for idempotent comment posting, preventing duplicate notifications on re-runs
• Add informative comments at both lock and unlock stages to communicate the moderation process to issue authors

Design Choices

Design Choice 1: Should all newly created issues be locked, or only those from non-maintainers?

Options Considered:

1. Lock all issues unconditionally on creation
2. Lock only issues created by users who are not organization members/maintainers

Chosen Option: 1

Rationale: Lock all issues unconditionally. This provides consistent behavior, simpler implementation, and maintainers can immediately apply the "approved" label to their own issues if needed. The unlock workflow ensures fast turnaround for triaged issues.

Design Choice 2: What should the "approved" label be named?

Options Considered:

1. approved (simple, direct)
2. moderation: approved (namespaced, consistent with priority: and skill: prefixes)
3. triage: approved (indicates triage process)

Chosen Option: 1

Rationale: approved. This keeps it simple and action-oriented. The label's purpose is clear without additional namespacing, and it aligns with the ticket's language.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Lock Issues on Creation

This phase creates the workflow and script that automatically locks newly opened issues, preventing interaction until a maintainer reviews them. A comment explains the moderation process to the issue author.

Task 1: Create the Lock Workflow File

Define the GitHub Actions workflow that triggers on issue creation and invokes the lock script.

• Create .github/workflows/bot-issue-lock-on-open.yml following the exact structure of bot-gfi-candidate-notification.yaml
• Trigger on issues: types: [opened]
• Set permissions to issues: write and contents: read
• Add concurrency group keyed by issue number with cancel-in-progress: false
• Use the standard three-step pattern: harden-runner → checkout → github-script
• Pin actions to the canonical SHAs: harden-runner 9af89fc71515a100421586dfdb3dc9c984fbf411, checkout 8e8c483db84b4bee98b60c0593521ed34d9990e8, github-script 3a2844b7e9c422d3c10d287c895573f7108da1b3
• Pass GITHUB_TOKEN and DRY_RUN (using the fork-detection pattern) as environment variables

Task 2: Create the Lock Script

Implement the JavaScript logic that locks the issue and posts an explanatory comment.

• Create .github/scripts/bot-issue-lock-on-open.js
• Extract owner, repo, and issue number from the workflow context
• Check for existing moderation comment using the HTML marker pattern (<!-- Issue Moderation Lock -->) to ensure idempotency
• Post a comment explaining: the issue is locked for triage review, a maintainer will review shortly, and the "approved" label will unlock it for contributor assignment
• Call the GitHub REST API to lock the issue conversation (github.rest.issues.lock)
• Respect the DRY_RUN environment variable by logging intended actions without executing them when true

🤖 Prompt for AI agents

Create the GitHub Actions workflow file and its companion JavaScript script to
automatically lock issues when they are first opened.

**Workflow file** — `.github/workflows/bot-issue-lock-on-open.yml`:
- Model the file structure exactly after `bot-gfi-candidate-notification.yaml`
- Trigger: `issues: types: [opened]`
- Permissions: `issues: write`, `contents: read`
- Concurrency group keyed by issue number with `cancel-in-progress: false`
- Three-step job: harden-runner → checkout → github-script
- Pin actions to the following SHAs:
  - harden-runner: `9af89fc71515a100421586dfdb3dc9c984fbf411`
  - checkout: `8e8c483db84b4bee98b60c0593521ed34d9990e8`
  - github-script: `3a2844b7e9c422d3c10d287c895573f7108da1b3`
- Pass `GITHUB_TOKEN` and `DRY_RUN` (using the fork-detection pattern) as
environment variables to the script

**Script file** — `.github/scripts/bot-issue-lock-on-open.js`:
- Extract owner, repo, and issue number from the workflow context
- Before posting, check all existing issue comments for the HTML marker `<!--
Issue Moderation Lock -->` to ensure idempotency
- Post a comment that includes the `<!-- Issue Moderation Lock -->` HTML marker
and explains: the issue is locked for triage review, a maintainer will review
shortly, and the "approved" label will unlock it for contributor assignment
- Call `github.rest.issues.lock` to lock the issue conversation
- When the `DRY_RUN` environment variable is `true`, log intended actions
without executing them

Phase 2: Unlock Issues on Approval

This phase creates the workflow and script that unlocks issues when the "approved" label is applied, signaling that the issue is ready for contributor assignment.

Task 1: Add Approved Label Constant

Register the new label in the shared label constants for consistency across scripts.

• Update .github/scripts/shared/labels.js to add APPROVED_LABEL = 'approved'
• Export the constant alongside existing labels for use in the unlock script

Task 2: Create the Unlock Workflow File

Define the GitHub Actions workflow that triggers when the "approved" label is applied.

• Create .github/workflows/bot-issue-unlock-on-approved.yml following the structure of bot-p0-issues-notify-team.yml
• Trigger on issues: types: [labeled]
• Add if: condition checking github.event.label.name == 'approved' (the newly-applied label)
• Set permissions to issues: write and contents: read
• Add concurrency group keyed by issue number with cancel-in-progress: false
• Use the standard three-step pattern with the same SHA-pinned actions
• Pass GITHUB_TOKEN and DRY_RUN as environment variables

Task 3: Create the Unlock Script

Implement the JavaScript logic that unlocks the issue and posts a welcome comment.

• Create .github/scripts/bot-issue-unlock-on-approved.js
• Import the APPROVED_LABEL constant from shared/labels.js
• Extract owner, repo, and issue number from the workflow context
• Check for existing unlock comment using an HTML marker (<!-- Issue Moderation Unlock -->) to prevent duplicate comments
• Call the GitHub REST API to unlock the issue conversation (github.rest.issues.unlock)
• Post a comment indicating: the issue has been approved for contribution, contributors can now comment and request assignment via /assign
• Respect the DRY_RUN environment variable

🤖 Prompt for AI agents

Create the shared label constant update, the GitHub Actions workflow file, and
the companion JavaScript script to automatically unlock issues when the
"approved" label is applied.

**Label constants** — `.github/scripts/shared/labels.js`:
- Add and export `APPROVED_LABEL = 'approved'` alongside the existing label
constants

**Workflow file** — `.github/workflows/bot-issue-unlock-on-approved.yml`:
- Model the file structure exactly after `bot-p0-issues-notify-team.yml`
- Trigger: `issues: types: [labeled]`
- Add a top-level or job-level `if:` condition: `github.event.label.name ==
'approved'`
- Permissions: `issues: write`, `contents: read`
- Concurrency group keyed by issue number with `cancel-in-progress: false`
- Three-step job: harden-runner → checkout → github-script, using the same
SHA-pinned actions as Phase 1
- Pass `GITHUB_TOKEN` and `DRY_RUN` as environment variables to the script

**Script file** — `.github/scripts/bot-issue-unlock-on-approved.js`:
- Import `APPROVED_LABEL` from `shared/labels.js`
- Extract owner, repo, and issue number from the workflow context
- Before posting, check all existing issue comments for the HTML marker `<!--
Issue Moderation Unlock -->` to prevent duplicate comments
- Call `github.rest.issues.unlock` to unlock the issue conversation
- Post a comment that includes the `<!-- Issue Moderation Unlock -->` HTML
marker and indicates: the issue has been approved for contribution, and
contributors can now comment and request assignment via `/assign`
- When the `DRY_RUN` environment variable is `true`, log intended actions
without executing them

Research

The repository has an extensive GitHub Actions workflow infrastructure in .github/workflows/ with supporting JavaScript scripts in .github/scripts/. All workflows follow strict security patterns: SHA-pinned actions, step-security/harden-runner with egress auditing, minimum required permissions, and the hl-sdk-py-lin-md runner. Label constants are centralized in .github/scripts/shared/labels.js. Existing label-triggered workflows like bot-gfi-candidate-notification.yaml and bot-p0-issues-notify-team.yml serve as direct templates for the new moderation workflows. Comment deduplication is handled via HTML marker strings embedded in comment bodies.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create the GitHub Actions workflow file and its companion JavaScript script to
automatically lock issues when they are first opened.

**Workflow file** — `.github/workflows/bot-issue-lock-on-open.yml`:
- Model the file structure exactly after `bot-gfi-candidate-notification.yaml`
- Trigger: `issues: types: [opened]`
- Permissions: `issues: write`, `contents: read`
- Concurrency group keyed by issue number with `cancel-in-progress: false`
- Three-step job: harden-runner → checkout → github-script
- Pin actions to the following SHAs:
  - harden-runner: `9af89fc71515a100421586dfdb3dc9c984fbf411`
  - checkout: `8e8c483db84b4bee98b60c0593521ed34d9990e8`
  - github-script: `3a2844b7e9c422d3c10d287c895573f7108da1b3`
- Pass `GITHUB_TOKEN` and `DRY_RUN` (using the fork-detection pattern) as
environment variables to the script

**Script file** — `.github/scripts/bot-issue-lock-on-open.js`:
- Extract owner, repo, and issue number from the workflow context
- Before posting, check all existing issue comments for the HTML marker `<!--
Issue Moderation Lock -->` to ensure idempotency
- Post a comment that includes the `<!-- Issue Moderation Lock -->` HTML marker
and explains: the issue is locked for triage review, a maintainer will review
shortly, and the "approved" label will unlock it for contributor assignment
- Call `github.rest.issues.lock` to lock the issue conversation
- When the `DRY_RUN` environment variable is `true`, log intended actions
without executing them
===============================================================================

Task: 2

Create the shared label constant update, the GitHub Actions workflow file, and
the companion JavaScript script to automatically unlock issues when the
"approved" label is applied.

**Label constants** — `.github/scripts/shared/labels.js`:
- Add and export `APPROVED_LABEL = 'approved'` alongside the existing label
constants

**Workflow file** — `.github/workflows/bot-issue-unlock-on-approved.yml`:
- Model the file structure exactly after `bot-p0-issues-notify-team.yml`
- Trigger: `issues: types: [labeled]`
- Add a top-level or job-level `if:` condition: `github.event.label.name ==
'approved'`
- Permissions: `issues: write`, `contents: read`
- Concurrency group keyed by issue number with `cancel-in-progress: false`
- Three-step job: harden-runner → checkout → github-script, using the same
SHA-pinned actions as Phase 1
- Pass `GITHUB_TOKEN` and `DRY_RUN` as environment variables to the script

**Script file** — `.github/scripts/bot-issue-unlock-on-approved.js`:
- Import `APPROVED_LABEL` from `shared/labels.js`
- Extract owner, repo, and issue number from the workflow context
- Before posting, check all existing issue comments for the HTML marker `<!--
Issue Moderation Unlock -->` to prevent duplicate comments
- Call `github.rest.issues.unlock` to unlock the issue conversation
- Post a comment that includes the `<!-- Issue Moderation Unlock -->` HTML
marker and indicates: the issue has been approved for contribution, and
contributors can now comment and request assignment via `/assign`
- When the `DRY_RUN` environment variable is `true`, log intended actions
without executing them

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!