Bitbucket

Configuration settings for backing up repositories from Bitbucket.

Warning

Known limitations:

• Issues are not backed up

• SCM Backup supports Bitbucket Cloud (see Hosting Options) only, the self-hosted options are not supported!

  ⇒ see Why doesn’t SCM Backup support backing up local installations of [hoster X]?

Sources

For the basics, please read the Sources section first.

For Bitbucket, the hoster entry in the config file needs to look like this:

hoster: bitbucket

SCM Backup will always backup a Bitbucket Workspace.

Bitbucket repository URLs look like this: https://bitbucket.org/WORKSPACEID/REPO/…so the URL part directly behind https://bitbucket.org is the workspace ID.

(The distinction between “users” and “organizations” - which most other hosters have, and which Bitbucket also had before they introduced workspaces - doesn’t really exist anymore)

• To backup the repos of any workspace, the name entry in the config needs to be set to the workspace ID

• If the workspace is the user’s “personal” workspace (workspace name is equal to username), set the type in the config to user. For any other workspace, set the type to org. [1]

Authentication

Without authentication, SCM Backup can only backup your public repositories.

In this case, it shows a warning:

To backup your private repositories as well, you need to authenticate with a user who has sufficient permissions to the workspace’s repositories.

Warning

In the past, Bitbucket used app passwords for this. App passwords are now replaced by API tokens and all existing app passwords will be disabled June 9, 2026 (source: 1, 2).

If you’re currently using app passwords to authenticate SCM Backup, you must replace them by API tokens before June 9, 2026.

Create an API token for SCM Backup for that user:

1. Login with your Atlassian ID, go to the API tokens page and follow these steps to create a new API token with scopes.

   (important: there are two options to create a token either with or without scopes, and you need one with scopes!)

2. Select Bitbucket as the app, and give the token at least the following permissions:

   • read:repository:bitbucket

   • read:wiki:bitbucket

3. Put your Bitbucket username, email address, and the API token into the authName, apiAuthName and password properties of the source in the config file.

   Note

   By default, a user’s workspace ID is equal to the user name, but it’s possible to change the workspace ID, so workspace ID and user name don’t match anymore.

   In this case, you need to set name to the workspace ID and authName to the user name.

   Example:

   sources:
   
     - title: some_title
       hoster: bitbucket
       type: org
       name: your_workspace
       authName: your_user_name
       apiAuthName: your_bitbucket_email@example.com
       password: your_api_token
   

   This will backup the repositories of the workspace your_workspace, but authenticate with:

   • the email address your_bitbucket_email@example.com and the API token (for calling the Bitbucket API)

   • the user your_user_name and the API token (for Git commands)

Footnotes

[1]

For what SCM Backup does, there’s no difference between users and workspaces. The actual backup will work with both types.

However, not all validations are done for both types, and if you set the wrong type, you may see misleading warning messages (example).