Issues and pull requests

Active contributors: Mislav, Kynan, Sam Coe, William Martin

Purpose

gh issue and gh pr are the highest-traffic commands in the CLI. They cover creation, listing, viewing, editing, commenting, closing, reopening, locking, transferring, pinning, merging, checking out, and reviewing GitHub issues and pull requests.

Directory layout

pkg/cmd/issue/
  issue.go                 # NewCmdIssue: registers subcommands
  list/  view/  create/  close/  reopen/  comment/  edit/  delete/
  develop/  lock/  pin/  unpin/  transfer/  status/
  shared/                  # cross-subcommand helpers (lookup, render)
  argparsetest/            # test fixtures for arg-parsing edge cases

pkg/cmd/pr/
  pr.go                    # NewCmdPR: registers subcommands
  list/  view/  create/  close/  reopen/  comment/  edit/  diff/
  checkout/  checks/  merge/  ready/  review/  revert/
  status/  update-branch/
  shared/                  # editable templates, finder, reactions, surveys

api/queries_issue.go       # GraphQL queries for issues
api/queries_pr.go          # GraphQL queries for PRs (~25 KB)
api/queries_pr_review.go   # PR review queries (~21 KB)
api/queries_comments.go    # issue/PR comment queries
api/queries_branch_issue_reference.go

pr/ is structurally a superset of issue/ because PRs need branch-aware behaviour, checkouts, merges, and reviews.

Key abstractions

Symbol	File	Role
NewCmdIssue	pkg/cmd/issue/issue.go	Constructs the gh issue Cobra subtree.
NewCmdPR	pkg/cmd/pr/pr.go	Constructs the gh pr Cobra subtree.
NewCmdList (issue)	pkg/cmd/issue/list/list.go	The canonical example of the Options + Factory pattern.
NewCmdCreate (pr)	pkg/cmd/pr/create/create.go	The largest command handler in the repo (~46 KB). Coordinates branch sync, fork detection, draft PRs, fill-from-commits, and review surveys.
findShared	pkg/cmd/pr/shared/finder.go	Resolves a PR or issue from a number, URL, or branch ref.
editable	pkg/cmd/pr/shared/editable.go	Common editing model used by pr edit and issue edit.
Survey templates	pkg/cmd/pr/shared/survey.go	Interactive prompts for create/edit flows.

How it works

A typical request lifecycle for gh issue list:

sequenceDiagram
    participant User
    participant Cobra as Cobra (root)
    participant List as NewCmdList
    participant Run as listRun
    participant API as api.Client.GraphQL
    participant Print as tableprinter

    User->>Cobra: gh issue list -l bug
    Cobra->>List: NewCmdList(f, runF=nil)
    Cobra->>Run: RunE -> listRun(opts)
    Run->>API: GraphQL(IssueList, {...})
    API-->>Run: []api.Issue
    Run->>Print: write rows to opts.IO.Out
    Print-->>User: rendered table or JSON

The --json path uses cmdutil.Exporter.Write instead of the table printer. Whether the output is colourised depends on opts.IO.ColorEnabled(), which itself depends on IsStdoutTTY and the NO_COLOR environment variable.

pr create follows the same shape but with a longer middle: it calls git.Client to determine the local branch, calls the API to learn the parent fork, prompts for a title/body via Prompter, optionally opens the editor for body input, then issues a GraphQL mutation.

Integration points

• Imports the smart repo resolver: registered with &repoResolvingCmdFactory in root.go.
• Reads from git.Client.CurrentBranch and git.Client.UncommittedChangeCount for pr create and pr checkout.
• Uses internal/featuredetection to choose between Issues v1 and Issues v2 GraphQL surfaces, and to detect ProjectsV2 support when populating issue projects.
• Uses internal/tableprinter for list output.
• Uses pkg/markdown (Glamour-based) for body rendering on TTY.
• Surveys go through internal/prompter, with Bubble Tea-based selectors used in some create flows.

Entry points for modification

• New issue or PR field: extend the matching api/queries_*.go file and propagate the field through the relevant view/list rendering plus any --json exporter list.
• New subcommand: add pkg/cmd/issue/<name>/<name>.go (and _test.go), then register it in issue.go's NewCmdIssue.
• New flag on an existing command: edit the NewCmdFoo constructor and threading through the FooOptions struct; cover with a flag-parsing test that uses a stubbed runF.

Key source files

File	Purpose
pkg/cmd/issue/issue.go	Subcommand registration.
pkg/cmd/issue/list/list.go	Canonical list implementation.
pkg/cmd/issue/view/view.go	Issue rendering with comments and reactions.
pkg/cmd/pr/pr.go	Subcommand registration.
pkg/cmd/pr/create/create.go	Largest single command in the codebase.
pkg/cmd/pr/checkout/checkout.go	Cross-fork PR checkout logic.
pkg/cmd/pr/merge/merge.go	Squash, merge-queue, and admin-merge handling.
pkg/cmd/pr/checks/checks.go	Status check polling and rendering.
pkg/cmd/pr/review/review.go	PR review submission flow.
api/queries_pr.go	PR GraphQL queries.
api/queries_pr_review.go	PR review GraphQL queries.

Related pages

• API client for query plumbing.
• Feature detection for capability-aware code paths.
• Patterns and conventions for the shared command shape.