Bitbucket Cloud apps overview

Bitbucket Cloud apps create a link between Bitbucket and other applications. 

Apps extend the reach and power of Bitbucket by providing a way for you to embed third-party applications directly into your Bitbucket account. Apps can appear as extensions of Bitbucket's interface, like new pages, tabs, or sections inside Bitbucket.

Apps can also change how you interact with Bitbucket. For example, a Bitbucket app could use webhooks to notify a third-party application when a specific event occurs in Bitbucket (like when a pull request is merged).

Bitbucket app vendors use the Atlassian Connect framework to build the integrations and create extension points in the Bitbucket UI. Apps can also make calls to Bitbucket's REST API to send and retrieve data and other information from Bitbucket.

App security

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.

Installation permissions

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 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. 

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 Personal settings from your avatar in the bottom left and click the OAuth 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 account.

Install an app

1. Navigate to the proper workspace, if you are not already there. To find a particular workspace, click your profile avatar > click on the workspace listed under the Recent workspaces, or click All workspaces to display an entire list from which you can choose.

2. Select the Settings cog on the top navigation bar.

3. Select Workspace settings from the Settings dropdown menu.

4. Click Marketplace under Apps and features on the left side menu.

5. Pick an app you want and click Add.

6. 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

1. Navigate to the proper workspace, if you are not already there. To find a particular workspace, click your profile avatar > click on the workspace listed under the Recent workspaces, or click All workspaces to display an entire list from which you can choose.

2. Select the Settings cog on the top navigation bar.

3. Select Workspace settings from the Settings dropdown menu.

4. Select Installed apps in the Apps and features section.

5. Select the app you want to remove, then click Remove.

6. 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.

1. Navigate to the proper workspace, if you are not already there. To find a particular workspace, click your profile avatar > click on the workspace listed under the Recent workspaces, or click All workspaces to display an entire list from which you can choose.

2. Select the Settings cog on the top navigation bar.

3. Select Workspace settings from the Settings dropdown menu.

4. Select Installed apps in the Apps and features section.

5. Click Enable development mode. 

6. Click Install app from URL.

7. Copy the URL to the application you created.

8. Paste in the URL in the field in the Install app from URL dialog, then click Install.

Your app will appear along with the others on the Installed apps page.