Probot Messages

A Probot extension for communicating with repository maintainers. It is used for delivering messages that require user action to ensure the correct operation of the app, such as configuring the app after installation, or fixing configuration errors.

How It Works

A new issue is opened for messages that don't already have an open issue, otherwise an optional update is posted on the existing issue in the form of a comment.

Usage

$ npm install probot-messages

Required permissions

• Issues - Read & Write
• Repository metadata - Read-only

Examples

Notify maintainers about additional configuration steps.

const sendMessage = require('probot-messages');

module.exports = app => {
  app.on('installation_repositories.added', async context => {
    for (const item of context.payload.repositories_added) {
      const [owner, repo] = item.full_name.split('/');
      await sendMessage(
        app,
        context,
        '[{appName}] Getting started',
        'Follow these steps to configure the app...',
        {owner, repo}
      );
    }
  });
};

Notify maintainers about configuration errors.

const sendMessage = require('probot-messages');

module.exports = app => {
  app.on('push', async context => {
    const configFile = 'config.yml';
    try {
      const config = await context.config(configFile);
    } catch (error) {
      if (error.name === 'YAMLException') {
        await sendMessage(
          app,
          context,
          '[{appName}] Configuration error',
          '[{appName}]({appUrl}) has encountered a configuration error in ' +
            `\`${configFile}\`.\n\`\`\`\n${error.toString()}\n\`\`\``,
          {update: 'The configuration error is still occurring.'}
        );
      }
    }
  });
};

API

sendMessage

Messages repository maintainers by submitting an issue.

Parameters

• app Object app instance
• context Object event context
• title string issue title, {appName} and {appUrl} are optional placeholders
• message string issue content, {appName} and {appUrl} are optional placeholders
• options Object? options (optional, default {})
  • options.update string? update to post as a comment, {appName} and {appUrl} are optional placeholders, no update is posted if the value is falsy or the issue is locked (optional, default '')
  • options.updateAfterDays number? post update only if the issue had no activity in this many days (optional, default 7)
  • options.owner string? owner of the repository (optional, default value inferred from context)
  • options.repo string? repository (optional, default value inferred from context)

Examples

const sendMessage = require('probot-messages');

module.exports = app => {
  app.on('issue_comment.created', async context => {
    await sendMessage(app, context, 'Title', 'Message');
  });
};

Returns Promise<Message> Promise that will be fulfilled with a Message object

Message

Details of the message.

Type: Object

Properties

• owner string owner of the repository
• repo string repository
• issue number issue number of the message
• comment number? comment ID of the update
• isNew boolean indicates if the issue was newly created

License

Copyright (c) 2018-2021 Armin Sebastian

This software is released under the terms of the MIT License. See the LICENSE file for further information.