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, select avatar > Bitbucket settings 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, select avatar > Add-ons.
For a team, select Teams > team name, click Manage team, and then click Find new add-ons on the left side.
- Pick an add-on you want and click Install for that add-on.
- Review the access permissions the add-on is requesting and click Install 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, select avatar > Bitbucket settings.
For a team, select Teams > team name and then click Manage team.
- Click Manage add-ons under ADD-ONS AND FEATURES on the left side.
- 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 Add-Ons page in Bitbucket, 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 add-ons page.
Was this helpful?
Thanks for your feedback!