Setting up connector

General Info 

MS Teams connector plugin is made to send webhooks from Bitbucket to channel in MS Teams messenger. The notifications are based on the events user has chosen to get notifications about. 

Whether you are planning to get notified on pull request events or if someone forked a repository, you can customize it as you need and get information in MS Teams channel in a cool and informative way. 

Set up

In order to establish Bitbucket and MS Teams communication user must set up a connection on the MS Teams and Bitbucket side. To do so see the instruction below. 

I. Create a channel in MS Teams messenger

(skip if you already have one)

Switch to Teams tab.

>

Press Join or create a team.

>

Press Create Team.

>

Give name to your Team and Press Next.

II. Set up a connector in MS Teams

1. Go to your MS Teams channel and choose "Connectors" option in the channel settings menu.

2. Select "Incoming Webhook" in the list of provides options. 

Press Add to start configuring webhook connector.

3. Give name to the connector created in MS Teams

(notifications from Bitbucket will be marked with it as title - ex. Bitbucket webhook)

Press Create.

5. After you have set up the Incoming Webhook connector in MS Teams get a channel link. You will need it to complete set up in Bitbucket. 

To copy a link to the clipboard press a button next to the link.

Press Save.

III. Set up a connector in Bitbucket

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 to MS Teams channel 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 → MS Teams Connector

For Repository: Bitbucket → Project → Repository → Repository settings → MS Teams Connector

This is the menu where you can complete the set up. 

Paste previously copied channel link into the field "Webhook URL" and press Test Connection if you want to double check connection.

If everything is done right you will see a notification on successful setup completion. Now you can customize notification events you want to receive in MS Teams channel. 

IV. Configure notification Filters

MS teams Connector allows narrowing down notification pool to minimize notification spamming with the help of 4 filters:

• Users

Select users in the corresponding fields if you want to get notification to channel only if actions are performed by them.

• User Groups

Notification will be sent to MS Teams channel only if events were triggered by users in the selected group.

• Branch (only on repository level)

Type branch name if you want to get notifications only if they took place within this particular branch. You can add several branches to monitor for events happening within.

This filter works only for events like Push, File changed and all of the Pull Request section events. If some other event takes place within a repository, it will bypass this filter.

• Folder (only on repository level)

Type repository folder or folder path to get notification to MS Teams channel only about events happening within particular folder. Type another folder name or its path in the new field to monitor for events in all selected folders.

This filter works only for events like Push, Merged, File changed. If some other event takes place within a repository, it will bypass this filter.

V. Set up notifications

Given webhook connector provides user with a range of events one can choose to receive in MS Teams channel. 

After the connection is set up you can customize connector to send only those event notifications that you want it to. Select checkboxes next to the events you want to get notifications about.

Press Save.

Now every time the selected event takes place with the current repository, a corresponding message will appear in your MS Teams channel.

User can create several configurations for the same repository in case it is required to split notification messages into different channels depending on the event type. To create another configuration save current one and press "New setting".  

Please take into account that messages are processed by MS Teams channel which may result in notification delay.

Also creating several configurations using the same MS Teams channel link is not possible, unless one of them is created on project level.

Connector Activation/Deactivation

Notifications from Bitbucket can be turned On and Off at once in repository settings menu.

Just fing a toggle element at the top of the connector interface and change it's status by clicking on it. Depending on its state notifications will be active  or inactive.