Rate this page:
This changelog is the source of truth for all changes to the Bitbucket API and Bitbucket Connect API that affect people using Bitbucket Cloud and developing Bitbucket Cloud apps.
To ask any questions related to Bitbucket Cloud development please visit the Bitbucket Cloud developer community.
Bitbucket Pipelines operates in a Kubernetes-based infrastructure environment, and our internal execution environment leverages Containerd by default for all customers in a transparent manner.
A small number of users have been provisioned onto Docker based runtime infrastructure after a specific exemption was applied by Customer Support; it’s now time to retire that infrastructure.
A runtime change does not impact your ability to build containers using the Docker CLI, the primary impact is if you’re using out-of-date Docker tooling, or tooling that leverages deprecated Docker APIs
The Docker project has been committed to the Containerd project for a number of years Extending Docker’s Integration with containerd | Docker
Bitbucket Cloud now features Project and Workspace Access Tokens, which are similar to the recently released Repository Access Tokens, providing access to a single project or workspace and all the repositories under that resource. These tokens can be used to authenticate with Bitbucket APIs for scripting, CI/CD tools, Bitbucket Cloud-connected apps, and Bitbucket Cloud integrations.
Workspace admins can set a Project or Workspace Access Token’s access level through permission scopes during creation. Each token is linked to a project or workspace; preventing them from being used to access any repositories outside the specific project or workspace.
To start using Project Access Tokens, visit a Bitbucket Cloud project you have admin access to, and navigate to Project settings > Security > Access tokens. For Workspace Access Tokens, navigate to the Workspace view, then select Settings > Security > Access tokens.
For details, see:
Project Access Tokens (Bitbucket Cloud documentation)
Workspace Access Tokens (Bitbucket Cloud documentation)
On January 18, 2023, we'll be extending the length of API tokens for Atlassian accounts, API keys, and Repository Access Tokens. This ensures new tokens and keys generated after this date are more secure and reliable. Tokens and keys created before January 18, 2023 won’t be affected.
We’ve discontinued support for personal Connect apps in Bitbucket. Please see the deprecation notice for more details.
Bitbucket Cloud now features Repository Access Tokens, a new form of authentication that provides access to a single repository. These tokens can be used to authenticate with Bitbucket APIs for scripting, CI/CD tools, Bitbucket Cloud-connected apps, and Bitbucket Cloud integrations.
Repository admins can set a Repository Access Token’s access level through permission scopes during creation. Each token is linked to its repository, not a user or workspace; this prevents them from being used to access any other repositories or workspaces.
To start using Repository Access Tokens, select Repository Settings > Security > Access Tokens on your repository.
For more information, see:
https://developer.atlassian.com/cloud/bitbucket/rest/intro/#repository-access-tokens
Repository Access Tokens (Bitbucket Cloud documentation)
To support the development of a new feature, we're introducing a new subtype of the Account
definition called App User
into the Bitbucket Cloud API. After a 6-month deprecation period, ending on Feb 9, 2023, any API which documents an Account
type can start returning App User
objects, along with the currently expected Team
and User
objects.
Read more about the impact of the changes here: https://developer.atlassian.com/cloud/bitbucket/announcement-introducing-app-user/
Bitbucket is deprecating support for Personal Connect apps on January 1, 2023. This is an uncommon type of Connect app that installs into a user’s personal account rather than the workspace.
Below you can find more information about this change, as well as steps to update your app.
Personal Connect apps are a type of Bitbucket Connect app that is installed into the user’s personal account - as opposed to the typical Connect app that is installed into a Bitbucket workspace. As such, Personal Connect apps ‘follow’ users around as they navigate content across different workspaces.
From January 1, 2023, Bitbucket will no longer support Personal Connect apps. Their installation will be blocked. Soon after, Personal Connect apps will be removed from users' accounts. After this, the only valid Bitbucket Connect context type will be “account”.
This is part of an ongoing effort to give workspace admins more control over which integrations can access their data. Additionally, simplifying our Connect framework will help us create and roll out new features to customers faster.
If you're an app developer that maintains a personal Connect app, we suggest converting your app into a workspace Connect app. This will effectively reduce the reach of your app to the workspace of the user, rather than any workspace that the user can access.
In order to do this, you will need to update your Connect descriptor to change its "contexts"
attribute from ["personal"]
to ["account"]
. This change will then be applied to new installations of your app.
To apply this change to existing installations you have 2 options:
Your users can apply the change manually, if they update your app through the “Installed Apps” section under workspace settings.
Alternatively, you can apply this change to all of your existing installations by updating each installation through the REST API. You can find more info at https://developer.atlassian.com/cloud/bitbucket/rest/api-group-addon/#api-addon-put.
As a user, check if any of your installed apps are “personal” apps by navigating to your workspace settings > Apps and Features > Installed Apps. For each app you can see the installation context (personal
or workspace
).
You can also contact your app vendor to learn more about the recommended upgrade path.
The previously announced change to the format of App Passwords has been fully rolled out.
We recently launched a new developer support page, which serves as a centralized hub for reporting issues, managing your app and getting support. This page will streamline your experience of getting in contact with us for different areas of support:
Bugs: Report development or Marketplace bugs
Incidents: Report critical issues or breaking changes
App listing: Edit your app or access Marketplace APIs
Accounts and payment: Manage your Marketplace payments and licenses
App migration: Get help with creating a cloud version of your app
Security programs: Apply or adjust your program details
Partner resources: Request access to exclusive partner content
Ukraine support: Request emergency concessions or ask questions
If you have any questions, please get in touch with us via the developer community announcement.
On Jul 12, 2022, Bitbucket will be changing the format of newly created app passwords. As part of this, the length of app passswords will change from 20 to 36 characters.
To improve the overall security of app passwords, we want to improve our capabilities to scan for any leaked tokens. Changing the format lets us accomplish this at a greater scale.
This should have no impact on most scripts and integrations. However, you may need to update your storage to accommodate for this. For example, you may need to update the character size of a database column, in case you’re persisting these tokens in a database, like Postgres.
If you’re impacted by this in any way, we suggest that you allow for tokens with a length of 100 characters. This should cover any potential future changes as well.
Note that this will only affect newly created app passwords. Existing app passwords will remain unchanged.
Beginning 15 May 2023, we are removing the project:write
scope from the Bitbucket Cloud API.
We have released a new scope, project:admin
, which means the project:write
scope is now obsolete.
All integrations currently using the project:write
scope to call the Project endpoints (listed here) need to start using the project:admin
scope.
All integrations currently using the project:write
scope to call the Repository endpoints (listed here) or Git LFS need to start using the repository
scope.
We are changing the type of diff that is returned in the Bitbucket Cloud API from a ‘3-way’ diff to Git’s ‘three-dot’ diff. This new diff reflects the difference between the tip of a source branch and the commit from which it branched off of the destination. Read more about the new ‘three-dot’ diff here.
As a part of this change we are deprecating the merge
query parameter in the diff
and diffstat
API endpoints. It is being replaced with a new query parameter topic
, an optional boolean where true
returns the new 'three-dot' diff and false
returns a simple two-dot
diff.
For the next six months, requests to the diff APIs with neither the merge
nor topic
parameter provided will continue to return a '3-way' diff. After this period, the merge
parameter will be removed entirely and requests without a topic
parameter will return a 'three-dot' diff.
An improvement will be made in the coming days to allow customers (site admins) to turn off (or back on) end-user installation capabilities for OAuth 2.0 (3LO) apps. If you are a developer of OAuth 2.0 (3LO) apps, you do not need to take any action as a result of this change, as this message is only to communicate the impact to the customer.
Previously, controls were not in place for an admin to block their users from installing 3LO apps. Adding the ability for an admin to prohibit users from installing 3LO apps now aligns more closely to how a user would install any other, non-3LO apps on the Marketplace. This functionality was requested by several Atlassian enterprise customers to gain increased control over where their data is shared and which apps have access to their instance. By allowing admins to control end-user app installs, we are making it possible for more enterprise customers to move to cloud. Once in cloud, these companies will not be blocked from installing 3LO apps, because admins will retain the ability to vet and install the apps at their discretion.
Figure (a) below demonstrates the section of the customer’s admin console where they will now be able to block their users from installing 3LO apps. Figure (b) below shows the new experience when a customer tries to install a 3LO app after their admin has disabled this function.
If a customer attempts to install a 3LO app after their admin has disabled this function, the following error message will appear:
App is blocked by an admin
An admin has not allowed [App Name]
to access data from [Your Atlassian Instance]
. Select another site to authorize access to or contact your admin for more information.
(a)
(b)
As previously announced in the Bitbucket blog, beginning 1 March 2022, Bitbucket users will not be able to use their Atlassian account passwords for API and Git activity.
Additionally, we've recently announced that new users with Atlassian accounts created on or after 13 September 2021 will not be able to use their account passwords for these Bitbucket activities.
Read more here.