Triage GitHub Issues with a CLI

---
name: triage-github-issues-workflow
description: "Read open issues as structured data, group them by evidence and urgency, then propose rather than silently apply changes."
---

# Triage GitHub issues

## Intended outcome

Turn an issue queue into an actionable triage report without losing user context or changing state unexpectedly.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **GitHub CLI** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 2.86.0 recorded)
  - Install: `brew install gh`
  - Authentication: OAuth, personal access token, GitHub Actions token
  - Minimum permissions: Use a read-only or fine-grained token limited to the required repositories.
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
  - Install: `brew install jq`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.

## Input contract

- Repository name
- triage criteria
- label taxonomy
- read-scoped GitHub identity

## Output contract

- Grouped issue list
- duplicate candidates
- label suggestions
- approved update commands

## Safe workflow

1. **Collect the queue** — List issues with labels, timestamps, authors, and URLs in JSON.
   - Input: Repository and search boundary
   - Output: Structured issue dataset
   - Risk: `read-only`
   - Command: `gh issue list --state open --limit 100 --json number,title,labels,author,updatedAt,url`
2. **Group and verify** — Group by topic and urgency, then open likely duplicates before making a claim.
   - Input: Issue dataset and triage rules
   - Output: Triage table with evidence
   - Risk: `read-only`
3. **Propose updates** — Show exact label, assignee, or close commands only for accepted decisions.
   - Input: Approved triage decisions
   - Output: Reviewable update commands
   - Risk: `remote-write`
   - Command: `gh issue edit 123 --add-label "needs-repro"`

## Ask before proceeding

- Adding or removing labels
- Assigning people or milestones
- Closing, reopening, or editing an issue

## Rollback

- Remove an incorrect label
- Reopen an issue with a correction note
- Keep the pre-change JSON export

## Official sources

- [GitHub CLI manual](https://cli.github.com/manual/) — Official command, authentication, JSON field, and workflow documentation.
- [GitHub REST API documentation](https://docs.github.com/en/rest) — Official HTTP API and authentication reference for GitHub resources.