---
name: tracker/gh-cli:issue-search
description: Search GitHub issues (gh-cli implementation of the abstract tracker issue-search op)
version: "0.4.0"
---

# Issue Search (GitHub)

gh-cli implementation of the abstract `tracker:issue-search` operation. Searches issues in the current repository using GitHub's search syntax. Note: GitHub search uses its own query syntax (not JQL), and parent/epic relationships are expressed via labels or task lists rather than a `parent` field — callers passing JQL-style `parent = KEY-123` queries must translate to a label or sub-issue convention.

## Parameters

| Parameter | Type   | Required | Description                                        |
| --------- | ------ | -------- | -------------------------------------------------- |
| query     | string | Yes      | GitHub search query (e.g. `label:epic state:open`) |
| max       | number | No       | Maximum results (default: 20)                      |

## Implementation

```bash
gh issue list \
  --search "{query}" \
  --json number,title,state,assignees,labels,url \
  --limit {max || 20}
```

## Output

| Field  | Type     | Description                                                      |
| ------ | -------- | ---------------------------------------------------------------- |
| issues | object[] | Array of `{ id (number), title, status (state), assignee, url }` |

## Errors

| Code        | Cause                         | Recovery                           |
| ----------- | ----------------------------- | ---------------------------------- |
| NOT_A_REPO  | Not in a git repository       | Navigate to a repository directory |
| AUTH_FAILED | Not authenticated with gh CLI | Run `gh auth login`                |

## Used By

- dev-sprint (find sprint epics and child issues)
- dev-feature (fetch child issues under an epic)
