get-gh-issue

NAME

get-gh-issue - fetch GitHub issue data via the GitHub CLI

SYNOPSIS

state-name:
  tool: get-gh-issue
  arguments:
    issue-number: <number>
    format: <format>                # optional
    include-title: <boolean>        # optional
    include-description: <boolean>  # optional
    include-comments: <boolean>     # optional

DESCRIPTION

The get-gh-issue tool fetches issue details from GitHub using the gh CLI. It automatically detects the repository from the git remote and retrieves the specified issue’s title, body, and comments.

The tool requires the GitHub CLI (gh) to be installed and authenticated.

ARGUMENTS

Argument	Required	Default	Description
`issue-number`	Yes	-	GitHub issue number (with or without `#`)
`format`	No	`json`	Output format: `json` or `markdown`
`include-title`	No	`true`	Include issue title
`include-description`	No	`true`	Include issue body
`include-comments`	No	`true`	Include issue comments

EXIT CODES

Code	Meaning
`0`	Success
`1`	General error
`2`	Not in a git repository
`3`	Issue not found
`4`	Access denied (authentication required)
`5`	Rate limit exceeded
`6`	GitHub CLI not installed
`7`	Network or temporary error

OUTPUT

JSON format (default) includes all issue fields plus comments array:

{
  "number": 123,
  "title": "Issue title",
  "body": "Issue description...",
  "state": "open",
  "comments": [
    {
      "user": {"login": "username"},
      "body": "Comment text..."
    }
  ]
}

Markdown format provides human-readable output:

# Issue #123

## Issue title

Issue description...

## Comments

### username

Comment text...

EXAMPLES

Fetch Issue as JSON

get-issue:
  tool: get-gh-issue
  arguments:
    issue-number: 123
  output: var(issue_json)

Fetch Issue as Markdown

get-issue:
  tool: get-gh-issue
  arguments:
    issue-number: "#456"
    format: markdown
  output: file(./issue.md)

Minimal Fetch (Title Only)

get-title:
  tool: get-gh-issue
  arguments:
    issue-number: 789
    include-description: false
    include-comments: false
  output: var(issue_data)

Error Handling

fetch-issue:
  tool: get-gh-issue
  arguments:
    issue-number: "{{ issue_num }}"
  output: var(issue)
  on-error:
    3: issue-not-found
    4: auth-required
    5: rate-limited
    6: gh-not-installed
    _: network-error
  next: process-issue

issue-not-found:
  tool: bash
  arguments:
    command: 'echo "Issue #{{ issue_num }} not found" >&2 && exit 1'

auth-required:
  tool: bash
  arguments:
    command: |
      echo "GitHub authentication required. Run: gh auth login"
      exit 1

rate-limited:
  tool: bash
  arguments:
    command: |
      echo "GitHub API rate limit exceeded. Authenticate with gh auth login for higher limits."
      exit 1

gh-not-installed:
  tool: bash
  arguments:
    command: |
      echo "GitHub CLI not found. Install from https://cli.github.com"
      exit 1

Use Issue Data with AI

start-at: fetch-issue

states:
  fetch-issue:
    tool: get-gh-issue
    arguments:
      issue-number: "{{ issue_number }}"
      format: markdown
    output: var(issue_content)
    next: analyze

  analyze:
    tool: claude
    arguments:
      prompt: |
        Analyze this GitHub issue and suggest an implementation approach:

        {{ issue_content }}
    output: var(analysis)

Workflow Triggered by Issue

name: implement-feature
start-at: load-issue

variables:
  issue_number: ""

states:
  load-issue:
    tool: get-gh-issue
    arguments:
      issue-number: "{{ issue_number }}"
      format: markdown
    output: file(./context/issue.md)
    next: implement

  implement:
    tool: claude-code
    arguments:
      prompt: |
        Implement the feature described in this issue:

        {{ file(./context/issue.md) }}

PREREQUISITES

GitHub CLI Installation

# macOS
brew install gh

# Linux
# See https://cli.github.com/manual/installation

Authentication

gh auth login

Follow the prompts to authenticate with GitHub.

Repository Detection

The tool detects the repository from git remote get-url origin. Supported formats:

HTTPS: https://github.com/owner/repo.git
SSH: git@github.com:owner/repo.git