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, default7
) -
options.owner
string? owner of the repository (optional, default value inferred fromcontext
) -
options.repo
string? repository (optional, default value inferred fromcontext
)
-
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.