GitHub Issue Fetcher

Overview

Fetch GitHub issues from the current repository using the gh CLI tool with flexible sorting, filtering, and field extraction capabilities. This skill provides patterns for common workflows like getting the next issue to work on, extracting specific fields, and querying issues with custom criteria.

Prerequisites

This skill requires two command-line tools to be installed:

1. GitHub CLI (gh) - Official GitHub command-line tool
2. jq - JSON processor for parsing command output

Checking Dependencies

Before executing issue commands, verify both tools are available:

# Check if gh is installed
command -v gh >/dev/null 2>&1 || echo "gh not found"

# Check if jq is installed
command -v jq >/dev/null 2>&1 || echo "jq not found"

Installation Guidance

If a required tool is missing, provide the user with installation instructions based on their platform:

GitHub CLI (gh):

• macOS: brew install gh
• Linux (Debian/Ubuntu): sudo apt install gh
• Linux (Fedora/RHEL): sudo dnf install gh
• Windows: winget install --id GitHub.cli
• Other: Visit https://cli.github.com/

jq:

• macOS: brew install jq
• Linux (Debian/Ubuntu): sudo apt-get install jq
• Linux (Fedora/RHEL): sudo dnf install jq
• Windows: winget install jqlang.jq
• Other: Visit https://jqlang.github.io/jq/download/

GitHub Authentication

The gh CLI requires authentication. If the user encounters authentication errors, guide them to run:

gh auth login

This will prompt them through the authentication flow.

Core Capabilities

1. Detecting the Current Repository

To automatically determine the current repository, use git commands:

# Get the repository in owner/repo format
REPO=$(git config --get remote.origin.url | sed -E 's|.*github\.com[:/]([^/]+/[^.]+)(\.git)?|\1|')

Alternatively, let gh auto-detect by omitting the --repo flag when running from within a git repository directory.

2. Fetching the Next Issue

The "next issue" defaults to the oldest created open issue. Use gh issue list with sorting and limiting:

# Get the oldest created issue (next to work on)
gh issue list --search "sort:created-asc" --limit 1 --json number,title,body,labels,assignees,milestone,state,url

3. Extracting Specific Fields

Use jq to extract specific fields from the JSON output:

# Get just the issue number
gh issue list --search "sort:created-asc" --limit 1 --json number | jq '.[0].number'

# Get just the issue body
gh issue list --search "sort:created-asc" --limit 1 --json body | jq -r '.[0].body'

# Get just the issue title
gh issue list --search "sort:created-asc" --limit 1 --json title | jq -r '.[0].title'

# Get multiple fields in a formatted way
gh issue list --search "sort:created-asc" --limit 1 --json number,title,body | jq -r '.[0] | "Issue #\(.number): \(.title)\n\n\(.body)"'

Note: Use -r flag with jq to output raw strings without quotes.

4. Available Fields

The --json flag accepts the following fields:

• number - Issue number
• title - Issue title
• body - Issue body/description
• labels - Array of label objects
• assignees - Array of assignee objects
• milestone - Milestone object
• state - Issue state (OPEN, CLOSED)
• url - Issue URL
• createdAt - Creation timestamp
• updatedAt - Last update timestamp
• closedAt - Close timestamp (if closed)
• comments - Number of comments
• author - Author object

5. Sorting Options

Use the --search flag with sort qualifiers:

# Oldest created (default for "next issue")
--search "sort:created-asc"

# Newest created
--search "sort:created-desc"

# Most recently updated
--search "sort:updated-desc"

# Least recently updated
--search "sort:updated-asc"

# Most commented
--search "sort:comments-desc"

# Least commented
--search "sort:comments-asc"

Note: GitHub doesn't have a native "priority" sort, but priority can be inferred from labels, milestones, or projects.

6. Filtering Options

Combine multiple filters in the --search query:

# Filter by label
--search "label:bug sort:created-asc"

# Filter by assignee
--search "assignee:username sort:created-asc"

# Filter by milestone
--search "milestone:\"v1.0\" sort:created-asc"

# Filter by state (default is open)
--search "is:open sort:created-asc"
--search "is:closed sort:created-desc"

# Combine multiple filters
--search "label:bug assignee:@me is:open sort:created-asc"

# No assignee
--search "no:assignee sort:created-asc"

# No label
--search "no:label sort:created-asc"

7. Common Patterns

Get the next issue to work on:

gh issue list --search "sort:created-asc" --limit 1 --json number,title,body

Get just the issue number for scripting:

ISSUE_NUM=$(gh issue list --search "sort:created-asc" --limit 1 --json number | jq '.[0].number')

Get the full issue body text:

gh issue list --search "sort:created-asc" --limit 1 --json body | jq -r '.[0].body'

Get the most urgent unassigned bug:

gh issue list --search "label:bug no:assignee sort:created-asc" --limit 1 --json number,title,body

List all high-priority issues:

gh issue list --search "label:priority-high sort:created-asc" --json number,title,labels

Usage Workflow

When a user requests GitHub issue information:

1. Verify dependencies: Check that gh and jq are installed; if not, provide installation guidance
2. Determine the repository context: Check if running in a git repository, or ask the user for the repo name
3. Understand the request: Identify what fields they need (body, number, title, etc.)
4. Apply appropriate sorting: Default to sort:created-asc for "next issue" requests, adjust based on user needs
5. Apply filters if specified: Add label, assignee, or other filters to the search query
6. Construct the command: Build the gh issue list command with appropriate flags
7. Extract fields: Use jq to parse and extract only the requested fields
8. Present results: Return the extracted data in the format the user needs

Examples

User request: "What's the next GitHub issue to work on?"

gh issue list --search "sort:created-asc" --limit 1 --json number,title | jq -r '.[0] | "#\(.number): \(.title)"'

User request: "Give me the body of the next GitHub issue"

gh issue list --search "sort:created-asc" --limit 1 --json body | jq -r '.[0].body'

User request: "Show me the newest bug with no assignee"

gh issue list --search "label:bug no:assignee sort:created-desc" --limit 1 --json number,title,body | jq -r '.[0] | "Issue #\(.number): \(.title)\n\n\(.body)"'