Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see http://docs.buildbot.net/current/.

2.5.15.16. Telegram Bot

Buildbot offers a bot, similar to the IRC for Telegram mobile and desktop messaging app. The bot can notify users and groups about build events, respond to status queries, or force and stop builds on request (if allowed to).

In order to use this reporter, you must first speak to BotFather and create a new telegram bot. A quick step-by-step procedure is as follows:

Start a chat with BotFather.
Type /newbot.
Enter a display name for your bot. It can be any string.
Enter a unique username for your bot. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot’s username must end in bot, e.g. MyBuildBot or MyBuildbotBot.
You will be presented with a token for your bot. Save it, as you will need it for TelegramBot configuration.

Optionally, you may type /setcommands, select the username of your new bot and paste the following text:

commands - list available commands
force - force a build
getid - get user and chat ID
hello - say hello
help - give help for a command or one of it's arguments
last - list last build status for a builder
list - list configured builders or workers
nay - forget the current command
notify - notify me about build events
shutdown - shutdown the buildbot master
source - the source code for buildbot
status - list status of a builder (or all builders)
stop - stop a running build
version - show buildbot version
watch - announce the completion of an active build

If you do this, Telegram will provide hints about your bot commands.

If you want, you can set a custom picture and description for your bot.

After setting up the bot in Telegram, you should configure it in Buildbot.

from buildbot.plugins import reporters
telegram = reporters.TelegramBot(
        bot_token='bot_token_given_by_botfather',
        bot_username'username_set_in_botfather_bot',
        chat_ids=[-1234567],
        authz={('force', 'stop'): "authorizednick"}
        notify_events=[
            'exception',
            'problem',
            'recovery',
            'worker'
        ],
        usePolling=True)
c['services'].append(telegram)

The following parameters are accepted by this class:

bot_token: (mandatory) Bot token given by BotFather.
bot_username: (optional) This should be set to the bot unique username defined in BotFather. If this parameter is missing, it will be retrieved from the Telegram server. However, in case of the connection problems, configuration of the Buildbot will be interrupted. For this reason it is advised to set this parameter to the correct value.
chat_ids: (optional) List of chats IDs to send notifications specified in the notify_events parameter. For channels it should have form @channelusername and for private chats and groups it should be a numeric ID. To get it, talk to your bot or add it to a Telegram group and issue /getid command.

Note

In order to receive notification from the bot, you need to talk to it first (and hit the /start button) or add it to the group chat.

authz

(optional) Authentication list for commands. It must be a dictionary with command names (without slashes) or tuples of command names as keys. There are two special command names: '' (empty string) meaning any harmless command and '!' for dangerous commands (currently /force, /stop, and /shutdown). The dictionary values are either True of False (which allows or deny commands for everybody) or a list of numeric IDs authorized to issue specified commands. By default, harmless commands are allowed for everybody and the dangerous ones are prohibited.

A sample authz parameter may look as follows:

authz={
  'getid': True,
  '': [123456, 789012],
  ('force', 'stop'): [123456],
}

Anybody will be able to run the getid command, users with IDs 123456 and 789012 will be allowed to run any safe command and the user with ID 123456 will also have the right to force and stop builds.

tags

(optional) When set, this bot will only communicate about builders containing those tags. (tags functionality is not yet implemented)

notify_events

(optional) A list or set of events to be notified on the Telegram chats. Telegram bot can listen to build ‘start’ and ‘finish’ events. It can also notify about missing workers and their return. This parameter can be changed during run-time by sending the /notify command to the bot. Note however, that at the buildbot restart or reconfig the notifications listed here will be turned on for the specified chats. On the other hand, removing events from this parameters will not automatically stop notifications for them (you need to turn them off for every channel with the /notify command).

showBlameList

(optional, disabled by default) Whether or not to display the blame list for failed builds. (blame list functionality is not yet implemented)

useRevisions

(optional, disabled by default) Whether or not to display the revision leading to the build the messages are about. (useRevisions functionality is not yet implemented)

useWebhook

(optional, disabled by default) By default this bot receives messages from Telegram through polling. You can configure it to use a web-hook, which may be more efficient. However, this requires the web frontend of the Buildbot to be configured and accessible through HTTPS (not HTTP) on a public IP and port number 443, 80, 88, or 8443. Furthermore, the Buildbot configuration option buildbotURL must be correctly set. If you are using HTTP authentication, please ensure that the location buildbotURL/telegrambot_token (e.g. https://buildbot.example.com/telegram123456:secret) is accessible by everybody.

certificate

(optional) A content of your server SSL certificate. This is necessary if the access to the Buildbot web interface is through HTTPS protocol with self-signed certificate and userWebhook is set to True.

pollTimeout

(optional) The time the bot should wait for Telegram to respond to polling using long polling.

retryDelay

(optional) The delay the bot should wait before attempting to retry communication in case of no connection.

To use the service, you sent Telegram commands (messages starting with a slash) to the bot. In most cases you do not need to add any parameters; the bot will ask you about the details.

Some of the commands currently available:

/getid

Get ID of the user and group. This is useful to find the numeric IDs, which should be put in authz and chat_ids configuration parameters.

/list

Emit a list of all configured builders, workers or recent changes.

/status

Announce the status of all builders.

/watch

You will be presented with a list of builders that are currently running. You can select any of them to be notified when the build finishes..

/last

Return the results of the last builds on every builder.

/notify

Report events relating to builds. If the command is issued as a private message, then the report will be sent back as a private message to the user who issued the command. Otherwise, the report will be sent to the group chat. Available events to be notified are:

started: A build has started.
finished: A build has finished.
success: A build finished successfully.
failure: A build failed.
exception: A build generated and exception.
cancelled: A build was cancelled.
problem: The previous build result was success or warnings, but this one ended with failure or exception.
recovery: This is the opposite of problem: the previous build result was failure or exception and this one ended with success or warnings.
worse: A build state was worse than the previous one (so e.g. it ended with warnings and the previous one was successful).
better: A build state was better than the previous one.
worker: A worker is missing. A notification is also send when the previously reported missing worker connects again.

By default this command can be executed by anybody. However, consider limiting it with authz, as enabling notifications in huge number of chats (of any kind) can cause some problems with your buildbot efficiency.

/help

Show short help for the commands.

/commands

List all available commands. If you explicitly type /commands botfather, the bot will respond with a list of commands with short descriptions, to be provided to BotFather.

/source

Announce the URL of the Buildbot’s home page.

/version

Announce the version of this Buildbot.

If explicitly allowed in the authz config, some additional commands will be available:

/force: Force a build. The bot will read configuration from every configured ForceScheduler and present you with the build parameters you can change. If you set all the required parameters, you will be given an option to start the build.
/stop: Stop a build. If there are any active builds, you will be presented with options to stop them.
/shutdown: Control the shutdown process of the Buildbot master. You will be presented with options to start a graceful shutdown, stop it or to shutdown immediately.

If you are in the middle of the conversation with the bot (e.g. it has just asked you a question), you can always stop the current command with a command /nay.

If the tags is set (see the tags option in Builder Configuration) changes related to only builders belonging to those tags of builders will be sent to the channel.

If the useRevisions option is set to True, the IRC bot will send status messages that replace the build number with a list of revisions that are contained in that build. So instead of seeing build #253 of …, you would see something like build containing revisions a87b2c4. Revisions that are stored as hashes are shortened to 7 characters in length, as multiple revisions can be contained in one build and may result in too long messages.