Probot

Probot is a TypeScript framework for building GitHub Apps in Node.js. Instead of wiring up webhook signature verification, event routing, and GitHub App authentication by hand, developers register handlers with a simple app.on("issues.opened", handler) API and Probot takes care of installation-token exchange, request signing, retries, and rate-limit throttling on top of Octokit underneath.

Beyond the event-handling core, Probot ships a CLI (probot run) that scaffolds and runs an app, including an interactive first-run setup flow that walks a new user through registering a GitHub App via the manifest flow and proxies webhooks to localhost with smee.io during development. It also supports GitHub Enterprise Server deployments, pluggable HTTP servers, and an installation-token cache that can be backed by Redis for multi-process deployments — the combination is what has made it the de facto framework behind thousands of GitHub Apps built by the open-source community.

What You Get

• A typed event-emitter API (app.on, app.onAny, app.onError) for subscribing to any GitHub webhook event, with events queued automatically until the underlying Octokit client finishes async initialization.
• An authenticated Octokit client per-installation, built on @octokit/core with pagination, REST endpoint methods, retry, and throttling plugins pre-wired and an LRU (or optional Redis) token cache.
• A CLI (probot run <app>) plus an interactive setup wizard that registers a new GitHub App via the manifest flow and tunnels webhooks to your local machine with smee.io.
• A swappable HTTP server layer (src/server) for exposing a webhook receiver and custom routes, with a Node middleware export (getNodeMiddleware) for embedding Probot inside an existing Express/Fastify app.
• Structured logging via @probot/pino, configurable as pretty or JSON output, plus optional Sentry error reporting.

Common Use Cases

• Auto-labeling, triaging, or commenting on new issues and pull requests based on their content.
• Enforcing merge/CI policy bots (required checks, stale-PR closers, changelog reminders).
• Syncing repository settings, labels, or branch-protection rules across an organization from a config file.
• Building internal developer-productivity bots that react to GitHub Actions, releases, or deployment events.
• Prototyping and shipping public GitHub Marketplace apps without hand-rolling webhook verification and App auth.

Under The Hood

Architecture Probot’s core Probot class (src/probot.ts) manages a private deferred-initialization state machine (UNINITIALIZED/INITIALIZING/INITIALIZED) so that event listeners registered via on/onAny/onError before the async Octokit and webhooks setup finishes are queued and flushed once initialization completes. createProbot (src/create-probot.ts) merges configuration from environment variables, caller-supplied defaults, and overrides — resolving the GitHub App private key via @probot/get-private-key — into a ready Probot instance. The CLI entry point, run() (src/run.ts, invoked through bin/probot.js), wraps a Server (src/server/server.ts) around Probot.defaults(), dispatching to a first-run setup app (src/apps/setup.ts) when App ID or private key are missing, and otherwise resolving and loading the caller’s app function(s). Webhook delivery, HTTP serving, CLI bootstrapping, and the Octokit client each live in clearly separated modules beneath a slim public API surface.

Tech Stack Written in TypeScript and shipped as native ES modules, targeting Node 20.18.1+ or 22+. GitHub API access and webhook parsing/verification run on the Octokit family (@octokit/core, plugin-paginate-rest, plugin-rest-endpoint-methods, plugin-retry, plugin-throttling, @octokit/webhooks), with @probot/pino for structured logging, toad-cache for in-memory installation-token caching (with optional ioredis backing), and bottleneck for request throttling. package-config and npx-import-light resolve user configuration and dynamically load installed Probot apps. The project builds with tsc, tests with Vitest (plus tsd for type-level tests and @vitest/coverage-v8), generates docs with TypeDoc, and releases via semantic-release including a JSR publish step.

Code Quality The test/ directory mirrors src/ module-for-module (probot.test.ts, run.test.ts, server.test.ts, webhook-proxy.test.ts, manifest-creation.test.ts) and is further layered with dedicated e2e/, integration/, and fixtures/ subdirectories, going well beyond flat unit coverage. Prettier enforces formatting across source, tests, and docs (checked in CI), and TypeScript’s compiler plus tsd provide type-level guarantees in place of a separate lint config. Error handling is explicit: the Probot constructor throws descriptive errors for missing appId/privateKey, and run() throws production-specific guidance pointing at the exact environment variable an operator needs to set. CI runs dependency-review and license-check jobs alongside the test suite.

What Makes It Unique Rather than reinventing GitHub API access, Probot’s differentiation is in the GitHub App onboarding experience it wraps around Octokit primitives: an interactive CLI setup flow registers a new GitHub App through GitHub’s manifest API on first run, and a bundled smee.io proxy lets webhooks reach localhost during development without exposing a public URL. Transparent GitHub Enterprise Server support (via a single GHE_HOST environment variable) and a swappable HTTP server layer that can be embedded inside an existing Express or Fastify app round out a framework aimed at removing nearly all of the boilerplate between “I have an idea for a GitHub bot” and a running app.