Connector for Bitbucket - User Guide

 

 

This is the guide how to use Telegram connector for Bitbucket add-on. Here you can find the necessary information how to start working with it step-by-step.

 

Step 1 - Create your bot

for Bitbucket administrators

 

Before you begin to receive notifications, Bitbucket administrator must establish a connection between Telegram and Bitbucket itself.

All communication between these services is performed via your custom telegram bot. If you don’t have one, please use the official documentation to get your bot. (see here)

Here is a quick guide how to:

  1. Open Telegram.

  2. Search for BotFather bot.

  3. Type /start and follow the given workflow to create your bot (bot’s name must end in "bot").

  4. Done. Your bot is created.

 

Step 2 - Set up connection

for Bitbucket administrators

 

After add-on installation Bitbucket administrator must go to Settings → Telegram Connector to establish connection between Bitbucket and Telegram.

 

 

Here administrator must add crucial information about created Telegram bot:

  • Bot name

  • Access token.

This information is given only to bot creator from BotFather. Alongside with other control options.

 

After configuration is saved, service connection is complete. Now users can set up their own notification rules.

 

Proxy

Optionally add-on supports sending messages using proxy. To send add-on traffic via proxy add required information into bot configuration settings:

  • Proxy Host

  • Proxy Port

 

Press Save/Restart to update information.

Step 3 - Create configuration

 

Users can be notified on events happening with your project or repository via Telegram group chats. All notifications are sent from Bitbucket on behalf of your custom bot used for the whole Bitbucket instance.

 

Each project or repository administrator can set up configuration that will notify on certain events.

To do so go to project/repository settings Telegram Connector. On this page you can create as many configurations as you want as long as they use different Telegram group ID.

 

 

 

There are 2 places where user can set up a connector in Bitbucket. 

  1. Repository settings

  2. Project settings

Both sections have identical basic features, yet connector on repository level will send notifications on events in particular repository. While connector on project level will notify on events in all repositories in project.

Configurations created on project level can be viewed on repository page, yet can cannot be edited there. Editing is possible only from add-on configuration in project settings.  

 

For Project: Bitbucket → Project → Project settings → Telegram Connector

For Repository: Bitbucket → Project → Repository → Repository settings → Telegram Connector

 

Telegram Group address

To start creating a configuration user must fill in the required fields:

  • Title (will be used as configuration name)

  • Telegram group ID

 

How to get Telegram group ID

  1. Create Telegram group chat (see instruction)

  2. Add bot to group chat (find bot name under "Telegram group ID" field)

  3. Send /info command in chat to get Telegram group ID. (use /start command first if needed)

 

You can always test your connection to see if it is set up correctly by clicking on "Test connection” button.

 

Events picking

After managing the Telegram group ID and bot commands users can select events they want to be notified on. Each configuration is split by 3 column of events depending on their specifics:

  • Pull request notifications

  • Repository notifications

  • Commit related notifications

 

Activating toggles next to events will enable sending notifications to Telegram chat as soon as this event takes place in Bitbucket.

To enable/disable the whole event column - activate or deactivate toggle for the whole column.

 

Press Save to apply your changes.

 


Telegram is a separate tool. Due to this fact there is a small chance of network connectivity related issues.