the-nexus/docs/auto-reviewer-assignment.md

Automated Reviewer Assignment

Issue: #1444 - policy: Implement automated reviewer assignment (from Issue #1127 triage)
Purpose: Ensure all PRs have at least one reviewer assigned

Problem

From issue #1127 triage:

"0 of 14 PRs had a reviewer assigned before this pass."

This means:

• PRs can be created without any reviewer
• No automated enforcement of reviewer assignment
• PRs may sit without review for extended periods

Solution

1. GitHub Actions Workflow (.gitea/workflows/auto-assign-reviewers.yml)

Automatically assigns reviewers when PRs are created:

When it runs:

• On PR open
• On PR reopen
• On PR ready for review (not draft)

What it does:

1. Determines appropriate reviewers based on repository
2. Assigns reviewers via Gitea API
3. Adds comment about reviewer assignment
4. Verifies at least one reviewer is assigned

2. Reviewer Check Script (bin/check_reviewers.py)

Script to check for PRs without reviewers:

Usage:

# Check all repositories
python bin/check_reviewers.py

# Check specific repositories
python bin/check_reviewers.py --repos the-nexus timmy-home

# Generate report
python bin/check_reviewers.py --report

# Assign reviewer to specific PR
python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity

3. CODEOWNERS File (.github/CODEOWNERS)

Defines default reviewers for different paths:

# Default reviewer for all repositories
* @perplexity

# Specialized component owners
hermes-agent/ @Timmy
hermes-agent/agent-core/ @Rockachopa
hermes-agent/protocol/ @Timmy
the-nexus/ @perplexity
the-nexus/ai/ @Timmy
timmy-home/ @perplexity
timmy-config/ @perplexity

# Owner gates for critical systems
hermes-agent/ @Timmy

Reviewer Assignment Rules

Repository-Specific Rules

Repository	Default Reviewers	Required Reviewers	Notes
hermes-agent	@Timmy, @perplexity	@Timmy	Owner gate for critical system
the-nexus	@perplexity	None	QA gate
timmy-home	@perplexity	None	QA gate
timmy-config	@perplexity	None	QA gate
the-beacon	@perplexity	None	QA gate

Special Rules

1. No self-review: PR author cannot be assigned as reviewer
2. Fallback: If no reviewers available, assign @perplexity
3. Critical systems: hermes-agent requires @Timmy as reviewer

How It Works

Automated Assignment Flow

1. PR Created → GitHub Actions workflow triggers
2. Determine Reviewers → Based on repository and CODEOWNERS
3. Assign Reviewers → Via Gitea API
4. Add Comment → Notify about assignment
5. Verify → Ensure at least one reviewer assigned

Manual Assignment

# Assign specific reviewer
python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity

# Check for PRs without reviewers
python bin/check_reviewers.py --report

Configuration

Environment Variables

• GITEA_TOKEN: Gitea API token for authentication
• REPO: Repository name (auto-set in GitHub Actions)
• PR_NUMBER: PR number (auto-set in GitHub Actions)

Repository Configuration

Edit the workflow to customize reviewer assignment:

# Define default reviewers based on repository
case "$REPO_NAME" in
  "hermes-agent")
    DEFAULT_REVIEWERS=("Timmy" "perplexity")
    REQUIRED_REVIEWERS=("Timmy")
    ;;
  "the-nexus")
    DEFAULT_REVIEWERS=("perplexity")
    REQUIRED_REVIEWERS=()
    ;;
  # Add more repositories as needed
esac

Testing

Test the workflow:

1. Create a test PR
2. Check if reviewers are automatically assigned
3. Verify comment is added

Test the script:

# Check for PRs without reviewers
python bin/check_reviewers.py --report

# Assign reviewer to test PR
python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity

Monitoring

Check for PRs without reviewers:

# Daily check
python bin/check_reviewers.py --report

# JSON output for automation
python bin/check_reviewers.py --json

Review assignment logs:

1. Check GitHub Actions logs for assignment details
2. Review PR comments for assignment notifications
3. Monitor for PRs with 0 reviewers

Enforcement

CI Check (Future Enhancement)

Add CI check to reject PRs with 0 reviewers:

# In CI workflow
- name: Check for reviewers
  run: |
    REVIEWERS=$(curl -s "https://forge.alexanderwhitestone.com/api/v1/repos/$REPO/pulls/$PR_NUMBER/requested_reviewers" \
      -H "Authorization: token $GITEA_TOKEN" | jq '.users | length')
    
    if [ "$REVIEWERS" -eq 0 ]; then
      echo "❌ ERROR: PR has no reviewers assigned"
      exit 1
    fi

Policy Enforcement

1. All PRs must have reviewers - No exceptions
2. No self-review - PR author cannot review own PR
3. Critical systems require specific reviewers - hermes-agent requires @Timmy

Related Issues

• Issue #1127: Perplexity Evening Pass triage (identified missing reviewers)
• Issue #1444: This implementation
• Issue #1336: Merge conflicts in CODEOWNERS (fixed)

Files Added/Modified

1. .gitea/workflows/auto-assign-reviewers.yml - GitHub Actions workflow
2. bin/check_reviewers.py - Reviewer check script
3. .github/CODEOWNERS - Cleaned up CODEOWNERS file
4. docs/auto-reviewer-assignment.md - This documentation

Future Enhancements

1. CI check for 0 reviewers - Reject PRs without reviewers
2. Slack/Telegram notifications - Notify when PRs lack reviewers
3. Load balancing - Distribute reviews evenly among team members
4. Auto-assign based on file changes - Assign specialists for specific areas

Conclusion

This implementation ensures all PRs have at least one reviewer assigned:

• Automated assignment on PR creation
• Manual checking for existing PRs
• Clear documentation of policies and procedures

Result: No more PRs sitting without reviewers.

License

Part of the Timmy Foundation project.