Managing GitHub Issues

Reference for managing GitHub issues from the command line using the gh CLI. Covers the full gh issue surface, milestone management (which gh does not expose directly), plus patterns that aren't obvious from --help.

Autonomy note: This is a pure reference skill — look up the command and proceed. When invoked by an autonomous skill (ss-agile-*), do NOT introduce confirmations or interactive prompts beyond what gh itself requires. Prefer non-interactive flags everywhere (--title, --body, --body-file -, --yes); never use --web.

Prerequisites

• gh is installed and authenticated (gh auth status shows a logged-in account).
• The working directory is inside a git repo with a GitHub remote, OR every command passes -R OWNER/REPO.
• Some operations need extra scopes: adding/removing projects requires the project scope (gh auth refresh -s project).

Issue identifiers

Every command that targets an issue accepts either:

• a number: 123
• a full URL: https://github.com/OWNER/REPO/issues/123

gh issue edit is the only command that accepts multiple issue numbers in one invocation.

Quick reference

Core CRUD

Comments

--edit-last and --delete-last only act on your own most recent comment on the issue.

Labels, milestones, assignees, projects

Labels and milestones must already exist on the repo — gh does not create them on the fly. To create them first:

• Labels: gh label create NAME --color RRGGBB --description "..."
• Milestones: gh has no gh milestone subcommand; use gh api (see "Managing milestones" below).

Filtering & search

--search uses GitHub's issue/PR search syntax (is:open, no:label, created:>2026-01-01, etc.). Full reference: https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests

When --search is used, the other filter flags are still honored and AND-ed together.

State, pinning, locking, transfer

--reason for lock accepts: off_topic, resolved, spam, too_heated.

Linked development branches

The branch is registered on the issue and a PR opened from it will auto-link.

JSON output & scripting

Any read command (view, list, status) supports --json FIELDS [--jq EXPR | --template TPL].

Available JSON fields (same on view, list, status): assignees, author, body, closed, closedAt, closedByPullRequestsReferences, comments, createdAt, id, isPinned, labels, milestone, number, projectCards, projectItems, reactionGroups, state, stateReason, title, updatedAt, url

Managing milestones

gh has no gh milestone subcommand. All milestone operations go through gh api against the REST endpoint repos/:owner/:repo/milestones. Path placeholders :owner and :repo are auto-substituted when running inside a repo; pass -R owner/repo or expand them manually when targeting another repo.

Key fields when creating:

• title (required, string)
• state (open / closed, default open)
• description (string)
• due_on (ISO 8601 timestamp, e.g. 2026-06-01T00:00:00Z)

To capture the number of a freshly created milestone:

MS_NUM=$(gh api repos/:owner/:repo/milestones \
  -f title="Sprint 1" -f description="..." \
  --jq .number)
gh issue create --title "First task" --milestone "Sprint 1" --body "..."
# or assign by name later:
gh issue edit 123 --milestone "Sprint 1"

Note: gh issue edit --milestone NAME and gh issue create --milestone NAME reference milestones by title, not number. Pick titles that won't collide.

Common patterns

Multi-line body from a heredoc

gh issue create --title "Crash on startup" --body "$(cat <<'EOF'
## Steps
1. Run `app --serve`
2. Visit localhost:3000

## Expected
Page loads.

## Actual
Crashes with stack trace below.
EOF
)"

For longer bodies, write a file and use --body-file path.md. Use --body-file - to pipe from another command.

Link a PR to close an issue automatically

Put one of these keywords in the PR body (case-insensitive): Closes #N, Fixes #N, Resolves #N. When the PR merges, GitHub closes the issue. Other variants: close, closed, fix, fixed, resolve, resolved.

For cross-repo: Closes owner/repo#N.

Find linking PRs for an issue

gh issue view 123 --json closedByPullRequestsReferences --jq '.closedByPullRequestsReferences[]'

Bulk operation: close all issues with a label

gh issue list --label stale --limit 1000 --json number --jq '.[].number' \
  | xargs -I{} gh issue close {} --reason "not planned" --comment "Closing stale."

"My open issues across the repo" one-liner

gh issue list --search "is:open assignee:@me" --json number,title,updatedAt

Create and immediately start work

NUM=$(gh issue create --title "Refactor auth" --body "..." --label refactor \
        --json number --jq .number)
gh issue develop "$NUM" --checkout

Note: gh issue create itself does not accept --json/--jq — it prints the issue URL. To capture the number, either parse the URL or gh issue list --search "..." --json number after creation. The snippet above works on gh 2.79+ where create returns the URL on stdout; if older, use:

URL=$(gh issue create --title "T" --body "B")
NUM=${URL##*/}
gh issue develop "$NUM" --checkout

Gotchas

• Labels/milestones must exist first. --label foo on a nonexistent label fails. Create labels with gh label create foo --color "ededed".
• `--state` default is `open`. To see closed too: --state all or --state closed.
• List `--limit` defaults to 30. Pagination silently truncates if you forget to raise it.
• Close reasons are exact strings. Valid: completed, not planned, duplicate. Anything else errors.
• `--web` opens a browser. Never use in scripts/CI — it blocks and is non-deterministic.
• *`--edit-last` / `--delete-last` are scoped to your comments only*, not the latest comment by anyone.
• `gh issue edit` accepts multiple numbers (gh issue edit 1 2 3 --add-label bug); most other commands take exactly one.
• `gh issue delete` is irreversible and requires --yes for non-interactive use. Prefer close --reason "not planned" unless the issue is truly garbage (spam, accidental).
• `@me` / `@copilot` only work for the assignee flags, not author/mention filters — those need a real login.
• Cross-repo `-R` flag can go anywhere on the command line, but commands run on the current repo unless you set it. Easy to accidentally edit the wrong repo's issue when working in a clone.
• Free-form `--search` overrides default state filter. gh issue list --search "is:closed" works even though the default state is open — but --search "anything" --state open is redundant and is: in the query wins.

When to use gh api instead

gh issue is convenient for the common 90%. Drop down to gh api when you need:

• Reactions: gh api repos/:owner/:repo/issues/123/reactions
• Timeline events (closed-by, referenced, cross-references): gh api repos/:owner/:repo/issues/123/timeline
• Mutating fields gh issue edit doesn't expose (e.g., issue type on GraphQL).
• Pagination beyond --limit for very large queries — gh api --paginate graphql -f query=....
• Bulk operations where rate-limit headers matter.

Example: count open issues by label, server-side:

gh api graphql -f query='
  query($owner:String!, $repo:String!) {
    repository(owner:$owner, name:$repo) {
      issues(states:OPEN, first:0) { totalCount }
    }
  }' -F owner=OWNER -F repo=REPO

When NOT to use this skill

• The user is asking about pull requests, not issues — those use gh pr ... (different subcommand surface).
• The user wants to edit GitHub Discussions, Projects, or Releases — separate gh subcommands.
• The user wants a one-off web action (filing a single issue via the UI) — just open the repo in a browser.