Probot — Framework for Building GitHub Apps in Node.js

Introduction

Probot is a Node.js framework for building GitHub Apps that automate repository workflows. Instead of writing raw webhook handlers, you get a structured event system, authenticated API clients, and built-in tooling for testing and deployment.

What Probot Does

• Listens for GitHub webhook events (push, PR, issue, comment, check run, etc.)
• Provides an authenticated Octokit client scoped to each installation
• Handles app registration, permissions, and webhook verification automatically
• Supports local development with a webhook proxy via smee.io
• Powers well-known bots like Stale, Settings, and No Response

Architecture Overview

Probot wraps a Node.js HTTP server that receives GitHub webhook payloads. Each event is dispatched to handler functions you register. The framework manages JWT signing for app authentication and creates installation-scoped tokens on every request. Under the hood it uses Octokit for API calls and can run as a standalone server or as a serverless function.

Self-Hosting & Configuration

• Scaffold a new app with npx create-probot-app and follow the GitHub App setup wizard
• Store your App ID, private key, and webhook secret in environment variables
• Run locally with npm start and use smee.io to forward webhooks to localhost
• Deploy to any Node.js host: Vercel, AWS Lambda, Heroku, or a plain VM
• Configure permissions and subscribed events in the GitHub App settings page

Key Features

• Event-driven handler model with TypeScript support
• Automatic token refresh and installation-scoped API access
• Built-in logging with Pino and structured JSON output
• First-class testing support with fixtures and simulated webhook payloads
• Extensible via plugins for common patterns (auto-merge, labeling, stale management)

Comparison with Similar Tools

• GitHub Actions — runs inside GitHub's CI infra; Probot runs as a persistent app with richer webhook handling
• Octokit — low-level SDK; Probot adds the app framework, auth, and event routing on top
• Webhooks.js — handles webhook verification only; Probot provides the full app lifecycle
• Danger — focused on PR review automation; Probot covers all GitHub events

FAQ

Q: Is Probot the same as a GitHub Action? A: No. Probot runs as a GitHub App (a persistent service), while Actions run per-workflow inside GitHub.

Q: Can I deploy a Probot app as a serverless function? A: Yes. Probot supports AWS Lambda, Azure Functions, and Vercel serverless deployments.

Q: Does it support GitHub Enterprise Server? A: Yes. Point the base URL to your GHES instance in the app configuration.

Q: What license does Probot use? A: ISC license, fully open source at github.com/probot/probot.

Sources

• https://github.com/probot/probot
• https://probot.github.io/