probot

library14.3.2jsnpmunverified

Probot is a robust Node.js framework, currently at version 14.3.2, designed for building GitHub Apps to automate and enhance development workflows. It provides a streamlined, event-driven architecture that significantly simplifies interaction with the GitHub API and handling webhook events. Written in TypeScript, Probot ships with comprehensive type definitions, offering full support for TypeScript projects. The project maintains an active development and release cadence, with minor and patch versions frequently released (typically every few weeks) to deliver bug fixes, critical security updates (such as recent `yaml` dependency patches), and new features. Its primary differentiator is abstracting the complexities of GitHub App development, allowing developers to concentrate on core application logic rather than boilerplate API calls, authentication, or webhook infrastructure.

devops web-framework http-networking

npm install probot

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROBOT

probot

devopsjavascriptv14.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Probot

✓ import { Probot } from 'probot';

✗ const Probot = require('probot');

Probot v12+ is ESM-only. Use `import` statements; CommonJS `require` will result in an `ERR_REQUIRE_ESM` error.

ApplicationFunction

✓ import { ApplicationFunction } from 'probot';

This type is essential for defining the entry point of your Probot app when using TypeScript.

Context

✓ import { Context } from 'probot';

The `Context` type represents the webhook event payload and provides helpers for API interactions and logging within an event handler.

App Function Default Export

✓ export default (app: Probot) => { /* ... */ };

✗ module.exports = (app) => { /* ... */ };

The recommended way to define your Probot app's entry point is using an ESM default export for the application function.

This quickstart demonstrates a basic Probot app written in TypeScript, responding to new issue and pull request events by adding comments. It also includes error handling and shows how to log messages and use environment variables.

import { Probot } from 'probot'; export default (app: Probot) => { app.on('issues.opened', async (context) => { const issueComment = context.issue({ body: 'Thanks for opening this issue! We\'ll take a look soon.', }); return context.octokit.issues.createComment(issueComment); }); app.on('pull_request.opened', async (context) => { context.log.info(`New pull request opened: ${context.payload.pull_request.html_url}`); const prComment = context.issue({ body: 'Welcome to the party, pull request! Feel free to ask questions if you get stuck.', }); return context.octokit.issues.createComment(prComment); }); app.onError(async (error) => { app.log.error(`An error occurred: ${error.message}`); // Optionally, send error details to a monitoring service // console.error(error); }); // Example of using an environment variable for configuration (optional) const GREETING_MESSAGE = process.env.PROBOT_GREETING_MESSAGE ?? 'Hello from Probot!'; app.log.info(GREETING_MESSAGE); };

probot --version

Debug

Known issues

breakingProbot v12 and newer are pure ESM packages. Using `require()` for importing Probot will result in `ERR_REQUIRE_ESM` errors.

fix

Migrate your app to use ES Modules (`import`/`export`) or stick to Probot v11 for CommonJS compatibility. Ensure your `package.json` specifies `"type": "module"` if using ESM.

affects: >=12.0.0

breakingProbot requires Node.js version `^20.18.1 || >= 22`. Running with older Node.js versions will lead to startup failures or unexpected behavior.

fix

Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.18.1 or Node.js 22).

affects: >=14.0.0

breakingMajor version updates to the underlying `@octokit` monorepo (as seen in `v14.2.2`) can sometimes introduce breaking changes if your app directly interacts with `context.octokit` using patterns that have been deprecated or removed in newer Octokit versions.

fix

Consult the `@octokit/core` release notes for breaking changes and adapt your Octokit API calls accordingly. Always test your app after major `@octokit` dependency updates.

affects: >=14.2.2

gotchaStarting from `v14.3.0`, Probot replaces `dotenv` with Node.js native `parseEnv` for environment variable parsing. While this generally provides a more native experience, ensure your Node.js version supports `parseEnv` fully and any custom `dotenv` configurations are migrated.

fix

Review your environment variable loading strategy. If you rely on specific `dotenv` features (e.g., `.env.local` files, variable expansion), you might need to handle them manually or use a compatible alternative alongside Probot's native parsing.

affects: >=14.3.0

securityRegular security updates for dependencies, such as the `yaml` dependency update in `v14.3.2`, are released to patch vulnerabilities. Failing to update can expose your Probot app to known security risks.

fix

Regularly update your Probot package to the latest patch release (`npm update probot`) to ensure all known security vulnerabilities in its dependencies are addressed.

affects: All versions

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module [path/to/probot] not supported. probot is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which declares it to be an ES module.

Attempting to import Probot or its components using CommonJS `require()` syntax in a Node.js environment where Probot is treated as an ESM module.

fix

Update your import statements to use ES Modules syntax: `import { Probot } from 'probot';`. Ensure your project's `package.json` has `"type": "module"` if you are using `.js` files as ESM, or rename your app files to `.mjs`.

Error: GitHub App private key is missing or invalid.

The `PRIVATE_KEY` environment variable is not set, or the provided key is malformed or expired. Probot needs a valid private key to authenticate with GitHub as an app.

fix

Ensure `PRIVATE_KEY` is set in your environment variables. It should contain the entire content of the `.pem` file downloaded from your GitHub App settings, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----` headers/footers. Also, check that `APP_ID` is correctly set.

Error: Node.js version x.y.z is not supported.

Your current Node.js version does not meet Probot's `engines.node` requirement.

fix

Upgrade your Node.js environment to version `^20.18.1` or `>= 22` to match the requirements. Use a tool like `nvm` to manage Node.js versions efficiently.

Error: Webhook callback URL is not configured or reachable.

When running Probot locally without a tool like `smee.io`, or when deploying, the GitHub App's webhook URL is incorrectly configured or not publicly accessible.

fix

For local development, use `smee.io` (or similar) and set `WEBHOOK_PROXY_URL` to your Smee URL. For deployment, ensure your server is publicly accessible and the webhook URL in your GitHub App settings points to your deployed Probot app's `/api/github/webhooks` endpoint.

Upgrade

Version history

14.3.2latest on npm

Audit

Dependencies

@octokit/corerequiredCore dependency for interacting with the GitHub API. Probot provides an authenticated Octokit client via `context.octokit`.

smee-clientoptionalCommonly used for local development to forward GitHub webhook payloads from a public URL to your local Probot app.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/probot/probot ↗

packagehttps://www.npmjs.com/package/probot ↗

homepagehttps://probot.github.io ↗