# GitHub — connector pack

Access options in preference order. Probe each in order; use the first that answers. Research of record: `discussions/code-analysis-tools/research-tracker-connectors/01-github.md` (2026-08-19).

## Option 1 — the `gh` CLI (default)

Probe: `gh auth status` (exit 0 = authenticated; `gh --version` alone only proves the binary).
Setup if absent: `gh auth login` (browser flow) or `gh auth login --with-token` with a PAT (scopes: repo, read:org). CI: `GH_TOKEN` env.

- Read: `gh issue view <n|url> --comments --json title,body,labels,comments,state,url,author,assignees,milestone`
- Sweep: `gh issue list --search '<query>' --state all --json number,title,labels`
- Dedup: `gh search issues '<key phrases>' --repo OWNER/REPO`
- Create (approval-gated): `gh issue create --title <t> --body-file <f> --label <l>`
- Comment (approval-gated): `gh issue comment <n> --body-file <f>`
- Another repo: add `-R OWNER/REPO` to any of these.

## Option 2 — the official GitHub MCP server

`github/github-mcp-server` (GitHub-official, 32k★). Probe: a `github` entry in `.mcp.json` / MCP tools visible in-session.
Setup: `claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer <PAT>"` (hosted), or local Docker `ghcr.io/github/github-mcp-server` with OAuth.
Tool names (issues toolset, loaded by default): `issue_read` (get/get_comments/get_sub_issues/get_labels) · `list_issues` · `search_issues` · `issue_write` (create/update — the write gate applies) · `add_issue_comment` · labels via the `labels` toolset (`GITHUB_TOOLSETS` env to add).

## Option 3 — raw API fallback

Headers: `Authorization: Bearer <PAT>` · `Accept: application/vnd.github+json`.
- Read: `GET https://api.github.com/repos/OWNER/REPO/issues/N`
- Search: `GET https://api.github.com/search/issues?q=<query>` (q ≤256 chars, ≤5 boolean ops, ~10 req/min)
- Create: `POST /repos/OWNER/REPO/issues` `{"title","body","labels":[]}` · Comment: `POST .../issues/N/comments` `{"body"}`
- Labels: POST appends, PUT replaces — never PUT unless replacement is the stated intent.

## Composing for GitHub

Markdown body, native. Reference related issues/PRs by bare `#number` so GitHub auto-links. Labels from the owning doc's `module:` where the repo's label taxonomy allows — **read `gh label list` first; never invent labels** (real taxonomies differ: apache/superset uses `#bug:*`, not `bug`).

## Ecosystem notes (2026-08-19)

No incumbent GitHub-issues skill/plugin exists in anthropics/skills, the official plugin marketplace, or awesome-claude-code — this pack has no upstream to defer to. The reverse direction exists as `anthropics/claude-code-action` (@claude mentions inside issues trigger CI sessions); do not confuse the two.