Use Slack and Bitbucket Data Center together

How do I install the Bitbucket Data Center for Slack app in Bitbucket?

To install the Bitbucket Data Center for Slack app:

1. Log into your Bitbucket instance as an admin.

2. Click the admin menu and choose Add-ons. The Manage add-ons screen loads.

3. Click Find new apps or Find new add-ons from the left-hand side of the page.

4. Locate Bitbucket Data Center for Slack (Official) via search. Results include app versions compatible with your Bitbucket instance.

5. Click Install to download and install your app.

6. You're all set! Click Close in the Installed and ready to go dialog.

To find older Bitbucket for Slack (Official) versions compatible with your instance, you can look through our version history page.

How do I configure and connect the Bitbucket Data Center for Slack app to my Bitbucket site?

As a Bitbucket administrator

In the Bitbucket Data Center administration, you'll now have a Slack Integration navigation item under Add-ons.

1. Go to Slack Integration and select Connect Slack Team.

2. Click Go to Slack.

3. Click the green Install button for the Slack app and complete Slack's OAuth process.

Once you complete the OAuth process in Slack, you'll then see a new configuration page for your integration.

1. Scroll to the bottom to see the two fields you need to complete.

2. Add your Bitbucket base URL.

      3. Copy the contents of box #2 back into your Bitbucket setup.

       4. In Bitbucket, paste the Slack credentials into the Bitbucket configuration and then click Save.

       5. In your Slack window, click Submit.

Once the connection has been set up, you'll receive a success notification from Bitbucket in a direct message with Slackbot.

How do I configure a repository to post notifications into Slack?

As a Bitbucket administrator

In the Bitbucket administration, you'll now have a Slack Integration navigation item under Add-ons.

To access any Slack information, either private or public, you need to confirm your Slack account by doing the following:

1. Click the confirmation link to take you through the authentication flow in Slack.

2. Authorize the application to access your channels.

3. Connect Bitbucket repositories to different Slack channels.

You should now see You're accessing Slack as [Your Name] as well as public and private channels that you have access to in the channel picker.

      4. Select a repository and a channel, and then click Add.

You'll now see the new connection to Slack listed in the configuration table as well as receive a notification in Slack that Bitbucket notifications have been set up to appear in the channel.

From the configuration section, you can filter exactly what notifications you want to be sent to that channel by subscribing or unsubscribing to pull requests, repositories, commits, and commit events.

As a Repository administrator

Repository administrators are able to set up and configure their Slack notifications.

In the Bitbucket repository settings, you’ll have a Slack integration navigation item under Workflow.

In order to access any Slack information, either private or public, you need to confirm your Slack account by doing the following:

1. Click the confirmation link to take you through the authentication flow in Slack.

2. Authorize the application to access your channels.

3. Connect Bitbucket repositories to different Slack channels.

You should now see You're accessing Slack as [Your Name] as well as public and private channels that you have access to in the channel picker.

From this page, repository administrators can see current Slack channel connections for that repository, as well as set up new ones.

How do I connect to a private channel?

Once you have confirmed your account in the administration page, you should now see You're accessing Slack as [Your Name], and should now be able to select public and private channels from the channel picker.

How do I set up personal notifications?

The integration allows you to receive some specific personal notifications in Slack via a direct message from the bot.

1. Go to your Bitbucket user profile page.
2. Click the Manage Account > Slack notifications.
3. In the next page, choose the options for when you want to be notified and the Slack workspace of your preference.
   

How do I connect Bitbucket Data Center to a direct message or multi-party direct message?

It's not possible to set up Bitbucket notifications into Slack's direct messages or multi-party direct messages.
Alternatively we suggest setting up a private channel and configuring notifications to route there.

How do I connect to multiple Slack Workspaces?

The Bitbucket Data Center for Slack app supports the ability to connect to multiple Slack Workspaces, such as in a Slack Enterprise Grid.

1. At the top of the global Administration Slack page in Bitbucket, select the Workspace Selector menu.

2. Choose Connect to a new team.

3. Follow the steps below to connect your new workspace to this Bitbucket instance.

I use multiple Bitbucket instances or my instances are behind a firewall. How do I connect them to Slack?

The process for setting up additional Bitbucket instances with Slack takes some manual configuration to set up. Please ensure that you follow the below steps perfectly to ensure proper connectivity between your Bitbucket instance and Slack. You can repeat this process multiple times for each additional Bitbucket instance you have.

Step 1: Create the app

To get started, first visit https://api.slack.com/apps?new_classic_app=1. Make sure you create the App with classic scopes as Slack has released a new permission model that's not compatible with this App at this moment.

Step 2: Enable interactive components

1. In your app settings, go to Features > Interactive Components.

2. Click on the toggle button to turn Interactivity on.

3. Set the Request URL with https://{{url}}/rest/slack/latest/action, replacing {{url}} with your Bitbucket instance base URL (eg. bitbucket-demo.company.com).

4. Save your changes.

Step 3: Create slash commands

Slash commands lets users trigger an interaction with your app directly from the message box in Slack.

1. In your app settings, go to Slash Commands.

2. Click Create New Command.

3. Copy the details of this command over, replacing {{url}} with your Bitbucket URL:
   Command name: /bitbucket_server
   Request URL: https://{{url}}/rest/slack/latest/command
   Usage hint: account, help

   Make sure the Command name is not taken by another Slack app in your workspace.

   Once saved, your new slash command should show up in the list.

Step 4: Set up OAuth & Permissions

In order to set up all required scopes and permissions:

1. Go to Features > OAuth & Permissions.

2. Click Add New Redirect URL.

3. Set this to https://{{url}}/rest/slack/latest/oauth, replacing {{url}} with your Bitbucket URL.

4. Click Save URLs.

5. Scroll down to the Scopes section and add the following scopes:

     6. Double-check that you've added all scopes, and click Save.

Step 5: Add bot users

1. In the Features navigation bar, click Bot Users > Add a Bot User.

2. Set the display name and default username to whatever you'd like (for instance, Production Bitbucket).

3. Click Add Bot User.

Step 6: Subscribe to event subscriptions

1. In the navigation bar, go to Event Subscriptions.

2. Click the Enable Events toggle button.

3. Add your Request URL https://{{url}}/rest/slack/latest/event.

4. Click Change.

Now you can subscribe to the following events under Workspace Events:

Scroll down to Bot Events and add the following events here:

4. Scroll down to App Unfurl Domains and add your Bitbucket domain.

5. Click Save Changes to complete this section.

Step 7: Install the app

You can now install your app to your Slack workspace:

1. In the navigation bar, go to Settings > Install App.

2. Click Install App to Workspace.

3. In the Bitbucket configuration screen, from the Workspace Selector menu, select Connect to a new Team.

4. Choose Advanced connection type.

You'll need to copy each of the settings from your Slack app configuration into this screen.

Once completed, you'll be able to start using your Bitbucket integration.

Can I distribute the Slack App I created to connect my Bitbucket instance to multiple workspaces?

Yes, if you have followed the steps above to created a custom App.

First, your instance needs to have at least one connection with a workspace using the App credentials. This is required so the integration knows the App's client and secret.

Then, find the installation URL in Slack:

1. Find your App in Slack API page.
2. Go to the Manage Distribution under Settings.
3. Activate distribution with other workspaces. You will need to meet Slack's requirements for that.
4. Copy the Sharable URL.
5. Navigate to the shareable URL in a browser. It will trigger an installation flow. 
6. Select the target workspace and proceed.
7. At this point, if your App and the integration are correctly setup, you should be redirected to the integration configuration page in Bitbucket, with the new connection already setup for you.

Which Slash commands does the Bitbucket integration support? 

There are the slash commands you can use while interacting with the integration:

How can I fine-tune the integration?

Various system properties are available that allows you to tune specific parts of the integration, as described in the table below:

How can I troubleshoot the integration?

Debug logging

You can enable DEBUG level logging though configuration, using the following packages:

• com.atlassian.plugins.slack
• com.atlassian.bitbucket.plugins.slack

Connectivity from Slack

If you're having connectivity issues between your instance and Slack, double-check the following:

• Slack can reach your instance through a HTTPS-secured URL.
• You have properly saved your base URL without a trailing slash in the Slack App configuration.

• Make sure the path <baseUrl>/rest/slack/latest/* are whitelisted in your firewall and security filters in place.

• Make sure those paths allows "anonymous" requests, since incoming requests from Slack use a different authentication mechanism.
• If you're unable to expose your instance, you can still use the integration in notification-only mode, by creating a custom app as described in this page.

You can check the integration is available by making a request to the verification event endpoint. In a bash terminal it can be done with the following command:

curl -X POST \
  https://<bitbucket-base-url>/rest/slack/latest/event \
  -H 'Content-Type: application/json' \
  -H "X-Slack-Request-Timestamp: $(date +%s)" \
  -H 'X-Slack-Signature: any-value' \
  -d '{"challenge": "boo","type": "url_verification"}'

Failure to submit instance URL in Slack

The "Oops" error when submitting your instance URL is known to happen sometimes just after the App has been removed from a workspace, because Slack tries to reach out to the instance before completing the uninstallation.

This issue tends to fix itself within 15 or so as Slack finishes the process.

Is this supported by Atlassian?

Yes, absolutely. This integration is built and maintained by Atlassian. If you need support, visit support.atlassian.com.