[Intermediate]: Refactor .github/scripts/gfi_notify_team.js

[exploreriii]

🧩 Intermediate Contributors

This issue is intended for contributors who already have some familiarity with the
Hiero Python SDK codebase and contribution workflow.

You should feel comfortable:

• navigating existing source code and examples
• understanding SDK concepts without step-by-step guidance
• following the standard PR workflow without additional onboarding

If this is your very first contribution to the project, we recommend starting with a few
Good First Issues before working on this one.

🐞 Problem Description

Currently, when a good first issue is created, it notifies the good first issue team - so they are on standby - in case anyone wants to be assigned

The problem, is this creates a post inside the issue even though the issue is not yet assigned.

People looking for good first issues are often looking for available issues, and perhaps there are quite a few to choose from, so a comment could be indicative of someone being interested already - disassuading them from looking at the issue and wanting to work on it.

💡 Expected Solution

We should remove the bot logic that posts on a good first issue as soon as it is created.

Instead, we should add that same post but only after one person - first comments on the issue.
This person is likely to be the person wanting to work on the good first issue.

🧠 Implementation Notes

So workflow:

1. good first issue is created
2. new person sees there is a fresh good first issue, comments they want to be assigned to it.
3. good first issue support team is notified that a good first issue may be ready to be assigned and needs immediate attention.
   We should check the message is still relevant and make tweaks as needed.

Ensure no duplicate posts in case there are multiple people posting at once.

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem described above
• Follow existing project conventions and patterns
• Include tests or example updates where appropriate
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context or Resources

• SDK Developer Docs
• SDK Developer Training

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Fix incorrect team mentions in P0 alert notification comment #1111
• [Good First Issue]: Rename pr_missing_linked_issue workflows #1197
• [Good First Issue]: test #1002
• [Good First Issue]: #1005
• [Good First Issue]: Create docs/maintainers/good_first_issues.md #1034

🔗 Related PRs

#1123 - feat: Add workflow to notify team about Good first issues [merged]
#1128 - docs: add GFI-Guidelines Doc File [merged]
#1133 - docs: gfi guidelines [merged]
#1137 - feat: create new .github/ISSUE_TEMPLATE/05_intermediate_issue.yml [merged]
#1173 - feat(ci): add workflow to remind pull requests to link issues [merged]

👤 Suggested Assignees

• exploreriii
• MonaaEid
• kplnosmn94-droid
• aceppaluni
• AntonioCeppellini

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Refactor the GFI notification system to trigger on the first comment posted to a Good First Issue, rather than immediately when the issue is labeled. This prevents premature notifications and makes issues appear more available to potential contributors.

Observations

Codebase Summary

The project uses GitHub Actions workflows (.github/workflows/) to automate issue management, with Node.js scripts (.github/scripts/) handling the notification logic. The current GFI notification system uses an issues: labeled trigger and posts team mentions via the GitHub REST API. The codebase has established patterns for duplicate comment prevention using HTML marker comments and actor-based bot detection.

Assumptions

Assumption 1: First comment detection approach

Options Considered:

• Count all comments including bot comments (simpler but less accurate)
• Count only human comments by filtering out github-actions and other known bots (more accurate, aligns with user intent)

Chosen Option: Count only human comments by filtering based on comment author

Rationale: This better reflects the ticket's intent—developers want to know if a real person has shown interest. The existing codebase patterns already filter bot comments (see bot-verified-commits.yml), so this approach is consistent with established practices and provides better developer experience.

💡 User Tips

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

Implementation Steps

Phase 1: Update Workflow Trigger and Conditionals

Modify the GitHub Actions workflow to respond to comments instead of label events, and add label verification logic.

Task 1: Change workflow event trigger

Update .github/workflows/bot-gfi-notify-team.yml to trigger on comment events rather than labeling events.

• Replace issues: types: [labeled] trigger with issue_comment: types: [created]
• Maintain existing permissions (issues: write and contents: read) as they're sufficient for comment events
• Update workflow name and description if needed to reflect the new trigger behavior

Task 2: Add label verification conditional

Add job-level conditional logic to verify the issue has a GFI label before executing the notification job.

• Update the existing if condition to check for GFI labels in the issue context
• Access labels via github.event.issue.labels array (available in issue_comment events)
• Check for both "Good First Issue" and "Good First Issue Candidate" labels using contains() expression
• Ensure the condition also verifies this is an issue comment (not a PR comment) by checking that github.event.issue.pull_request is absent

🤖 Prompt for AI agents

Update the workflow trigger to fire on issue comments instead of issue labels,
and add job-level conditionals to verify GFI labels exist.

In `.github/workflows/bot-gfi-notify-team.yml`:
- Change trigger from `issues: types: [labeled]` to `issue_comment: types:
[created]`
- Keep existing permissions unchanged
- Add/update job `if` condition to check `github.event.issue.labels` contains
"Good First Issue" or "Good First Issue Candidate"
- Ensure condition verifies `github.event.issue.pull_request` is absent to
exclude PR comments

Phase 2: Enhance Script Logic for First Comment Detection

Modify the notification script to detect when the triggering comment is the first human comment and prevent duplicate notifications from concurrent comments.

Task 1: Add first comment verification logic

Update .github/scripts/gfi_notify_team.js to verify the triggering comment is the first human comment on the issue.

• Fetch all issue comments using the existing pagination pattern
• Filter comments to exclude bot comments (check comment.user.login === 'github-actions' and any other known bot accounts)
• Count remaining human comments and verify the count equals 1 (meaning this is the first human comment)
• If count is greater than 1, exit early without posting notification
• Preserve existing error handling patterns with try-catch blocks

Task 2: Adjust duplicate notification prevention

Refine the existing marker-based duplicate detection to work with the new comment-triggered flow.

• Keep the existing <!-- GFI Issue Notification --> HTML marker in the notification comment body
• Verify the marker check happens after the first-comment count verification
• Ensure the marker check searches only for bot-authored comments to avoid false positives
• This provides defense-in-depth: count check prevents most duplicates, marker check catches any that slip through timing windows

Task 3: Update notification message content

Review and adjust the notification message to reflect the new workflow where someone has already expressed interest.

• Update message text to acknowledge that someone has commented and shown interest
• Keep the team mention (@hiero-ledger/hiero-sdk-good-first-issue-support)
• Preserve the different message variants for "Good First Issue" vs "Good First Issue Candidate" labels
• Update language from "new GFI ready to assign" to "GFI with interested contributor" or similar
• Maintain the issue metadata (title, link) and signature footer structure

🤖 Prompt for AI agents

Implement first comment detection and update notification logic to work with
comment-triggered workflow.

In `.github/scripts/gfi_notify_team.js`:
- Fetch all issue comments with pagination
- Filter out bot comments (`comment.user.login === 'github-actions'` and other
bots)
- Count human comments and exit early if count > 1
- Keep existing HTML marker (`<!-- GFI Issue Notification -->`) for duplicate
prevention
- Ensure marker check searches only bot-authored comments after count
verification
- Update notification message text to acknowledge someone has shown interest
- Maintain team mention `@hiero-ledger/hiero-sdk-good-first-issue-support`
- Preserve separate messages for "Good First Issue" vs "Good First Issue
Candidate"
- Keep existing error handling with try-catch blocks

Phase 3: Add Robustness for Concurrent Comments

Implement additional safeguards to handle edge cases where multiple people comment simultaneously.

Task 1: Add workflow concurrency control

Configure the workflow to serialize executions per issue to prevent race conditions.

• Add concurrency block to .github/workflows/bot-gfi-notify-team.yml at the job or workflow level
• Set concurrency.group to a dynamic value like gfi-notify-issue-${{ github.event.issue.number }}
• Set concurrency.cancel-in-progress to false to allow the first run to complete rather than cancelling it
• This ensures that if multiple comments arrive in quick succession, they're processed serially, giving the marker check time to work

Task 2: Add logging for debugging

Enhance script logging to help troubleshoot issues with comment detection and duplicate prevention.

• Add console.log statements for key decision points: comment count, marker found/not found, label type detected
• Log when skipping notification due to not being first comment
• Log when skipping due to existing marker
• Keep error logging patterns consistent with existing implementation
• These logs will appear in GitHub Actions run output for debugging

🤖 Prompt for AI agents

Add concurrency controls and enhanced logging to handle race conditions and aid
debugging.

In `.github/workflows/bot-gfi-notify-team.yml`:
- Add `concurrency` block with `group: gfi-notify-issue-${{
github.event.issue.number }}`
- Set `cancel-in-progress: false` to serialize executions per issue

In `.github/scripts/gfi_notify_team.js`:
- Add console.log for comment count, marker detection results, and label types
- Log when skipping due to not being first comment
- Log when skipping due to existing marker
- Maintain consistent error logging patterns

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update the workflow trigger to fire on issue comments instead of issue labels,
and add job-level conditionals to verify GFI labels exist.

In `.github/workflows/bot-gfi-notify-team.yml`:
- Change trigger from `issues: types: [labeled]` to `issue_comment: types:
[created]`
- Keep existing permissions unchanged
- Add/update job `if` condition to check `github.event.issue.labels` contains
"Good First Issue" or "Good First Issue Candidate"
- Ensure condition verifies `github.event.issue.pull_request` is absent to
exclude PR comments
===============================================================================

Task: 2

Implement first comment detection and update notification logic to work with
comment-triggered workflow.

In `.github/scripts/gfi_notify_team.js`:
- Fetch all issue comments with pagination
- Filter out bot comments (`comment.user.login === 'github-actions'` and other
bots)
- Count human comments and exit early if count > 1
- Keep existing HTML marker (`<!-- GFI Issue Notification -->`) for duplicate
prevention
- Ensure marker check searches only bot-authored comments after count
verification
- Update notification message text to acknowledge someone has shown interest
- Maintain team mention `@hiero-ledger/hiero-sdk-good-first-issue-support`
- Preserve separate messages for "Good First Issue" vs "Good First Issue
Candidate"
- Keep existing error handling with try-catch blocks
===============================================================================

Task: 3

Add concurrency controls and enhanced logging to handle race conditions and aid
debugging.

In `.github/workflows/bot-gfi-notify-team.yml`:
- Add `concurrency` block with `group: gfi-notify-issue-${{
github.event.issue.number }}`
- Set `cancel-in-progress: false` to serialize executions per issue

In `.github/scripts/gfi_notify_team.js`:
- Add console.log for comment count, marker detection results, and label types
- Log when skipping due to not being first comment
- Log when skipping due to existing marker
- Maintain consistent error logging patterns

💡 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 assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[undefinedIsMyLife]

I’d like to pick this up and work on it.

[exploreriii]

Thanks @undefinedIsMyLife !
This one is more urgent please