Use Slack and Bitbucket Server together

このページの内容

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

このページの内容

How do I install the Bitbucket Server for Slack app in Bitbucket?

To install the Bitbucket Server 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 Server 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 Server for Slack (Official) versions compatible with your instance, you can look through our version history page.

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

Slack requires that the Bitbucket instance is accessible through the internet via a secure connection (HTTPS). Therefore, you need to open up your secure port and make sure that the server has a valid certificate.

If that's not an option for you, you are still able to setup a limited connection with Slack by creating a custom Slack app that will give you notifications from Bitbucket to Slack. See how to create an app below in this page.

As a Bitbucket administrator

In the Bitbucket Server administration area, 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 Server base URL.


Do not include a trailing after your web address. Make sure your web address is secured with HTTPS protocol and reachable from the internet.


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

       4. In Bitbucket Server, 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 Server in a direct message with Slackbot.

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

As a Bitbucket administrator

In the Bitbucket Server administration area, 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 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 Server repository settings area, 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.

プライベート チャンネルへの接続方法

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 Server to a direct message or multi-party direct message?

It's not possible to set up Bitbucket Server 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 Server 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 from below to connect your new workspace to this Bitbucket Server instance.

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

The process for setting up additional Bitbucket Server 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 Server instance and Slack. You can repeat this process multiple times for each additional Bitbucket Server 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

You can skip this section if your Bitbucket instance is behind a firewall so that Slack can't reach it.

  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 Server instance base URL (eg. bitbucket-demo.company.com).

  4. Save your changes.

Step 3: Create slash commands

You can skip this section if your Bitbucket instance is behind a firewall so that Slack can't reach it.

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 Server's URL:
    Command name: /bitbucket_server
    Request URLhttps://{{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 Server's URL.

  4. Click Save URLs.

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

channels:read

channels:write

links:read

groups:read

groups:write

links:write

im:read

mpim:read

chat:write:bot

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

Without all of these scopes, it's possible that the bot will not function correctly. If you're having issues with the bot working later, please reference that you've asked for all required permissions.

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

You can skip this section if your Bitbucket instance is behind a firewall so that Slack can't reach it.

  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.

Please make sure that it says Verified to ensure your connection between Slack and your Bitbucket Server instance.

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

app_uninstalled

channel_archive

channel_deleted

channel_unarchive

group_archive

group_deleted

group_unarchive

link_shared

tokens_revoked


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

member_joined_channel

message.channels

message.groups

message.im

message.mpim

 

Make sure all of the events have been added. If you're having issues with the bot working later, please reference that you've added all required events.

4. Scroll down to App Unfurl Domains and add your Bitbucket Server 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 Server 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.

Data Center 製品での連携の使用可否について

Yes, this integration is fully compatible with Bitbucket Data Center.

Which Slash commands does the Bitbucket Server integration support? 

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

スラッシュ コマンド操作
/bitbucket_server help

Show help information about slash commands.

/bitbucket_server accountShow your Bitbucket account, if you have connected it to your Slack account. Connecting your accounts is required if you want to access issues in Slack or setup channels in Bitbucket.

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:

System property name説明Plugin default value
slack.client.max.channel.bulk.loadMaximum number of Slack channels that are fetched at once, used in the administration page. It can affect how Slack rate limits the integration.50
slack.client.list.all.conversations

If enabled, channel selector dropdown in configuration page will list all Slack channels for the selected workspace, rather than the user channels.

(warning) Do not use this is large workspaces but could be useful for small ones.

false
slack.client.pagination.limit

Maximum number of channels to load if slack.client.list.all.conversations is enabled. Each page loads a thousand channels, so a pagination limit of 2 means 2000 channels max.

(warning) Increasing this value too much will slow down or crash your browser, as it will try to render thousands of entries.

2



slack.client.retry.on.connection.failureOkHttp3 boolean flag to retry if failed to establish a connection. Documentation.true
slack.client.connect.timeoutOkHttp3 timeout in ms when establishing new connections. Documentation.3000
slack.client.read.timeoutOkHttp3 timeout in ms while waiting for data in a connection. Documentation.10000
slack.client.retry.countNumber of times the Slack client retries in case it gets a 5xx response. Backoff delays in seconds are 1, 3, 5, 8, 13, and 30 seconds, respectively.3
slack.client.rate.limit.retry.countNumber of times the Slack client retries in case if gets a 429 HTTP response from Slack. Documentation. By default, Slack will return a Retry-After header with a time interval the client will use to delay the next attempt3
slack.client.thread.pool.sizeAffects how many threads will process Slack notifications but also affects other asynchronous operations in the integration, such as the ability of handling incoming requests from Slack.5
slack.client.queue.size

Limits the memory consumed by the integration. For instance, if a big spike in events trigger a large number of notifications at once, if the queue maximum size is reached, new attempts to schedule notifications will fail and those notifications will be dropped.

Note that, with a default value of 1000, it would require 1001 or more events happening at basically the same, without giving a change to the queue to be processed. A big bulk edit could reach such limit if the Slack notifications are enabled in that context.

1000
slack.client.cache.expire.secondsTime in seconds to expire cached values from Slack requests (channels and user names, for instance). Note that values are cached according to the Slack token, so they are all restricted to the respective Slack user.900 (15mi)
slack.notification.max.watchers
Maximum number of pull request watchers to notify on events. It might affect rate-limiting.30
slack.addon.unfurl.file.max.linesMaximum number of lines that will be unfurled in Slack.5

Some of the system properties and the upper limits they represent, when in a clustered environment, will affect nodes individually. So limits such as queue size will scale according to the number of nodes available in the cluster.

How can I troubleshoot the integration?

デバッグ ロギング

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.

これはアトラシアンのサポート対象ですか?

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

最終更新日: 2020 年 2 月 6 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.