github-cli

Use when

• Creating, viewing, or merging pull requests
• Managing issues (create, close, comment)
• Checking workflow/action status
• Creating releases
• Cloning or forking repos

Don't use when

• Local git operations (use git directly)
• Non-GitHub remotes (GitLab, Bitbucket)

Outputs

• PRs, issues, releases, or action logs in GitHub (no local files unless explicitly created).

Templates or Examples

• Use the command tables below as templates.

Prerequisites

• gh CLI installed
• SSH key configured for GitHub access

Quick Reference

Pull Requests

| Action | Command | |--------|---------| | List PRs | gh pr list | | View PR | gh pr view <number> | | Create PR | gh pr create --title "..." --body "..." | | Checkout PR | gh pr checkout <number> | | Merge PR | gh pr merge <number> | | PR diff | gh pr diff <number> | | PR checks | gh pr checks <number> |

Issues

| Action | Command | |--------|---------| | List issues | gh issue list | | View issue | gh issue view <number> | | Create issue | gh issue create --title "..." --body "..." | | Close issue | gh issue close <number> | | Comment | gh issue comment <number> --body "..." |

Repos & Releases

| Action | Command | |--------|---------| | Clone | gh repo clone <owner>/<repo> | | Fork | gh repo fork <owner>/<repo> | | View repo | gh repo view | | Create release | gh release create <tag> --title "..." --notes "..." | | List releases | gh release list |

Actions & Workflows

| Action | Command | |--------|---------| | List runs | gh run list | | View run | gh run view <run-id> | | Watch run | gh run watch <run-id> | | Rerun failed | gh run rerun <run-id> --failed | | List workflows | gh workflow list |

API & GraphQL

REST API:

gh api repos/<owner>/<repo>/pulls
gh api repos/<owner>/<repo>/issues/<number>/comments

GraphQL (for data not exposed by gh pr view):

# List PR review threads (gh pr view doesn't expose these)
gh api graphql -F owner=<owner> -F name=<repo> -F number=<pr> -f query='
query($owner:String!, $name:String!, $number:Int!){
  repository(owner:$owner,name:$name){
    pullRequest(number:$number){
      reviewThreads(first:100){
        nodes{id isResolved isOutdated comments(first:50){nodes{id author{login} body}}}
        pageInfo{hasNextPage endCursor}
      }
    }
  }
}'

# Resolve a review thread
gh api graphql -F threadId=<threadId> -f query='
mutation($threadId:ID!){
  resolveReviewThread(input:{threadId:$threadId}){thread{isResolved}}
}'

Pagination: If pageInfo.hasNextPage is true, repeat with after: "<endCursor>".

Procedure

1. Ensure gh auth status shows authenticated
2. Use gh pr list or gh issue list to find items
3. Perform action with appropriate command
4. Verify with gh pr checks or gh run list
5. Always use a heredoc with --body-file or a specific encoding that supports \n correctly

Checks & Guardrails

• Always check PR status before merging
• Use --draft for work-in-progress PRs
• Prefer gh pr merge --squash for clean history
• Check gh run list after pushing to verify CI
• Use GraphQL for review threads (gh pr view doesn't expose them)
• Handle pagination when results exceed 100 items