Last updated Jul 25, 2024

Integrating with Bitbucket Cloud

Bitbucket Cloud can be customized and extended by creating apps. Apps can:

  • integrate with an external service,
  • add new features,
  • update settings and
  • retrieve information from Bitbucket.

Options for integrating with Bitbucket Cloud

You have four main options for integrating with Bitbucket Cloud:

  1. Build a Bitbucket app on Forge, our recommended platform for building secure, reliable, and scalable apps.
  2. Call the REST API via scripts or other API clients to automate operations in Bitbucket Cloud not otherwise available through the user interface.
  3. Develop an Atlassian Connect app that integrates in the Bitbucket Cloud UI to add contextual information or functions.
  4. Develop a pipe for Bitbucket Pipelines that can integrate with an external system to deploy code, scan your code, call other services or implement other functionality.

Forge apps

Forge is our recommended platform for building apps. It’s designed to revolutionize how Atlassian cloud products are customized, extended, and integrated.

To start building a Bitbucket app with Forge, see:

Connect apps

Before you build with Connect, consider Forge

We recommend Forge for building Atlassian cloud apps. Forge lets you host apps on infrastructure that is provisioned, managed, monitored, and scaled automatically by Atlassian.

Get started with Forge

Atlassian Connect is a framework for building apps for Jira, Confluence, and Bitbucket Cloud. It remains an option for developers who want complete control over the tech stack and infrastructure, for example, projects that require complex storage or compute hosting.

To start building a Bitbucket app with Connect, see:

Building apps without Forge or Connect

Apps built without Forge or Connect can still access data and create content through the Bitbucket APIs. These apps can use OAuth 2.0 (3LO) or basic auth to pass information between your app and Bitbucket, depending on your security needs. See the Security section below for more details.

Note that Forge and Connect are required to implement certain functionality in apps. For example, only Forge and Connect apps can extend the user interface of products.

Using the APIs

You can use the Bitbucket APIs in Bitbucket apps, as well as in scripts, API clients, or other methods of making calls.

  • REST API allows you to access and update Bitbucket entities, such as commits and pull requests.
  • Forge JavaScript API provides additional functionality to the Forge platform so that you can interact with REST endpoints and to store data.
  • Connect JavaScript API lets you use iframes with your Connect app, so that your iframe can call APIs, store cookies, access user info, and more.

Atlassian development guidelines

Follow our design guidelines to make your app consistent with Atlassian's products.

Atlassian Design guidelines

Since Forge and Connect apps can insert content directly into the user interface, it's important that apps are visually compatible with Atlassian design.

Security

There are a few basic options for security, depending on what sort of app you are trying to make:

  • Forge apps use OAuth 2.0 when authenticating with Bitbucket. Scopes are an OAuth 2.0 mechanism that limits an app's access to a user's account. The Forge platform also provides managed APIs to make requests on behalf of the user, meaning that third-party code is never trusted with user credentials.
  • Connect apps have HTTPS and JWT authentication built in to secure communication between your app, Bitbucket, and the user. Our Connect toolkits, Atlassian Connect Express (ACE) and Atlassian Connect for Spring Boot, handle most of the security setup for new apps.
  • OAuth 2.0 (3LO) apps use OAuth 2.0 (3LO) to pass permissions and data from Bitbucket.
  • Basic auth is supported for making API calls via App Passwords and Access Tokens.

For more details, see Security overview.

Atlassian Marketplace (for Connect apps only)

You can publish your Bitbucket Connect app on the Atlassian Marketplace so other cloud users can install it, or list it privately if you don't intend to distribute your code. Private listings use secret tokens that you can generate yourself.

Examples and resources

Check out our example apps and patterns for app ideas and strategies, or see some tutorials on more advanced topics:

Rate this page: