[Intermediate]: Automate assignment for beginner issues

[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

We have a new beginner issue label, and a beginner template

This means we will be creating more beginner issues

We can enable auto-assignment for beginner issues, because they are low-risk for the SDK as are narrowly scoped and well-documented. Users of beginner issues will be used to auto assignment from good first issues.

We do not need to add more guards as we can rely on existing:

• spam user limitations, limited to 1 GFI at a time
• 2 max assignments per user

💡 Expected Solution

Create a well-tested auto assignment bot for beginner issues

🧠 Implementation Notes

Read a similar example:
.github/scripts/bot-gfi-assign-on-comment.js
.github/workflows/bot-gfi-assign-on-comment.yml

create one for beginner issues.

the labe is exactly 'beginner'

ensure:

• team members do not receive the assign reminder, if they are posting, it may be to help (and they can self-assign anyway)

NOTE please test lots of the scenarios on your fork, by merging your solution to your fork, creating various test case scenario issues and seeing if the bot works as expected.

✅ 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

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Approach

Create an auto-assignment bot for "beginner" labeled issues that mirrors the existing GFI bot functionality, allowing users to request assignment via /assign comments and providing helpful reminders, while excluding team members from receiving reminder notifications.

Observations

The project uses a two-file bot pattern for GitHub automation: JavaScript modules in .github/scripts/ contain the core logic, while YAML workflow files in .github/workflows/ configure event triggers and permissions. The existing GFI auto-assignment bot (bot-gfi-assign-on-comment.js/yml) processes /assign commands, validates assignments, and posts reminders. Other bots in the ecosystem use similar patterns for mentor assignment, intermediate issue guards, and P0 notifications. The project follows Keep a Changelog format for changelog entries and requires thorough fork testing before merging automation changes.

Assumptions

Assumption 1: Team member identification method for reminder exclusion

Options Considered:

• Use GitHub API's getCollaboratorPermissionLevel() to check for write/maintain/admin/triage permissions (same as bot-intermediate-assignment.js)
• Create a new team members configuration file similar to mentor_roster.json
• Use hardcoded GitHub team aliases

Chosen Option: 1

Rationale: Using the GitHub API permission check aligns with existing patterns, requires no manual maintenance of team lists, and accurately identifies users with repository access who can self-assign anyway.

💡 User Tips

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

Implementation Steps

Phase 1: Create Beginner Issue Assignment Bot Script

Create the JavaScript module that handles /assign command processing and reminder posting for beginner issues, following the GFI bot pattern with team member filtering.

Task 1: Create bot-beginner-assign-on-comment.js

Create the core bot logic in .github/scripts/ that processes comments on beginner issues

• Create new file .github/scripts/bot-beginner-assign-on-comment.js following the structure of bot-gfi-assign-on-comment.js
• Export async function receiving { github, context } parameters
• Extract payload data: issue number, comment body, commenter username, issue labels
• Implement validation chain: reject bots, missing data, non-issues (PRs)
• Add issueIsBeginnerIssue() helper that checks for exact label match "beginner" (not "Good First Issue")
• Reuse comment validation regex /(^|\s)\/assign(\s|$)/i for detecting /assign commands
• Add hasTeamMemberAccess() helper that uses github.rest.repos.getCollaboratorPermissionLevel() to check if user has write/maintain/admin/triage permissions
• Implement assignment logic: call github.rest.issues.addAssignees() after validation passes
• Post already-assigned notification if issue has assignees, directing users to browse unassigned beginner issues
• Implement reminder posting for non-assignment comments on unassigned beginner issues, but skip reminder if commenter has team member access
• Use unique marker <!-- beginner assign reminder --> (not the GFI marker) to prevent duplicate reminders
• Check existing comments before posting reminder to avoid spam

Task 2: Handle edge cases and error conditions

Ensure robust error handling throughout the bot

• Add null/undefined checks for all extracted payload properties
• Handle GitHub API errors gracefully (permission issues, rate limits, network failures)
• Log errors appropriately but don't fail silently - allow workflow to show failure status
• Ensure bot only processes issue comments, not PR comments (check context.payload.issue.pull_request)

🤖 Prompt for AI agents

Create the beginner issue assignment bot script that processes `/assign`
commands and posts reminders for beginner labeled issues, with team member
filtering.

Create `.github/scripts/bot-beginner-assign-on-comment.js`:
- Export async function accepting `{ github, context }` parameters
- Extract payload data: issue number, comment body, commenter username, issue
labels
- Implement validation: reject bots, missing data, and PRs
- Add `issueIsBeginnerIssue()` helper to check for exact "beginner" label match
- Use regex `/(^|\s)\/assign(\s|$)/i` to detect `/assign` commands
- Add `hasTeamMemberAccess()` helper using
`github.rest.repos.getCollaboratorPermissionLevel()` to check for
write/maintain/admin/triage permissions
- Implement assignment logic via `github.rest.issues.addAssignees()`
- Post already-assigned notification if issue has assignees
- For non-assignment comments on unassigned beginner issues, post reminder only
if commenter is not a team member
- Use unique marker `<!-- beginner assign reminder -->` to prevent duplicates
- Check existing comments before posting reminders
- Add null/undefined checks for all payload properties
- Handle GitHub API errors gracefully with appropriate logging
- Ensure bot only processes issue comments using
`context.payload.issue.pull_request` check

Phase 2: Create Workflow Configuration

Configure the GitHub Actions workflow that triggers the beginner assignment bot on issue comment events.

Create bot-beginner-assign-on-comment.yml

Create workflow file in .github/workflows/ that triggers on issue comments

• Create new file .github/workflows/bot-beginner-assign-on-comment.yml following structure of bot-gfi-assign-on-comment.yml
• Configure trigger: issue_comment event with created type (not edited)
• Set permissions: issues: write for assignments/comments, contents: read for repository access
• Add concurrency control: group by beginner-assign-${{ github.event.issue.number }} with cancel-in-progress: false to prevent race conditions
• Add condition: github.event.issue.pull_request == null to ensure bot only runs on issues
• Configure job to use actions/github-script@v8.0.0 (same version as GFI bot)
• Load and execute .github/scripts/bot-beginner-assign-on-comment.js with github and context objects

🤖 Prompt for AI agents

Create the GitHub Actions workflow configuration that triggers the beginner
assignment bot on issue comment events.

Create `.github/workflows/bot-beginner-assign-on-comment.yml`:
- Follow structure of `bot-gfi-assign-on-comment.yml`
- Configure trigger on `issue_comment` event with `created` type only
- Set permissions: `issues: write` and `contents: read`
- Add concurrency control grouped by `beginner-assign-${{
github.event.issue.number }}` with `cancel-in-progress: false`
- Add condition `github.event.issue.pull_request == null` to run only on issues
- Use `actions/github-script@v8.0.0`
- Load and execute `.github/scripts/bot-beginner-assign-on-comment.js` with
github and context objects

Phase 3: Testing and Validation

Thoroughly test the bot implementation on a fork following the documented testing procedures.

Task 1: Fork testing setup

Prepare fork environment for testing the new bot

• Follow guidance in docs/sdk_developers/training/testing_forks.md for fork setup
• Enable GitHub Actions on fork via Settings (disabled by default)
• Merge bot implementation to fork's main branch as "production" version
• Prepare test scenarios: beginner labeled issues with various user types and comment patterns

Task 2: Execute comprehensive test scenarios

Test all bot behaviors and edge cases

• Test successful assignment: non-team member comments /assign on unassigned beginner issue
• Test already-assigned notification: user comments /assign on already-assigned beginner issue
• Test reminder posting: non-team member posts non-assignment comment on unassigned beginner issue
• Test team member exclusion: team member (collaborator with write+ access) posts non-assignment comment - verify NO reminder posted
• Test team member self-assignment: team member comments /assign - verify assignment succeeds
• Test duplicate reminder prevention: multiple non-assignment comments don't create duplicate reminders
• Test non-beginner issues: verify bot ignores issues without "beginner" label
• Test PR comments: verify bot doesn't run on pull request comments
• Test bot comments: verify bot ignores other bots' comments
• Test concurrent assignment attempts: multiple users try to /assign simultaneously
• Document test results and any issues discovered

🤖 Prompt for AI agents

This phase focuses on testing and validation activities that don't require code
generation. Manual testing should be performed on a fork.

Set up fork environment:
- Follow `docs/sdk_developers/training/testing_forks.md` for setup
- Enable GitHub Actions in fork settings
- Merge bot implementation to main branch
- Create beginner labeled test issues

Execute test scenarios:
- Non-team member `/assign` on unassigned beginner issue
- User `/assign` on already-assigned beginner issue
- Non-team member non-assignment comment on unassigned beginner issue (should
post reminder)
- Team member non-assignment comment (should NOT post reminder)
- Team member self-assignment
- Duplicate reminder prevention
- Non-beginner issue handling
- PR comment handling
- Bot comment handling
- Concurrent assignment attempts
- Document all test results

Phase 4: Documentation Updates

Add changelog entry following project conventions.

Update CHANGELOG.md

Add entry describing the new bot functionality

• Add entry under the "Unreleased" section in CHANGELOG.md following Keep a Changelog format
• Use "### Added" category subsection
• Write bullet point: "Auto-assignment bot for beginner labeled issues with /assign command support and helpful reminders"
• Reference this issue number in the changelog entry
• Follow existing format: concise description with issue link

🤖 Prompt for AI agents

Update documentation to reflect the new beginner issue assignment bot.

Update `CHANGELOG.md`:
- Add entry under "Unreleased" section
- Use "### Added" category
- Add bullet point: "Auto-assignment bot for beginner labeled issues with
`/assign` command support and helpful reminders"
- Include issue number reference
- Follow Keep a Changelog format and existing project conventions

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create the beginner issue assignment bot script that processes `/assign`
commands and posts reminders for beginner labeled issues, with team member
filtering.

Create `.github/scripts/bot-beginner-assign-on-comment.js`:
- Export async function accepting `{ github, context }` parameters
- Extract payload data: issue number, comment body, commenter username, issue
labels
- Implement validation: reject bots, missing data, and PRs
- Add `issueIsBeginnerIssue()` helper to check for exact "beginner" label match
- Use regex `/(^|\s)\/assign(\s|$)/i` to detect `/assign` commands
- Add `hasTeamMemberAccess()` helper using
`github.rest.repos.getCollaboratorPermissionLevel()` to check for
write/maintain/admin/triage permissions
- Implement assignment logic via `github.rest.issues.addAssignees()`
- Post already-assigned notification if issue has assignees
- For non-assignment comments on unassigned beginner issues, post reminder only
if commenter is not a team member
- Use unique marker `<!-- beginner assign reminder -->` to prevent duplicates
- Check existing comments before posting reminders
- Add null/undefined checks for all payload properties
- Handle GitHub API errors gracefully with appropriate logging
- Ensure bot only processes issue comments using
`context.payload.issue.pull_request` check
===============================================================================

Task: 2

Create the GitHub Actions workflow configuration that triggers the beginner
assignment bot on issue comment events.

Create `.github/workflows/bot-beginner-assign-on-comment.yml`:
- Follow structure of `bot-gfi-assign-on-comment.yml`
- Configure trigger on `issue_comment` event with `created` type only
- Set permissions: `issues: write` and `contents: read`
- Add concurrency control grouped by `beginner-assign-${{
github.event.issue.number }}` with `cancel-in-progress: false`
- Add condition `github.event.issue.pull_request == null` to run only on issues
- Use `actions/github-script@v8.0.0`
- Load and execute `.github/scripts/bot-beginner-assign-on-comment.js` with
github and context objects
===============================================================================

Task: 3

This phase focuses on testing and validation activities that don't require code
generation. Manual testing should be performed on a fork.

Set up fork environment:
- Follow `docs/sdk_developers/training/testing_forks.md` for setup
- Enable GitHub Actions in fork settings
- Merge bot implementation to main branch
- Create beginner labeled test issues

Execute test scenarios:
- Non-team member `/assign` on unassigned beginner issue
- User `/assign` on already-assigned beginner issue
- Non-team member non-assignment comment on unassigned beginner issue (should
post reminder)
- Team member non-assignment comment (should NOT post reminder)
- Team member self-assignment
- Duplicate reminder prevention
- Non-beginner issue handling
- PR comment handling
- Bot comment handling
- Concurrent assignment attempts
- Document all test results
===============================================================================

Task: 4

Update documentation to reflect the new beginner issue assignment bot.

Update `CHANGELOG.md`:
- Add entry under "Unreleased" section
- Use "### Added" category
- Add bullet point: "Auto-assignment bot for beginner labeled issues with
`/assign` command support and helpful reminders"
- Include issue number reference
- Follow Keep a Changelog format and existing project conventions

💡 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!

[Pikolosan]

Hello @exploreriii, could u assign this issue to me.

[exploreriii]

Assigned @Pikolosan, thank you for this and sorry for the delay!
This would be a very beneficial feature for us - greatly appreciated if you can go the extra mile and test it on your fork later 👍

[Pikolosan]

Hey , thanks for the assign.
I have developed a solution on my forked repo already and tried some tests.
Kinldy check them so i can create a pr

Test 1: Successful Assignment and reassign check
link : Pikolosan#2
Result: User commented /assign and was correctly assigned. and alert on second command.

Test 2: Non assign comments
link : Pikolosan#5
result : no reaction

Test 3: assign command in Non beginner issue
link : Pikolosan#3
result : no reaction.

[exploreriii]

Excellent work and tests, let's go!