tessl/npm-probot

A framework for building GitHub Apps to automate and improve your workflow

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Probot

Name: tessl/npm-probot
Author: tessl

Probot is a comprehensive Node.js framework for building GitHub Apps that automate and improve your workflow. Built in TypeScript, it provides a high-level API for handling GitHub webhook events, managing GitHub App authentication, and interacting with the GitHub API through a unified context system.

Package Information

Package Name: probot
Package Type: npm
Language: TypeScript
Installation: npm install probot

Core Imports

import { Probot, Context, run, createProbot } from "probot";

For CommonJS:

const { Probot, Context, run, createProbot } = require("probot");

Basic Usage

import { Probot } from "probot";

export default (app: Probot) => {
  // Handle issues being opened
  app.on("issues.opened", async (context) => {
    const issueComment = context.issue({
      body: "Thanks for opening this issue!",
    });
    return context.octokit.issues.createComment(issueComment);
  });

  // Handle all events
  app.onAny(async (context) => {
    context.log.info({ event: context.name, action: context.payload.action });
  });

  // Handle errors
  app.onError(async (error) => {
    app.log.error(error);
  });
};

Architecture

Probot is built around several key components:

Event-Driven Architecture: Uses GitHub webhooks to trigger application logic based on repository events
Context System: Provides rich context objects containing event payloads, authenticated Octokit instances, and helper methods
Authentication Management: Handles GitHub App authentication, installation tokens, and JWT generation automatically
HTTP Server: Built-in server for receiving webhooks, serving web interfaces, and handling OAuth flows
Middleware System: Extensible request/response handling with built-in logging, error handling, and static file serving
Configuration Management: Environment-based configuration with support for development and production deployments

Capabilities

Core Framework

The main Probot class and application lifecycle management for building GitHub Apps with event handling, authentication, and server setup.

class Probot {
  constructor(options: Options);
  static defaults(defaults: Options): typeof Probot;
  static get version(): string;
  
  get log(): Logger;
  get version(): string;
  get webhooks(): ProbotWebhooks;
  get webhookPath(): string;
  
  async auth(installationId?: number): Promise<ProbotOctokit>;
  async getNodeMiddleware(options?: { log?: Logger; path?: string }): Promise<ReturnType<typeof createNodeMiddleware>>;
  async load(appFn: ApplicationFunction | ApplicationFunction[], options?: ApplicationFunctionOptions): Promise<void>;
  async ready(): Promise<this>;
  async receive(event: WebhookEvent): Promise<void>;
  
  on: ProbotWebhooks["on"];
  onAny: ProbotWebhooks["onAny"];
  onError: ProbotWebhooks["onError"];
}

Core Framework

Context and Event Handling

Rich context objects for webhook events with GitHub API integration and repository-specific helper methods.

class Context<Event extends WebhookEvents = WebhookEvents> {
  public name: WebhookEvents;
  public id: string;
  public payload: WebhookPayload;
  public octokit: ProbotOctokit;
  public log: Logger;
  
  get isBot(): boolean;
  
  repo<T>(object?: T): RepoResultType<Event> & T;
  issue<T>(object?: T): RepoResultType<Event> & { issue_number: number } & T;
  pullRequest<T>(object?: T): RepoResultType<Event> & { pull_number: number } & T;
  async config<T>(fileName: string, defaultConfig?: T, deepMergeOptions?: MergeOptions): Promise<T | null>;
}

Context and Event Handling

HTTP Server and Middleware

Built-in HTTP server for webhooks, web interfaces, and custom request handling with middleware support.

class Server {
  constructor(options: ServerOptions);
  
  get port(): number;
  get host(): string;
  static get version(): string;
  get version(): string;
  
  addHandler(handler: Handler): void;
  async loadHandlerFactory(appFn: HandlerFactory): Promise<void>;
  async load(appFn: ApplicationFunction): Promise<void>;
  async start(): Promise<HttpServer>;
  async stop(): Promise<void>;
}

HTTP Server and Middleware

GitHub API Integration

Enhanced Octokit client with Probot-specific plugins, authentication, and configuration for seamless GitHub API access.

class ProbotOctokit extends Octokit {
  // Includes all standard Octokit functionality plus:
  // - Automatic authentication with GitHub Apps
  // - Request throttling and retries
  // - Pagination support
  // - Enterprise compatibility
  // - Request logging
  // - Configuration file reading
}

GitHub API Integration

Application Creation and Deployment

Factory functions and utilities for creating, configuring, and running Probot applications in various environments.

function createProbot(options?: CreateProbotOptions): Probot;
function createNodeMiddleware(appFn: ApplicationFunction, options?: MiddlewareOptions): Promise<NodeMiddleware>;
function run(appFnOrArgv: ApplicationFunction | string[], additionalOptions?: Partial<Options>): Promise<Server>;

Application Creation and Deployment

Core Types

interface Options {
  privateKey?: string;
  githubToken?: string;
  appId?: number | string;
  Octokit?: typeof ProbotOctokit;
  log?: Logger;
  redisConfig?: RedisOptions | string;
  secret?: string;
  logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
  logFormat?: "json" | "pretty";
  logLevelInString?: boolean;
  logMessageKey?: string;
  sentryDsn?: string;
  port?: number;
  host?: string;
  server?: Server;
  baseUrl?: string;
  request?: RequestRequestOptions;
  webhookPath?: string;
  webhookProxy?: string;
}

type ApplicationFunction = (
  app: Probot,
  options: ApplicationFunctionOptions
) => void | Promise<void>;

type ApplicationFunctionOptions = {
  cwd: string;
  addHandler: (handler: Handler) => void;
  [key: string]: unknown;
};

type Handler = (
  req: IncomingMessage,
  res: ServerResponse  
) => void | boolean | Promise<void | boolean>;

type ProbotWebhooks = Webhooks<Omit<Context, keyof WebhookEvent>>;

type StripUndefined<T> = {
  [K in keyof T]-?: Exclude<T[K], undefined>;
};

type OctokitOptions = NonNullable<
  ConstructorParameters<typeof ProbotOctokit>[0]
>;

type PackageJson = {
  name?: string;
  version?: string;
  description?: string;
  homepage?: string;
  repository?: string;
  engines?: { [key: string]: string };
};

type Env = NodeJS.ProcessEnv;

Install with Tessl CLI