use-github

name	use-github
description	Reference for gh CLI commands—auth, repo context, GraphQL conventions. Workflow skills delegate here for shared mechanics.

Use GitHub

Reference for shared gh CLI mechanics—auth, repo context, and GraphQL conventions. Workflow skills own their specific commands and delegate here for these common patterns.

Auth

gh needs required_permissions: ["full_network"].

gh auth status

If failed: Tell user gh auth login.

Repo Context

gh repo view --json owner,name

Extract owner.login and name — needed for REST and GraphQL API calls.

GraphQL API

Invocation Pattern

gh api graphql \
  -f query="$(cat path/to/query.graphql)" \
  -F owner=<owner> \
  -F name=<repo> \
  -F number=<number>

Pass each variable as its own -F flag (not a variables object). Use -f (lowercase) for string values and -F (uppercase) for typed values (integers, booleans).

Conventions for Query Templates

Each skill owns its own .graphql query files. Follow these conventions:

• Always include pageInfo { hasNextPage endCursor } on paginated connections. If hasNextPage is true, tell the user that more results exist and offer three options: fetch the next page, fetch all remaining pages, or continue with the current page only.
• Include databaseId on any node you will reference via the REST API (REST endpoints use integer IDs, not GraphQL node IDs).
• Include createdAt on comments when ordering matters.

Pagination

When pageInfo.hasNextPage is true, fetch the next page by passing the endCursor value as the after argument on the connection:

gh api graphql \
  -f query="$(cat path/to/query.graphql)" \
  -F owner=<owner> \
  -F name=<repo> \
  -F number=<number> \
  -f after=<end_cursor>

Query templates that support pagination should accept an optional $after: String variable and pass it to the connection (e.g. reviewThreads(first: 50, after: $after)). The $after is nullable so the first call works without it.

Merge results across pages before processing.

Error Handling

• Auth failure (401): Tell user gh auth login.
• Rate limit (403 with rate limit headers): Report remaining reset time and suggest waiting.
• Not found (404 / null data): Report and abort the operation.