Bitbucket Cloud add-ons
Bitbucket Cloud apps create a link between Bitbucket and other applications. We currently offer a wide range of apps that provide you and your team access to code quality tools, graphs, web hosting, cloud based IDE's, and more right from Bitbucket. These apps appear as new features, integrations with an existing service, or other products that run right within Bitbucket.
How do apps work?
Apps 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. Apps 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 apps use the Atlassian Connect framework to build the integrations and create extension points in the Bitbucket UI. apps also make calls to Bitbucket's REST API to send and retrieve data and other information from Bitbucket.
When developers create apps for Bitbucket, they use a combination of factors to make sure each app is secure and has access to the right permissions. Apps use two separate lists of scopes to request these permissions. These requests appear as two different dialogs: 1) when the app is first installed and 2) when you first try to access the app.
When you or your team's administrator installs an app, 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 app declares these scopes in the app descriptor. That way, each request from Bitbucket to the third-party application contains only the necessary details. Included with the app are JSON Web Tokens (JWT), which transfer information securely between the application and Bitbucket.
OAuth consumer permissions
Each app 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 app 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 app. The following dialog is an example of what you might see when you grant access for an app, but it's appearance depends on the app.
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 app
You can install apps to your user account or your team's account. If you install the app from your user account, the app is only available to any of the repositories you can access. If an administrator installs an app on your team account, the app is only available to repositories that are part of your team.
Install an app
- 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 app you want and click Add.
- Review the access permissions the app is requesting and click Grant access if you approve.
As part of the installation process, some apps 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 app through the third party's site.
Remove an app
- 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 app you want to remove, then click Remove.
- A pop-up appears, making sure you want to remove the app. Click Remove if you are sure.
If you installed the app for your team, it won't be available to your team members once you remove it. If they would still want to use the app, they can install the it themselves on their personal account.
Create your own apps
Your team can build their own apps and install them on Bitbucket. To create one yourself, use the developer guide to learn all about Atlassian Connect for Bitbucket Cloud. Our example app is a good place to start. Once you have the app set up, you can use the rest of the developer guide to update how the app appears in Bitbucket and what it does. When you are ready to see your app 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 app from URL.
- From the pop-up that appears, paste in the URL and click Install.
Your app will appear along with the others on the Manage integrations page.