Developing for GitHub

Reference for building on GitHub — Apps, OAuth apps, webhooks, and the Octokit JS/TS SDKs. Official guides in references/ are fetched from the github/docs repo; SDK READMEs in references/octokit/ are snapshots of each octokit/* repo (versions in references/VERSIONS.md); opinionated how-to guides are in references/howto/. Fetched files carry source/fetched_at/sha256 frontmatter.

Scope / where to go instead

• Consuming the API (gh CLI, raw REST/GraphQL, rate limits, PAT setup) → working-with-github
• CI/CD workflows, OIDC → working-with-github-actions
• This skill = building Apps / OAuth apps / webhooks / Octokit integrations.

Quick reference

Task	Read
App vs OAuth app vs PAT — which to build	references/howto/auth-strategies.md, references/app-deciding.md, references/app-vs-oauth.md
Build a GitHub App end-to-end (auth flow)	references/howto/building-a-github-app.md, references/app-auth-*.md
JWT → installation token mechanics	references/app-jwt.md, references/app-installation-token.md
Minimal Octokit TS bot	references/howto/octokit-bot-example.md, references/octokit/octokit-js.md
Build an LLM-powered PR review bot (Vercel AI SDK, Claude/OpenAI swappable)	references/howto/llm-pr-reviewer.md
Handle webhooks + verify signatures	references/howto/webhooks.md, references/webhooks-validating.md, references/webhooks-handling.md
App permissions & rate limits	references/app-permissions.md, references/app-rate-limits.md
Octokit REST / GraphQL / pagination / throttling	references/octokit/octokit-rest.md, octokit-graphql.md, octokit-plugin-paginate-rest.md, octokit-plugin-throttling.md
OAuth app flow & scopes	references/oauth-*.md

How to use this skill

1. Designing an integration — start with references/howto/auth-strategies.md to pick App vs OAuth vs PAT, then references/howto/building-a-github-app.md for the wiring.
2. Implementing auth — the App flow is private key → signed JWT → installation access token. Read references/app-jwt.md then references/app-installation-token.md; @octokit/auth-app (references/octokit/octokit-auth-app.md) does it for you.
3. Webhooks — references/howto/webhooks.md for the verification pattern; always validate the X-Hub-Signature-256 HMAC before trusting a payload.
4. SDK specifics — grep references/octokit/.

Behavioral guidance

• Default to a GitHub App, not a PAT, for anything that outlives a single user or needs scoped, revocable, higher-rate-limit access. PATs are for personal scripts.
• Never skip webhook signature verification. Compute HMAC-SHA256 over the raw body with your secret and constant-time compare against X-Hub-Signature-256.
• Installation tokens expire after 1 hour — mint on demand and cache short-term; @octokit/auth-app handles refresh.
• Octokit is the paved path (Joe's TS-first default). Reach for @octokit/plugin-throttling + @octokit/plugin-retry in production to respect rate limits automatically.

Keeping this current

Regenerated by scripts/update_docs.js: fetches the curated Apps/OAuth/webhook guides from github/docs and the Octokit READMEs, and stamps npm versions. Refresh locally with make update-developing-for-github.