[Intermediate]: Adjust .github/scripts/bot-assignment-check.sh to guard against users with spam PRs

[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,
.github/scripts/bot-assignment-check.sh
allows regular users to have a maximum of 2 issues assigned.

This can be misused if some users want to create spam.

💡 Expected Solution

We can adjust .github/scripts/bot-assignment-check.sh
To check for users with a historical closed (not merged) pull request with a label of 'spam'. This might not be feasible as we have a lot of closed PRs.
Alternatively, if needed, we can check for a username with a spam list.

When the user requesting to be assigned is identified as historically created spam, their maximum assignment count should be 1 and ideally: scope to issues reduced to only to issues labelled as good first issues.

The list might be best as then we can remove the user from the spam list if they follow the documented workflow and create high-quality pull requests.

🧠 Implementation Notes

• create a spam list by github username
• limit total assignments to 1 at a time, only for 'Good First Issue' labelled

Keep other logic the same as is possible - the bot works very well for most cases.

✅ 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

• Create bot that prevents users to be assigned to an issue if they have open existing assignments #953
• Bug: Bot inactivity phase 1 file path not recognised #964
• Expand bot-inactivity-unassign bot - Phase 2: Extend the logic to handle users who do have a PR, but with ≥21 days of inactivity #969
• [Bug]: Activity Unassign Bot #1022
• [Bug]: Inactivity Bot calculating assigned days based on issue creation not days assigned #1074
• [Intermediate]: Refactor .github/scripts/gfi_notify_team.js #1212
• Create workflow that ensures advanced issue assigned only to those who are familiar with the code #1142
• [Good First Issue]: Rename workflows so script and workflow names match #1198

🔗 Related PRs

#1123 - feat: Add workflow to notify team about Good first issues [merged]
#1133 - docs: gfi guidelines [merged]
#1150 - ci: reduce office-hours reminder spam by posting only on most recent PR per user [merged]
#1173 - feat(ci): add workflow to remind pull requests to link issues [merged]
#1239 - feat: add explicit assignees mention to issue reminder bot [closed]

👤 Suggested Assignees

• exploreriii
• kplnosmn94-droid
• TianyangRen
• undefinedIsMyLife
• drtoxic69

---

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

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Enhance the bot assignment check script to restrict users with a history of spam contributions by maintaining a spam list, limiting these users to 1 assignment at a time for "Good First Issue" labeled issues only, while preserving existing bot behavior for all other users.

Observations

Codebase Summary

The repository uses GitHub Actions workflows and bash scripts in .github/ for automation. The assignment bot (bot-assignment-check.sh) currently enforces a 2-issue limit for regular users by checking permissions and counting open assignments. Scripts use the gh CLI with GH_TOKEN for GitHub API interactions. The codebase follows YAML conventions for workflow configurations but has no existing patterns for maintaining user lists.

Assumptions

Assumption 1: Spam List File Format

Options Considered:

• Plain text file (.github/spam-list.txt) with one username per line
• YAML configuration file (.github/spam-list.yml) with structured metadata
• JSON configuration file (.github/spam-list.json) for structured data

Chosen Option: Plain text file (.github/spam-list.txt) with one username per line

Rationale: Plain text file because it's the simplest to implement in bash, requires no additional parsing tools, is easy for maintainers to edit directly in GitHub's UI, and aligns with bash scripting patterns. Metadata can be added through comments if needed later.

Assumption 2: Label Checking Implementation

Options Considered:

• Check labels immediately when a spam-listed user is detected, before counting assignments
• Count assignments first, then check labels only if the count would exceed the limit

Chosen Option: Check labels immediately when a spam-listed user is detected, before counting assignments

Rationale: Check labels immediately when spam-listed user is detected because this provides faster feedback to the user (they get an instant message about restrictions) and avoids unnecessary API calls to count assignments for issues they can't be assigned to anyway.

💡 User Tips

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

Implementation Steps

Phase 1: Spam List Infrastructure

Create the spam list configuration file and establish the documentation for maintainers to manage it.

Task 1: Create Spam List File

Initialize a plain text configuration file to track usernames that should have restricted assignment privileges.

• Create .github/spam-list.txt in the repository root's .github/ directory
• Use one GitHub username per line format (no @ prefix)
• Add header comments explaining the file's purpose and how to add/remove entries
• Include example comment showing the format: # Add usernames below, one per line
• Start with an empty list (or test entries if needed for validation)

Task 2: Document Spam List Management

Provide guidance for maintainers on when and how to update the spam list.

• Add inline comments in .github/spam-list.txt explaining:
  • What qualifies a user for the spam list
  • How restrictions work (1 assignment, Good First Issue only)
  • How to remove users who improve their contributions
• Consider adding a brief section to project documentation (if appropriate) about the spam prevention system

🤖 Prompt for AI agents

Create spam list infrastructure to track users with restricted assignment
privileges.

Create `.github/spam-list.txt` file:
- Add header comments explaining purpose and usage
- Use format: one username per line (no @ prefix)
- Include example comment: `# Add usernames below, one per line`
- Start with empty list or test entries

Add documentation comments explaining:
- What qualifies a user for spam list
- Restriction details (1 assignment, Good First Issue only)
- How to remove users who improve contributions

Phase 2: Bot Assignment Logic Updates

Modify the assignment check script to read the spam list, detect spam-listed users, and apply the appropriate restrictions.

Task 1: Add Spam List Reading

Extend bot-assignment-check.sh to load and check the spam list during execution.

• Add function early in .github/scripts/bot-assignment-check.sh to read .github/spam-list.txt
• Skip empty lines and lines starting with # (comments)
• Store usernames in a variable or use grep to check membership
• Use grep -qxF "$ASSIGNEE" .github/spam-list.txt pattern for efficient lookup
• Handle file-not-found gracefully (treat as empty list)

Task 2: Implement Good First Issue Label Check

Query the GitHub API to determine if the assigned issue has the "Good First Issue" label.

• Use gh api or gh issue view to fetch issue labels for $ISSUE_NUMBER
• Parse the JSON response to extract label names
• Check for exact match with "Good First Issue" (case-sensitive)
• Store result in a variable like IS_GFI for later use

Task 3: Apply Spam User Restrictions

Integrate spam list detection into the existing permission and assignment count flow.

• After the existing permission check in .github/scripts/bot-assignment-check.sh, add spam list check
• If user is in spam list:
  • First check if issue has "Good First Issue" label using the label check from Task 2.2
  • If NOT a GFI: immediately revoke assignment and post comment explaining that spam-listed users can only be assigned to Good First Issue labeled issues
  • If IS a GFI: count open assignments (reusing existing logic)
  • If count >= 1 (instead of > 2 for regular users): revoke assignment and post comment explaining spam-listed users are limited to 1 assignment at a time
• If user is NOT in spam list: continue with existing logic unchanged (maintain current 2-issue limit)

Task 4: Update Bot Comments

Customize the explanatory comments posted when revoking assignments for spam-listed users.

• Create distinct comment messages for spam-listed users that explain:
  • Their restricted status
  • The 1-assignment limit
  • The Good First Issue only restriction
  • How they can have restrictions lifted (by demonstrating quality contributions)
• Maintain the existing comment style and HTML markers used by other bot scripts
• Keep existing comments for non-spam-listed users unchanged

🤖 Prompt for AI agents

Modify `bot-assignment-check.sh` to implement spam list restrictions for user
assignments.

Add spam list reading function:
- Read `.github/spam-list.txt` and skip empty lines and comments (#)
- Use `grep -qxF "$ASSIGNEE" .github/spam-list.txt` for membership check
- Handle missing file gracefully (treat as empty)

Implement Good First Issue label detection:
- Use `gh api` or `gh issue view` to fetch labels for issue
- Parse JSON to extract label names
- Check for exact "Good First Issue" match (case-sensitive)
- Store result in variable (e.g., `IS_GFI`)

Apply spam user restrictions after permission check:
- If user in spam list:
  - Check if issue has "Good First Issue" label
  - If NOT GFI: revoke assignment with explanation comment
  - If IS GFI: count open assignments and enforce 1-assignment limit
- If user NOT in spam list: preserve existing 2-issue limit logic

Create custom bot comments for spam-listed users:
- Explain restricted status and limitations
- Describe 1-assignment limit and Good First Issue only restriction
- Include guidance on how to have restrictions lifted
- Maintain existing comment style and HTML markers

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create spam list infrastructure to track users with restricted assignment
privileges.

Create `.github/spam-list.txt` file:
- Add header comments explaining purpose and usage
- Use format: one username per line (no @ prefix)
- Include example comment: `# Add usernames below, one per line`
- Start with empty list or test entries

Add documentation comments explaining:
- What qualifies a user for spam list
- Restriction details (1 assignment, Good First Issue only)
- How to remove users who improve contributions
===============================================================================

Task: 2

Modify `bot-assignment-check.sh` to implement spam list restrictions for user
assignments.

Add spam list reading function:
- Read `.github/spam-list.txt` and skip empty lines and comments (#)
- Use `grep -qxF "$ASSIGNEE" .github/spam-list.txt` for membership check
- Handle missing file gracefully (treat as empty)

Implement Good First Issue label detection:
- Use `gh api` or `gh issue view` to fetch labels for issue
- Parse JSON to extract label names
- Check for exact "Good First Issue" match (case-sensitive)
- Store result in variable (e.g., `IS_GFI`)

Apply spam user restrictions after permission check:
- If user in spam list:
  - Check if issue has "Good First Issue" label
  - If NOT GFI: revoke assignment with explanation comment
  - If IS GFI: count open assignments and enforce 1-assignment limit
- If user NOT in spam list: preserve existing 2-issue limit logic

Create custom bot comments for spam-listed users:
- Explain restricted status and limitations
- Describe 1-assignment limit and Good First Issue only restriction
- Include guidance on how to have restrictions lifted
- Maintain existing comment style and HTML markers

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