claude-code-skills-reference/github-ops/references/issue_operations.md

Issue Operations Reference

Comprehensive examples for GitHub issue management using gh CLI.

Creating Issues

Basic Issue Creation

# Create simple issue
gh issue create --title "Bug: Issue title" --body "Issue description"

# Create issue with labels and assignees
gh issue create --title "Bug: Title" --body "Description" \
  --label bug,priority-high --assignee username

# Create issue from template
gh issue create --template bug_report.md

# Create issue with body from file
gh issue create --title "Feature Request" --body-file feature.md

---

Listing Issues

Basic Listing

# List all issues
gh issue list

# List issues with filters
gh issue list --state open --label bug
gh issue list --assignee username
gh issue list --milestone "v2.0"

# List with pagination
gh issue list --limit 50

Advanced Filtering

# List issues by multiple labels
gh issue list --label "bug,priority-high"

# List issues NOT assigned to anyone
gh issue list --assignee ""

# List issues mentioned in PR
gh issue list --mention username

# List recently updated issues
gh issue list --state all --limit 10

---

Viewing Issues

Viewing Details

# View specific issue
gh issue view 456

# View issue in browser
gh issue view 456 --web

# View issue with comments
gh issue view 456 --comments

# Get issue as JSON
gh issue view 456 --json number,title,body,state,labels,assignees

---

Editing Issues

Update Issue Metadata

# Edit issue title
gh issue edit 456 --title "New title"

# Edit issue body
gh issue edit 456 --body "Updated description"

# Add labels
gh issue edit 456 --add-label enhancement,documentation

# Remove labels
gh issue edit 456 --remove-label wip

# Add assignees
gh issue edit 456 --add-assignee user1,user2

# Remove assignees
gh issue edit 456 --remove-assignee user1

# Set milestone
gh issue edit 456 --milestone "v2.0"

# Remove milestone
gh issue edit 456 --milestone ""

---

Issue Lifecycle

State Management

# Close issue
gh issue close 456

# Close issue with comment
gh issue close 456 --comment "Fixed in PR #789"

# Reopen issue
gh issue reopen 456

# Reopen with comment
gh issue reopen 456 --comment "Issue persists in v2.0"

Issue Linking

# Link to PR in issue (manual)
gh issue comment 456 --body "Fixed by #789"

# Close issue when PR merges (in PR description)
# Use keywords: closes, fixes, resolves
gh pr create --title "Fix bug" --body "Closes #456"

---

Commenting on Issues

Adding Comments

# Add comment to issue
gh issue comment 456 --body "Comment text"

# Add comment from file
gh issue comment 456 --body-file comment.txt

# Add comment with emoji reactions
gh issue comment 456 --body "Great idea! :+1:"

---

Issue Pinning and Priority

Pinning Issues

# Pin issue to repository
gh issue pin 456

# Unpin issue
gh issue unpin 456

---

Issue Transfers

Transfer to Another Repository

# Transfer issue to another repo
gh issue transfer 456 owner/other-repo

---

Bulk Operations

Operating on Multiple Issues

# Close all bug issues
gh issue list --label bug --json number -q '.[].number' | \
  xargs -I {} gh issue close {}

# Add label to all open issues
gh issue list --state open --json number -q '.[].number' | \
  xargs -I {} gh issue edit {} --add-label "needs-triage"

# Assign milestone to multiple issues
gh issue list --label "v2.0" --json number -q '.[].number' | \
  xargs -I {} gh issue edit {} --milestone "Release 2.0"

---

Output Formatting

JSON Output

# Get issue data as JSON
gh issue view 456 --json number,title,body,state,labels,assignees,milestone

# List issues with custom fields
gh issue list --json number,title,state,createdAt,updatedAt

# Process with jq
gh issue list --json number,title,labels | \
  jq '.[] | select(.labels | any(.name == "bug"))'

Template Output

# Custom format with Go templates
gh issue list --template '{{range .}}#{{.number}}: {{.title}} [{{.state}}]{{"\n"}}{{end}}'

---

Search Operations

Using GitHub Search Syntax

# Search issues with text
gh issue list --search "error in logs"

# Search issues by author
gh issue list --search "author:username"

# Search issues by label
gh issue list --search "label:bug"

# Complex search queries
gh issue list --search "is:open label:bug created:>2024-01-01"

---

Best Practices

Creating Effective Issues

1. Use descriptive titles - Be specific about the problem
2. Provide context - Include steps to reproduce
3. Add labels - Help with categorization and filtering
4. Assign appropriately - Tag people who can help
5. Link related items - Connect to PRs, other issues

Issue Management

1. Triage regularly - Review and label new issues
2. Update status - Keep issues current with comments
3. Close resolved issues - Link to fixing PR
4. Use milestones - Group related work
5. Pin important issues - Highlight key items

Labels Strategy

Common label categories:

• Type: bug, feature, enhancement, documentation
• Priority: priority-high, priority-medium, priority-low
• Status: wip, needs-review, blocked
• Area: frontend, backend, database, infrastructure

Automation Tips

1. Issue templates - Create templates for bugs, features
2. Auto-labeling - Use GitHub Actions to auto-label
3. Stale bot - Auto-close inactive issues
4. Project boards - Track issue progress
5. Webhooks - Integrate with external tools