Bitbucket Cloud Version Control

This guide describes how to set up version control for notebooks using Bitbucket Cloud.

Using the Databricks CLI and Workspace API

Although this document describes how to set up Bitbucket Cloud integration through the UI, we recommend that you integrate with Git through the Databricks CLI and Workspace API. It is a more powerful tool.

Getting an App Password

Go to Bitbucket Cloud and create an app password that allows access to your repositories. See the Bitbucket Cloud documentation.

Saving Your App Password and Username to Databricks

You can save your Bitbucket Cloud username and app password through the Account Settings page. Click the User icon on the top right of your screen and select Account Settings.

  1. Go to the “Git Integration” section.

  2. If you have previously entered credentials, click the “Change token or app password” button.

  3. Paste your username and app password into the username and password fields, and click Save.


Linking a Notebook to Bitbucket Cloud

In order to link your notebook to a file on Bitbucket Cloud, open the History Panel by clicking Revision History. The Git status bar should display Git: Not linked.


You cannot modify a notebook while the Revision history tab is open. Once you click the Git: Not linked text, you should see the notebook’s Git Preferences. The first time you open your notebook the option displayed will be Unlink, because the notebook is not on Bitbucket Cloud.

Select Link, and you should be able to edit the text inputs.
  • Copy the URL of the Bitbucket Cloud repository in the input area labelled as Link.
  • The path in the second text box determines where in the repository you would like to store your file.
  • Python notebooks will have the suggested default file extension .py. If you use .ipynb, your notebook will save in iPython notebook format.
  • If the file already exists on Bitbucket Cloud, you can directly copy and paste the URL of the file.
  • Click Save to finish linking your notebook.
  • A prompt will appear with the option “Save this file to your Bitbucket Cloud repo” if this file did not previously exist.

Save a Notebook to Bitbucket Cloud

While the changes that you make to your notebook are saved automatically to the history list, changes do not automatically persist to Bitbucket Cloud.

  • Click Save Now to save your notebook to Bitbucket Cloud.
  • Optionally, enter a message to describe your change.
  • Make sure that Also Commit to Git is selected.


Revert/Update a Notebook to a version from Git

Once you link a notebook, we will sync your history with Git every time you re-open the history panel.


Versions that sync to Git will have the commit hashes as part of the entry. Click Restore this version to view old/new versions of your notebook from Git.

Branch Support

You can work on an arbitrary branch of your repository with Databricks.

Listing Branches


Best Practice for Code Reviews

Databricks supports git branching.

  • You can link a notebook to your own fork and choose a branch.
  • We recommend using separate branches for each notebook.
  • Once you are happy with your changes, you can use the Create PR link in the Git Preferences dialog to take you to Bitbucket Cloud’s Pull Request page.
  • The Create PR link displays only if you’re not working on the default branch of the parent repository.

Bitbucket Server


Bitbucket Server integration is not yet supported.


If you receive errors related to Bitbucket Cloud history sync, verify the following:

  1. You have initialized the repository on Bitbucket Cloud, and it isn’t empty. Try the URL that you entered and verify that it forwards to your Bitbucket Cloud repository.
  2. Your app password is active and your username is correct.
  3. If the repository is private, you should have read and write access (through Bitbucket Cloud) on the repository.