skmuiruri

The gh issue command manages the full lifecycle of GitHub Issues.

Creating an Issue

# Interactive — prompts for title, body, labels, etc.
gh issue create
 
# Non-interactive
gh issue create --title "Bug: login fails" --body "Steps to reproduce..."
 
# Open your editor for the body
gh issue create --title "Feature request" --editor
 
# With metadata
gh issue create \
  --title "Fix typo in docs" \
  --body "Page X has a typo" \
  --label bug,docs \
  --assignee @me \
  --milestone v2.0 \
  --project "Roadmap"

Working with a Different Repository

All gh issue commands accept -R owner/repo:

gh issue create -R cli/cli --title "My issue"
gh issue list -R cli/cli

If you are inside a cloned repository, the -R flag is not needed.

Listing Issues

# Default: 30 open issues
gh issue list
 
# More results
gh issue list --limit 100
 
# Filter by state
gh issue list --state closed
gh issue list --state all
 
# Filter by label
gh issue list --label bug
gh issue list --label "bug,help wanted"
 
# Filter by assignee
gh issue list --assignee @me
gh issue list --assignee octocat
 
# Filter by author
gh issue list --author octocat
 
# Filter by milestone
gh issue list --milestone v2.0
 
# Search within issues
gh issue list --search "login error"
 
# JSON output
gh issue list --json number,title,labels --jq '.[].title'

Viewing an Issue

# View in the terminal (rendered markdown)
gh issue view 123
 
# Open in the browser
gh issue view 123 --web
gh issue view 123 -w
 
# JSON output
gh issue view 123 --json title,body,comments

Editing an Issue

# Interactive
gh issue edit 123
 
# Non-interactive
gh issue edit 123 --title "Updated title"
gh issue edit 123 --body "Updated body"
gh issue edit 123 --add-label enhancement --remove-label bug
gh issue edit 123 --add-assignee octocat
gh issue edit 123 --milestone v2.0
gh issue edit 123 --add-project "Roadmap"

Commenting on an Issue

# Open your editor
gh issue comment 123
 
# Inline
gh issue comment 123 --body "Thanks for reporting this!"
 
# Open the comment in the browser instead
gh issue comment 123 --web

Closing and Reopening

gh issue close 123
gh issue close 123 --comment "Fixed in #125" --reason completed
gh issue close 123 --reason "not planned"
 
gh issue reopen 123

Pinning and Unpinning

gh issue pin 123
gh issue unpin 123

Locking and Unlocking

gh issue lock 123 --reason "off-topic"
gh issue unlock 123

Lock reasons: off-topic, too heated, resolved, spam.

Transferring an Issue

gh issue transfer 123 target-owner/target-repo

Deleting an Issue

gh issue delete 123 --yes

Developing Against an Issue

Create a linked development branch for an issue:

# Create a branch linked to the issue (auto-named from issue title)
gh issue develop 123
 
# Specify the branch name and base
gh issue develop 123 --name fix-login-bug --base main
 
# Create the branch on a different repo (for forks)
gh issue develop 123 --branch-repo myuser/my-fork
 
# Create and immediately check out the branch
gh issue develop 123 --checkout
 
# List branches linked to an issue
gh issue develop 123 --list

When a PR from a linked branch is merged, the issue is automatically closed. This is the recommended workflow for tracking which branches address which issues.

Checking Issue Status

See issues relevant to you across the current repository:

gh issue status

This shows:

  • Issues assigned to you
  • Issues mentioning you
  • Issues you opened

Exercises

  1. Create a test issue: gh issue create --title "Test issue" --body "Testing gh CLI"
  2. List all open issues: gh issue list
  3. View the issue you created: gh issue view <number>
  4. Add a comment: gh issue comment <number> --body "Adding a comment"
  5. Close it: gh issue close <number> --reason completed
Previous← RepositoriesNextPull Requests →