Gh Issues

gh-issues — Auto-fix GitHub Issues with Parallel Sub-agents

Automatically fetch GitHub issues, spawn sub-agents to implement fixes, and open pull requests. Supports filtering by labels, milestones, assignees, and watch mode for continuous processing.

When to Use

✅ USE this skill when:

• User wants to automatically fix bugs from GitHub issues
• Processing multiple issues in batch mode
• Setting up continuous issue fixing with watch mode
• User asks to "fix all open bugs" or "process the issue queue"

❌ DON'T use this skill when:

• Single issue that needs manual review first
• Issues requiring user input/clarification
• Non-GitHub task trackers (use appropriate tools)

Installation

# Requires git, gh CLI, and curl (usually pre-installed)
npm install -g @cli/gh  # If not already installed

Setup

Token Configuration

The skill needs GH_TOKEN environment variable. Check in order:

1. Environment variable: echo $GH_TOKEN
2. Config file: cat ~/.thepopebot/config.json | jq -r '.skills."gh-issues".apiKey'
3. GitHub secrets (for Docker agent): AGENT_GH_TOKEN

Fork Mode (Optional)

For contributing to repos you don't own:

# Set up your fork
gh repo fork owner/repo --clone=false

Usage

Basic Usage

# Process issues from current repo
node {baseDir}/index.js owner/repo --limit 5

# Process with filters
node {baseDir}/index.js owner/repo --label bug --limit 10 --milestone v1.0

# Watch mode (continuous)
node {baseDir}/index.js owner/repo --watch --interval 5

# Dry run (preview only)
node {baseDir}/index.js owner/repo --dry-run --limit 5

Command Line Flags

Architecture

6-Phase Workflow

Phase 1: Parse Arguments
    ↓
Phase 2: Fetch Issues (GitHub API via curl)
    ↓
Phase 3: Confirm Processing (unless --yes)
    ↓
Phase 4: Spawn Sub-agents (parallel)
    ↓
Phase 5: Monitor & Wait (unless --cron)
    ↓
Phase 6: Handle PR Reviews (if --watch)

Phase 2: Fetch Issues

Uses GitHub REST API directly (no gh CLI for fetching):

curl -s \
  -H "Authorization: Bearer $GH_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/owner/repo/issues?state=open&per_page=10"

Query Parameters:

• state: open, closed, or all
• labels: Comma-separated list (e.g., bug,help-wanted)
• milestone: Milestone number or * for any
• assignee: Username or @me
• per_page: 1-100 (default 30)
• sort: created, updated, comments
• direction: asc or desc

Phase 4: Spawn Sub-agents

For each issue, spawn a sub-agent with:

• Issue title and description
• Comments thread
• Repo context
• Branch naming convention: fix/issue-<number>-<slug>

Example sub-agent prompt:

Fix GitHub issue #123: "Button color wrong"

Issue Body:
The submit button uses #ff0000 instead of #00ff00...

Comments:
- User1: Can you also update the hover state?
- Maintainer: This affects all themes

Branch: fix/issue-123-button-color

Phase 5: Monitor PRs

Track sub-agent progress:

• ✅ Branch created
• ✅ Code committed
• ✅ PR opened
• ⏳ Awaiting review
• ✅ Merged / ❌ Closed

Implementation Structure

gh-issues/
├── SKILL.md              # This file
├── index.js              # Main entry point
├── fetch-issues.js       # GitHub API client
├── spawn-agent.js        # Sub-agent spawner
├── monitor-prs.js        # PR status tracker
└── utils/
    ├── repo-parser.js    # Parse owner/repo from args/git remote
    └── token-resolver.js # Resolve GH_TOKEN from env/config

Examples

Fix All Bug Issues

// Process up to 5 issues labeled "bug"
node index.js myorg/myrepo --label bug --limit 5 --yes

Watch Mode for Continuous Fixes

// Watch for new issues, process every 5 minutes
node index.js myorg/myrepo --label bug --watch --interval 5 --notify-channel -1002381931352

Contributing to External Repo

# Process issues from upstream, push to your fork
node index.js upstream/repo --fork yourname/repo --label "good first issue" --limit 3

Cron Mode (Fire-and-Forget)

# Spawn agents and exit (good for cron jobs)
node index.js myorg/myrepo --label bug --cron --limit 10

Error Handling

Common Issues

1. Token Expired: Refresh GH_TOKEN and retry
2. Rate Limited: Wait or use --interval to space requests
3. Permission Denied: Check repo access or use fork mode
4. Branch Exists: Append timestamp to branch name
5. PR Already Open: Skip or update existing PR

Retry Logic

const MAX_RETRIES = 3;
const RETRY_DELAY = 5000; // 5 seconds

async function fetchWithRetry(url, options) {
  for (let i = 0; i < MAX_RETRIES; i++) {
    try {
      return await fetch(url, options);
    } catch (err) {
      if (i === MAX_RETRIES - 1) throw err;
      await sleep(RETRY_DELAY * (i + 1));
    }
  }
}

Best Practices

1. Start Small: Test with --limit 1 first
2. Use Labels: Filter to specific issue types
3. Dry Run First: Always test with --dry-run before full execution
4. Monitor Closely: Watch first few PRs before enabling auto-merge
5. Respect Maintainers: Don't spam repos with low-quality PRs

Security Notes

• Never commit GH_TOKEN to git
• Use scoped tokens with minimal permissions
• Review sub-agent code before merging
• Set appropriate ALLOWED_PATHS for auto-merge

Testing

# Test token resolution
node index.js --dry-run --limit 1

# Test issue fetching (no agents)
node index.js owner/repo --dry-run --limit 5

# Test with single issue
node index.js owner/repo --limit 1 --yes

Integration with PopeBot

This skill integrates with PopeBot's agent system:

• Uses delegate-task skill for spawning sub-agents
• Leverages github-ops for PR monitoring
• Sends notifications via existing PopeBot channels
• Logs all activity to PopeBot session logs

References

• GitHub Issues API
• GitHub Pull Requests API
• GitHub Token Permissions