developing-for-github

---
name: developing-for-github
description: "Use when building software that integrates with GitHub — GitHub Apps, OAuth apps, webhook consumers, bots, CI checks, and automation built on the GitHub API. Covers the GitHub App auth model (private key → JWT → installation access token), choosing GitHub App vs OAuth app vs PAT, app permissions and rate limits, webhook delivery and HMAC signature verification, and the Octokit JS/TS SDK family (octokit, @octokit/rest, @octokit/graphql, @octokit/webhooks, @octokit/auth-app, paginate/throttling/retry plugins). Invoke when designing or coding a GitHub integration, debugging app authentication or webhook signatures, or picking an auth strategy. For raw REST/GraphQL usage and tokens from the consumer side, use working-with-github; for CI workflows, use working-with-github-actions."
metadata:
  last_updated: "2026-06-15"
---

# Developing for GitHub

Reference for **building on** GitHub — Apps, OAuth apps, webhooks, and the Octokit JS/TS SDKs. Official guides in [`references/`](references/) are fetched from the `github/docs` repo; SDK READMEs in [`references/octokit/`](references/octokit/) are snapshots of each `octokit/*` repo (versions in [`references/VERSIONS.md`](references/VERSIONS.md)); opinionated how-to guides are in [`references/howto/`](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`](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`.

• SKILL.md 4 KB
• references/VERSIONS.md 1 KB
• references/app-about-creating.md 9 KB
• references/app-auth-about.md 3 KB
• references/app-auth-as-app.md 4 KB
• references/app-auth-installation.md 10 KB
• references/app-best-practices.md 14 KB
• references/app-ci-checks.md 93 KB
• references/app-deciding.md 11 KB
• references/app-installation-token.md 1 KB
• references/app-jwt.md 8 KB
• references/app-login-button.md 22 KB
• references/app-on-behalf-of-user.md 3 KB
• references/app-permissions.md 9 KB
• references/app-private-keys.md 6 KB
• references/app-rate-limits.md 2 KB
• references/app-refreshing-user-tokens.md 5 KB
• references/app-registering.md 10 KB
• references/app-respond-to-webhooks.md 23 KB
• references/app-user-token.md 20 KB
• references/app-using-webhooks.md 7 KB
• references/app-vs-oauth.md 15 KB
• references/app-writing-code.md 6 KB
• references/oauth-authorizing.md 27 KB
• references/oauth-best-practices.md 9 KB
• references/oauth-creating.md 3 KB
• references/oauth-scopes.md 11 KB
• references/webhooks-about.md 5 KB
• references/webhooks-creating.md 11 KB
• references/webhooks-events-and-payloads.md 5 KB
• references/webhooks-failed-deliveries.md 3 KB
• references/webhooks-handling.md 19 KB
• references/webhooks-validating.md 8 KB
• references/howto/auth-strategies.md 7 KB
• references/howto/building-a-github-app.md 8 KB
• references/howto/llm-pr-reviewer.md 25 KB
• references/howto/octokit-bot-example.md 6 KB
• references/howto/webhooks.md 7 KB
• references/octokit/octokit-auth-app.md 36 KB
• references/octokit/octokit-core.md 13 KB
• references/octokit/octokit-graphql.md 9 KB
• references/octokit/octokit-js.md 35 KB
• references/octokit/octokit-plugin-paginate-rest.md 9 KB
• references/octokit/octokit-plugin-retry.md 3 KB
• references/octokit/octokit-plugin-throttling.md 7 KB
• references/octokit/octokit-rest.md 3 KB
• references/octokit/octokit-webhooks.md 58 KB
• scripts/update_docs.js 11 KB