probot/docs/api.md

API

This is the official probot API. Anything not documented here is subject to change without notice.

Robot

The robot parameter available to plugins is an instance of Robot.

module.exports = robot => {
  // your code here
};

on

robot.on will listen for any GitHub GitHub webhooks, which are fired for almost every significant action that users take on GitHub. The on method takes a callback, which will be invoked with two arguments when GitHub delivers a webhook:

• event - the event that was triggered, including event.payload which has the payload from GitHub.
• context - helpers for extracting information from the event, which can be passed to GitHub API calls

module.exports = robot => {
  robot.on('push', (event, context) => {
    // Code was pushed to the repo, what should we do with it?
    robot.log(event);
  });
};

Most events also include an "action". For example, the issues event has actions of assigned, unassigned, labeled, unlabeled, opened, edited, milestoned, demilestoned, closed, and reopened. Often, your bot will only care about one type of action, so you can append it to the event name with a .:

module.exports = robot => {
  robot.on('issues.opened', event => {
    // An issue was just opened.
  });
};

auth

robot.auth(id) will return an authenticated GitHub client that can be used to make API calls. It takes the ID of the installation, which can be extracted from an event:

module.exports = function(robot) {
  robot.on('issues.opened', async (event, context) => {
    const github = await robot.auth(event.payload.installation.id);
  });
};

Note: robot.auth is asynchronous, so it needs to be prefixed with a await to wait for the magic to happen.

The github object returned from authenticating is an instance of the github Node.js module, which wraps the GitHub API and allows you to do almost anything programmatically that you can do through a web browser.

log

robot.log is a logger backed by bunyan.

robot.log("This is a debug message");
robot.log.debug("…so is this");
robot.log.trace("Now we're talking");
robot.log.info("I thought you should know…");
robot.log.warn("Woah there");
robot.log.error("ETOOMANYLOGS");
robot.log.fatal("Goodbye, cruel world!");

The default log level is debug, but you can change it by setting the LOG_LEVEL environment variable to trace, info, warn, error, or fatal.

Context

Context has helpers for extracting information from the webhook event, which can be passed to GitHub API calls.

repo

Return the owner and repo params for making API requests against a repository. The object passed in will be merged with the repo params.

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

issue

Return the owner, repo, and number params for making API requests against an issue or pull request. The object passed in will be merged with the repo params.

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

isBot

Returns a boolean if the actor on the event was a bot.