Probot: GitHub App Framework

Common errors

• 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.

  cause 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.

  cause 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.

  cause 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.

  cause 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.

Warnings

• breaking Probot 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.
• breaking Probot 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).
• breaking Major 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.
• gotcha Starting 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.
• security Regular 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.

Install

• npm install probot npm
• yarn add probot yarn
• pnpm add probot pnpm

Imports

• Probot
  wrong:

  const Probot = require('probot');

  correct:

  import { Probot } from '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
  wrong:

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

  correct:

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

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

Quickstart

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);
};