Bitbucket Cloud add-ons
Bitbucket Cloud add-ons create a link between Bitbucket and other applications. We currently offer a wide range of add-ons that provide you and your team access to code quality tools, graphs, web hosting, cloud based IDE's, and more right from Bitbucket. These add-ons appear as new features, integrations with an existing service, or other products that run right within Bitbucket.
How do add-ons work?
Add-ons extend the reach and power of Bitbucket by providing a way for third parties to embed their applications directly into your Bitbucket account. Many of them appear as UI elements in the form of new pages, tabs, or sections. Add-ons can also change your interaction with Bitbucket. For example, they might use webhooks to notify the third-party application when an event occurs in Bitbucket.
The providers of these add-ons use the Atlassian Connect framework to build the integrations and create extension points in the Bitbucket UI. Add-ons also make calls to Bitbucket's REST API to send and retrieve data and other information from Bitbucket.
When developers create add-ons for Bitbucket, they use a combination of factors to make sure each add-on is secure and has access to the right permissions. Add-ons use two separate lists of scopes to request these permissions. These requests appear as two different dialogs: 1) when the add-on is first installed and 2) when you first try to access the add-on.
When you or your team's administrator installs an add-on, a dialog appears with a list of what the application will be able to access and the type of permissions it will have. The creator of the add-on declares these scopes in the add-on descriptor. That way, each request from Bitbucket to the third-party application contains only the necessary details. Included with the add-on are JSON Web Tokens (JWT), which transfer information securely between the application and Bitbucket.
OAuth consumer permissions
Each add-on also uses OAuth consumers to make requests on behalf of individual Bitbucket users. As a result, your personal data remains protected from unauthorized access and malicious or accidental changes.
On the first encounter of an add-on that you or your team has a recently installed, you'll see a window or page, similar to the installation dialog, that lists the scopes for the OAuth consumer. This message also includes a Grant Access button or link, which you need to click if you want to start using the add-on. The following dialog is an example of what you might see when you grant access for an add-on, but it's appearance depends on the add-on.
You can see the list of applications that you have granted access to under the OAuth integrated applications section in your account. To see this list, click Bitbucket settings from your avatar in the bottom left and click the Oath link.
Install and remove an add-on
You can install add-ons to your user account or your team's account. If you install the add-on from your user account, the add-on is only available to any of the repositories you can access. If an administrator installs an add-on on your team account, the add-on is only available to repositories that are part of your team.
Install an add-on
- For your user account: From your avatar in the bottom left, select Integrations.
For a team: From your avatar in the bottom left, select your team or click View all teams for a full list. Click Settings in the sidebar, and then click Find integrations.
- Pick an add-on you want and click Add.
- Review the access permissions the add-on is requesting and click Grant access if you approve.
As part of the installation process, some add-ons might request that you sign-on to or provide permission from their service. If that's the case, you'll be redirected to their site. You might also be able to adjust the functions of an add-on through the third party's site.
Remove an add-on
- For your user account: From your avatar in the bottom left, select Bitbucket settings.
For a team: From your avatar in the bottom left, select your team or click View all teams for a full list. Click Settings in the sidebar.
- Click Manage integrations under Integrations and features.
- Select the add-on you want to remove, then click Remove.
- A pop-up appears, making sure you want to remove the add-on. Click Remove if you are sure.
If you installed the add-on for your team, it won't be available to your team members once you remove it. If they would still want to use the add-on, they can install the it themselves on their personal account.
Create your own add-ons
Your team can build their own add-ons and install them on Bitbucket. To create one yourself, use the developer guide to learn all about Atlassian Connect for Bitbucket Cloud. Our example add-on is a good place to start. Once you have the add-on set up, you can use the rest of the developer guide to update how the add-on appears in Bitbucket and what it does. When you are ready to see your add-on in Bitbucket, use the following steps.
- Copy the URL to the application you created. If you used ngrok, the URL is the
httpsforwarding address you copied from ngrok.
- From the Manage integrations page, click Install add-on from URL.
- From the pop-up that appears, paste in the URL and click Install.
Your add-on will appear along with the others on the Manage integrations page.