probot

  • Version 13.4.5
  • Published
  • 747 kB
  • 26 dependencies
  • ISC license

Install

npm i probot
yarn add probot
pnpm add probot

Overview

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

Index

Variables

variable ProbotOctokit

const ProbotOctokit: any;

    Functions

    function createNodeMiddleware

    createNodeMiddleware: (
    appFn: ApplicationFunction,
    { probot, webhooksPath }?: MiddlewareOptions
    ) => (
    request: IncomingMessage,
    response: ServerResponse,
    next?: () => void
    ) => Promise<boolean>;
    • Create a Node/Express middleware.

      import { createServer } from "node:http"
      import { createProbot, createNodeMiddleware } from "probot"
      const appFn = (app) => {
      app.on("issues.opened", async (context) => {
      const issueComment = context.issue({
      body: "Thanks for opening this issue!",
      });
      return context.octokit.issues.createComment(issueComment);
      });
      };
      const middleware = createNodeMiddleware(appFn, { probot: createProbot() });
      const server = createServer((req, res) => {
      middleware(req, res, () => {
      res.writeHead(404);
      res.end();
      });
      });

    function createProbot

    createProbot: ({ overrides, defaults, env }?: CreateProbotOptions) => Probot;
    • Merges configuration from defaults/environment variables/overrides and returns a Probot instance. Finds private key using [@probot/get-private-key](https://github.com/probot/get-private-key).

      Parameter defaults

      default Options, will be overwritten if according environment variable is set

      Parameter overrides

      overwrites defaults and according environment variables

      Parameter env

      defaults to process.env

      See Also

      • https://probot.github.io/docs/configuration/

    function run

    run: (
    appFnOrArgv: ApplicationFunction | string[],
    additionalOptions?: AdditionalOptions
    ) => Promise<Server>;
    • Parameter appFnOrArgv

      set to either a probot application function: (app) => { ... } or to process.argv

    Classes

    class Context

    class Context<Event extends WebhookEvents = WebhookEvents> {}
    • The context of the event that was triggered, including the payload and helpers for extracting information can be passed to GitHub API calls.

      ```js export default app => { app.on('push', context => { context.log.info('Code was pushed to the repo, what should we do with it?'); }); }; ```

      {octokit} octokit - An Octokit instance {payload} payload - The webhook event payload {log} log - A pino instance

    constructor

    constructor(event: WebhookEvent<Event>, octokit: any, log: Logger);

      property id

      id: string;

        property isBot

        readonly isBot: boolean;
        • Returns a boolean if the actor on the event was a bot. {boolean}

        property log

        log: Logger;

          property name

          name: WebhookEvents;

            property octokit

            octokit: any;

              property payload

              payload: WebhookEvent<K>;

                method config

                config: <T>(
                fileName: string,
                defaultConfig?: T,
                deepMergeOptions?: merge.Options
                ) => Promise<T | null>;
                • Reads the app configuration from the given YAML file in the .github directory of the repository.

                  For example, given a file named .github/config.yml:

                  close: true
                  comment: Check the specs on the rotary girder.

                  Your app can read that file from the target repository:

                  // Load config from .github/config.yml in the repository
                  const config = await context.config('config.yml')
                  if (config.close) {
                  context.octokit.issues.comment(context.issue({body: config.comment}))
                  context.octokit.issues.edit(context.issue({state: 'closed'}))
                  }

                  You can also use a defaultConfig object:

                  // Load config from .github/config.yml in the repository and combine with default config
                  const config = await context.config('config.yml', {comment: 'Make sure to check all the specs.'})
                  if (config.close) {
                  context.octokit.issues.comment(context.issue({body: config.comment}));
                  context.octokit.issues.edit(context.issue({state: 'closed'}))
                  }

                  Config files can also specify a base that they extend. deepMergeOptions can be used to configure how the target config, extended base, and default configs are merged.

                  For security reasons, configuration is only loaded from the repository's default branch, changes made in pull requests from different branches or forks are ignored.

                  If you need more lower-level control over reading and merging configuration files, you can context.octokit.config.get(options), see https://github.com/probot/octokit-plugin-config.

                  Parameter fileName

                  Name of the YAML file in the .github directory

                  Parameter defaultConfig

                  An object of default config options

                  Parameter deepMergeOptions

                  Controls merging configs (from the [deepmerge](https://github.com/TehShrike/deepmerge) module) Configuration object read from the file

                method issue

                issue: <T>(
                object?: T
                ) => RepoResultType<Event> & { issue_number: RepoIssueNumberType<Event> } & T;
                • Return the owner, repo, and issue_number params for making API requests against an issue. The object passed in will be merged with the repo params.

                  const params = context.issue({body: 'Hello World!'})
                  // Returns: {owner: 'username', repo: 'reponame', issue_number: 123, body: 'Hello World!'}

                  Parameter object

                  Params to be merged with the issue params.

                method pullRequest

                pullRequest: <T>(
                object?: T
                ) => RepoResultType<Event> & { pull_number: RepoIssueNumberType<Event> } & T;
                • Return the owner, repo, and pull_number params for making API requests against a pull request. The object passed in will be merged with the repo params.

                  const params = context.pullRequest({body: 'Hello World!'})
                  // Returns: {owner: 'username', repo: 'reponame', pull_number: 123, body: 'Hello World!'}

                  Parameter object

                  Params to be merged with the pull request params.

                method repo

                repo: <T>(object?: T) => RepoResultType<Event> & T;
                • Return the owner and repo params for making API requests against a repository.

                  const params = context.repo({path: '.github/config.yml'})
                  // Returns: {owner: 'username', repo: 'reponame', path: '.github/config.yml'}

                  Parameter object

                  Params to be merged with the repo params.

                class Probot

                class Probot {}

                  constructor

                  constructor(options?: Options);

                    property auth

                    auth: (installationId?: number, log?: Logger) => Promise<ProbotOctokit>;

                      property log

                      log: Logger;

                        property on

                        on: Webhooks<SimplifiedObject>;

                          property onAny

                          onAny: Webhooks<SimplifiedObject>;

                            property onError

                            onError: Webhooks<SimplifiedObject>;

                              property version

                              static version: string;

                                property version

                                version: string;

                                  property webhookPath

                                  webhookPath: string;

                                    property webhooks

                                    webhooks: Webhooks<SimplifiedObject>;

                                      method defaults

                                      static defaults: <S extends Constructor<any>>(
                                      this: S,
                                      defaults: Options
                                      ) => (new (...args: any[]) => { [x: string]: any }) & S;

                                        method load

                                        load: (
                                        appFn: ApplicationFunction | ApplicationFunction[],
                                        options?: ApplicationFunctionOptions
                                        ) => Promise<void>;

                                          method receive

                                          receive: (event: WebhookEvent) => Promise<void>;

                                            class Server

                                            class Server {}

                                              constructor

                                              constructor(options?: ServerOptions);

                                                property expressApp

                                                expressApp: Application;

                                                  property log

                                                  log: Logger;

                                                    property probotApp

                                                    probotApp: Probot;

                                                      property version

                                                      static version: string;

                                                        property version

                                                        version: string;

                                                          method load

                                                          load: (appFn: ApplicationFunction) => Promise<void>;

                                                            method router

                                                            router: (path?: string) => any;

                                                              method start

                                                              start: () => Promise<
                                                              HttpServer<
                                                              typeof import('http').IncomingMessage,
                                                              typeof import('http').ServerResponse
                                                              >
                                                              >;

                                                                method stop

                                                                stop: () => Promise<unknown>;

                                                                  Interfaces

                                                                  interface Options

                                                                  interface Options {}

                                                                    property appId

                                                                    appId?: number | string;

                                                                      property baseUrl

                                                                      baseUrl?: string;

                                                                        property githubToken

                                                                        githubToken?: string;

                                                                          property host

                                                                          host?: string;

                                                                            property log

                                                                            log?: Logger;

                                                                              property logLevel

                                                                              logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';

                                                                                property logMessageKey

                                                                                logMessageKey?: string;

                                                                                  property Octokit

                                                                                  Octokit?: typeof ProbotOctokit;

                                                                                    property port

                                                                                    port?: number;

                                                                                      property privateKey

                                                                                      privateKey?: string;

                                                                                        property redisConfig

                                                                                        redisConfig?: RedisOptions | string;

                                                                                          property request

                                                                                          request?: RequestRequestOptions;

                                                                                            property secret

                                                                                            secret?: string;

                                                                                              property webhookPath

                                                                                              webhookPath?: string;

                                                                                                Type Aliases

                                                                                                type ApplicationFunction

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

                                                                                                  type ApplicationFunctionOptions

                                                                                                  type ApplicationFunctionOptions = {
                                                                                                  getRouter?: (path?: string) => express.Router;
                                                                                                  cwd?: string;
                                                                                                  [key: string]: unknown;
                                                                                                  };

                                                                                                    type ProbotOctokit

                                                                                                    type ProbotOctokit = InstanceType<typeof ProbotOctokit>;

                                                                                                      Namespaces

                                                                                                      namespace global

                                                                                                      namespace global {}

                                                                                                        namespace global.NodeJS

                                                                                                        namespace global.NodeJS {}

                                                                                                          interface ProcessEnv

                                                                                                          interface ProcessEnv {}

                                                                                                            property APP_ID

                                                                                                            APP_ID?: string;
                                                                                                            • The App ID assigned to your GitHub App.

                                                                                                              Example 1

                                                                                                              '1234'

                                                                                                            property GH_ORG

                                                                                                            GH_ORG?: string;
                                                                                                            • The organization where you want to register the app in the app creation manifest flow. If set, the app is registered for an organization (https://github.com/organizations/ORGANIZATION/settings/apps/new), if not set, the GitHub app would be registered for the user account (https://github.com/settings/apps/new).

                                                                                                            property GHE_HOST

                                                                                                            GHE_HOST?: string;
                                                                                                            • The hostname of your GitHub Enterprise instance.

                                                                                                              Example 1

                                                                                                              github.mycompany.com

                                                                                                            property GHE_PROTOCOL

                                                                                                            GHE_PROTOCOL?: string;
                                                                                                            • The protocol of your GitHub Enterprise instance. Defaults to HTTPS. Do not change unless you are certain. 'https'

                                                                                                            property HOST

                                                                                                            HOST?: string;
                                                                                                            • The host to start the local server on.

                                                                                                            property LOG_FORMAT

                                                                                                            LOG_FORMAT?: 'json' | 'pretty';
                                                                                                            • By default, logs are formatted for readability in development. You can set this to json in order to disable the formatting.

                                                                                                            property LOG_LEVEL

                                                                                                            LOG_LEVEL?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
                                                                                                            • The verbosity of logs to show when running your app, which can be fatal, error, warn, info, debug, trace or silent. 'info'

                                                                                                            property LOG_LEVEL_IN_STRING

                                                                                                            LOG_LEVEL_IN_STRING?: 'true' | 'false';
                                                                                                            • By default, when using the json format, the level printed in the log records is an int (10, 20, ..). This option tells the logger to print level as a string: {"level": "info"}. Default false

                                                                                                            property LOG_MESSAGE_KEY

                                                                                                            LOG_MESSAGE_KEY?: string;
                                                                                                            • Only relevant when LOG_FORMAT is set to json. Sets the json key for the log message. 'msg'

                                                                                                            property NODE_ENV

                                                                                                            NODE_ENV?: string;

                                                                                                              property PORT

                                                                                                              PORT?: string;
                                                                                                              • The port to start the local server on. '3000'

                                                                                                              property PRIVATE_KEY

                                                                                                              PRIVATE_KEY?: string;
                                                                                                              • The contents of the private key for your GitHub App. If you're unable to use multiline environment variables, use base64 encoding to convert the key to a single line string. See the Deployment docs for provider specific usage.

                                                                                                              property PRIVATE_KEY_PATH

                                                                                                              PRIVATE_KEY_PATH?: string;
                                                                                                              • When using the PRIVATE_KEY_PATH environment variable, set it to the path of the .pem file that you downloaded from your GitHub App registration.

                                                                                                                Example 1

                                                                                                                'path/to/key.pem'

                                                                                                              property REDIS_URL

                                                                                                              REDIS_URL?: string;
                                                                                                              • Set to a redis:// url as connection option for [ioredis](https://github.com/luin/ioredis#connect-to-redis) in order to enable [cluster support for request throttling](https://github.com/octokit/plugin-throttling.js#clustering).

                                                                                                                Example 1

                                                                                                                'redis://:secret@redis-123.redislabs.com:12345/0'

                                                                                                              property SENTRY_DSN

                                                                                                              SENTRY_DSN?: string;
                                                                                                              • Set to a [Sentry](https://sentry.io/) DSN to report all errors thrown by your app.

                                                                                                                Example 1

                                                                                                                'https://1234abcd@sentry.io/12345'

                                                                                                              property WEBHOOK_PATH

                                                                                                              WEBHOOK_PATH?: string;
                                                                                                              • The URL path which will receive webhooks. '/api/github/webhooks'

                                                                                                              property WEBHOOK_PROXY_URL

                                                                                                              WEBHOOK_PROXY_URL?: string;
                                                                                                              • Allows your local development environment to receive GitHub webhook events. Go to https://smee.io/new to get started.

                                                                                                                Example 1

                                                                                                                'https://smee.io/your-custom-url'

                                                                                                              property WEBHOOK_SECRET

                                                                                                              WEBHOOK_SECRET?: string;
                                                                                                              • **Required** The webhook secret used when creating a GitHub App. 'development' is used as a default, but the value in .env needs to match the value configured in your App settings on GitHub. Note: GitHub marks this value as optional, but for optimal security it's required for Probot apps.

                                                                                                                Example 1

                                                                                                                'development' 'development'

                                                                                                              Package Files (9)

                                                                                                              Dependencies (26)

                                                                                                              Dev Dependencies (24)

                                                                                                              Peer Dependencies (0)

                                                                                                              No peer dependencies.

                                                                                                              Badge

                                                                                                              To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                                                              You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/probot.

                                                                                                              • Markdown
                                                                                                                [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/probot)
                                                                                                              • HTML
                                                                                                                <a href="https://www.jsdocs.io/package/probot"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>