issue-links

Issue links

Pick the strongest accurate relationship — but no stronger.

Decision tree

• Closes / Fixes / Resolves #N in PR body — auto-closes on merge. Default when a PR ends an issue.
• blocked-by / blocks — A can't proceed or ship until B lands. Both are peer-sized; B is not a piece of A. Surfaces in the dependency graph and gates closing.
• parent / sub-issue — A is decomposition of parent B's work. Sub wouldn't exist on its own; parent isn't done until subs are. Subs roll up into parent's progress.
• plain #N mention — context only, no causal edge. Discussion, prior art, "see also". Default when nothing stronger fits.

The trap: reaching for parent/sub-issue when blocked-by is what's meant, because sub-issues were the only hierarchy GitHub had for years. Size test — peer-sized → blocked-by; smaller-than-parent → sub-issue.

How to apply each

Closes / Fixes / Resolves

In the PR body or commit message:

Closes #123

Same-repo number, or owner/repo#123 cross-repo. Recognized verbs: close, fix, resolve (any tense).

blocked-by (GraphQL only — no gh issue flag, no REST)

Two round-trips minimum: GraphQL executes one operation per request and Mutation doesn't expose repository, so query and mutation can't share a document. The lookup is aliased so both IDs return in one call (one rate-limit point), then the mutation runs.

read A_ID B_ID <<<"$(gh api graphql \
  -F owner=OWNER -F repo=REPO -F a=<A> -F b=<B> \
  -f query='
    query($owner: String!, $repo: String!, $a: Int!, $b: Int!) {
      repository(owner: $owner, name: $repo) {
        a: issue(number: $a) { id }
        b: issue(number: $b) { id }
      }
    }' --jq '.data.repository | "\(.a.id) \(.b.id)"')"

gh api graphql -f a="$A_ID" -f b="$B_ID" -f query='
  mutation($a: ID!, $b: ID!) {
    addBlockedBy(input: { issueId: $a, blockingIssueId: $b }) {
      issue { number }
      blockingIssue { number }
    }
  }'

Cross-repo: lift each alias above repository so each issue gets its own repo selection in the same query: