developing-for-github

Files (48)

• SKILL.md
• VERSIONS.md · references/
• app-about-creating.md · references/
• app-auth-about.md · references/
• app-auth-as-app.md · references/
• app-auth-installation.md · references/
• app-best-practices.md · references/
• app-ci-checks.md · references/
• app-deciding.md · references/
• app-installation-token.md · references/
• app-jwt.md · references/
• app-login-button.md · references/
• app-on-behalf-of-user.md · references/
• app-permissions.md · references/
• app-private-keys.md · references/
• app-rate-limits.md · references/
• app-refreshing-user-tokens.md · references/
• app-registering.md · references/
• app-respond-to-webhooks.md · references/
• app-user-token.md · references/
• app-using-webhooks.md · references/
• app-vs-oauth.md · references/
• app-writing-code.md · references/
• auth-strategies.md · references/howto/
• building-a-github-app.md · references/howto/
• llm-pr-reviewer.md · references/howto/
• octokit-bot-example.md · references/howto/
• webhooks.md · references/howto/
• oauth-authorizing.md · references/
• oauth-best-practices.md · references/
• oauth-creating.md · references/
• oauth-scopes.md · references/
• octokit-auth-app.md · references/octokit/
• octokit-core.md · references/octokit/
• octokit-graphql.md · references/octokit/
• octokit-js.md · references/octokit/
• octokit-plugin-paginate-rest.md · references/octokit/
• octokit-plugin-retry.md · references/octokit/
• octokit-plugin-throttling.md · references/octokit/
• octokit-rest.md · references/octokit/
• octokit-webhooks.md · references/octokit/
• webhooks-about.md · references/
• webhooks-creating.md · references/
• webhooks-events-and-payloads.md · references/
• webhooks-failed-deliveries.md · references/
• webhooks-handling.md · references/
• webhooks-validating.md · references/
• update_docs.js · scripts/

SKILL.md (first lines)

# 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`.

From joeblackwaslike/agent-skills, MIT.

More from joeblackwaslike/agent-skills