Github Issues Processor

Process GitHub issues in bulk or individually using the GitHub API, supporting creation, updates, labeling, assignment, commenting, and search operations from the command line.

When to Use This Command

Run this command when...

• You need to create, update, or triage multiple GitHub issues based on project requirements or bug reports
• Sprint planning requires bulk issue creation with proper labels, milestones, and assignments
• You want to search and filter existing issues to understand the current backlog state
• Bug reports or feature requests need to be converted into properly formatted GitHub issues
• You need to add comments, update labels, or close issues across a batch of related items

Quick Start

Copy
# .claude/commands/github-issues-processor.md
---
name: Github Issues Processor
description: Create, update, and manage GitHub issues via API
command: true
---
Process GitHub issues: $ARGUMENTS

Use the GitHub CLI and API to manage issues:
1. Determine the action (create, update, search, comment)
2. Gather repository context and existing labels/milestones
3. Execute the requested operation
4. Report results with issue URLs

Copy
# Invoke the command
claude "/github-issues-processor create 5 issues for the authentication epic"

# Expected output
# > Repository: myorg/myapp (main branch)
# > Available labels: bug, feature, enhancement, auth, priority-high
# > Creating issues for authentication epic...
# >   #142: Implement JWT token refresh mechanism [auth, feature]
# >   #143: Add OAuth2 Google provider integration [auth, feature]
# >   #144: Create MFA enrollment and verification flow [auth, feature]
# >   #145: Build session management with Redis [auth, enhancement]
# >   #146: Write authentication integration test suite [auth, testing]
# > All 5 issues created and labeled.
# > Epic link: https://github.com/myorg/myapp/issues?q=label:auth

Core Concepts

Concept	Description
Batch Operations	Creates, updates, or labels multiple issues in a single command execution
Context Awareness	Reads existing labels, milestones, and assignees from the repository before acting
Search and Filter	Queries issues by label, assignee, milestone, state, or full-text search
Comment Threading	Adds contextual comments to existing issues with formatted markdown content
Cross-Referencing	Links related issues, pull requests, and milestones for traceability

Issue Processing Workflow
==========================

  Input: Action + Details
         |
  [Determine Operation]
  Create | Update | Search | Comment | Close
         |
  [Gather Context]
  Repo info | Labels | Milestones | Assignees
         |
  [Execute via GitHub API]
  gh issue create | gh issue edit | gh api
         |
  [Report Results]
  Issue URLs | Status | Summary

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Action and details for issue processing	none	"create bug report for login failure"	Yes
repository	Target GitHub repository	current repo	"myorg/myapp"	No
labels	Labels to apply to created or updated issues	none	"bug,priority-high"	No
milestone	Milestone to assign issues to	none	"Sprint 14"	No
assignee	GitHub username to assign issues to	none	"@me"	No

Best Practices

1. Use consistent label taxonomies -- Establish and follow a labeling standard (type labels, priority labels, area labels) so issue filtering and reporting work reliably.

2. Include acceptance criteria in issue bodies -- When creating feature issues, add checkboxes for acceptance criteria so the definition of done is clear from the start.

3. Reference related issues -- Use "Related to #123" or "Blocks #456" syntax in issue bodies to build a navigable issue graph for complex features.

4. Assign milestones for sprint planning -- Attach issues to milestones so sprint progress can be tracked through GitHub milestone views and burned down over the sprint.

5. Batch-create from specifications -- For epics or large features, write a specification document and let the processor convert each requirement into a separate, linked issue.

Common Issues

GitHub CLI not authenticated: The processor requires gh auth login to have been completed. If authentication fails, run gh auth status to diagnose and gh auth login to re-authenticate.

Label does not exist: Creating issues with labels that do not exist in the repository causes failures. The processor checks for existing labels but cannot create new ones without permission. Create labels in GitHub settings first.

Rate limiting on bulk operations: Creating many issues rapidly can trigger GitHub API rate limits. The processor adds delays between API calls, but very large batches (50+) may need to be split across multiple invocations.