Share via

Version control dashboards with Git

This page explains how to use Databricks Git folders for version control and collaborative dashboard development. It also describes how to implement CI/CD processes to develop and deploy dashboards across different workspaces.

Important

This feature is in Public Preview.

Overview

Databricks Git folders track dashboard changes and history, support team collaboration, and allow you to deploy dashboards to production and recover previous versions.

Enable dashboard source control

Workspace admins can control workspace access to the Public Preview from the Previews page. By default, the Support Dashboards in Git folder preview is On.

How Git integration works with dashboards

Databricks Git folders track and manage changes to draft dashboards. The dashboard draft reflects all changes in a tracked dashboard. Git doesn't track publishing and scheduling configurations, such as warehouse selection and schedule creation. To manage these configurations, use the UI or automate changes with Databricks Asset Bundles or the AI/BI REST API.

  • To use bundles for dashboard management, see dashboard.
  • To publish and schedule dashboards with the REST API, see the Lakeview API reference.

Note

The Lakeview API uses the previous name for AI/BI dashboards.

Databricks Git folders manage common Git operations for dashboards and other workspace objects. To learn more, see What is Databricks Git folders.

Applying source control to dashboards

To track dashboards with Git, place them in a Databricks Git folder. Use one of the following options:

  • New dashboards: Create your dashboard within an existing Databricks Git folder to apply source control from the start.
  • Existing dashboards: Move an existing dashboard into a Databricks Git folder to track it with Git.

Managing permissions for source-controlled dashboards

Folder-level permissions apply to all objects within that folder, including dashboards. Dashboards in a Git folder inherit the parent folder's permissions in addition to any dashboard-specific permissions. Most Git operations require the CAN MANAGE permission. To learn more, see Folder ACLs and Git folder ACLs.

Clone the repository into your own Databricks Git folder, use feature branches, and submit pull requests. The following table outlines how to use Git folders to manage dashboards during different phases of development and deployment.

Important

Switching Git branches is a destructive operation for dashboards. Azure Databricks removes dashboards that don't exist on the target branch. If you switch back, dashboards reappear with new URLs and IDs, which breaks published links, bookmarks, and API integrations. Verify the target branch before switching and update all references afterward.

Project phase Workflow Expected outcome Known limitations
Initial commit
  • Move the dashboard into a Git folder in the workspace.
  • Commit and push to the remote Git repository.
 Git tracks the dashboard in a remote repository.
Development
  • Developers create Git folders on separate dev branches, typically in their home folders.
  • Commit changes to the development branch.
  • Merge development branches to main using pull requests.
  • Developers work independently.
  • Git tracks dashboard versions.
 Dashboard files use JSON format. SQL queries appear as a single line, which can make diffs hard to review in pull requests.
Deployment
  • Create a Git folder on the deployment branch in a non-user top-level folder. See CI/CD with Databricks Git folders (Repos).
  • Pull changes into the deployment folder.
  • Publish dashboards from this folder.
  • Remove edit+ access and restrict updates to Git.
  • Share dashboards with consumers.
  • Consumers access a consistent, published version of the dashboard.
  • You can share dashboards in the same folder with different audiences.
 Databricks doesn't provide built-in support for syncing a remote branch with a Git folder in the workspace, or deploying Databricks Asset Bundles with a dashboard resource from remote. Set up CI/CD automation to automate:
  • Pulling updates from the remote repository.
  • Publishing dashboards after sync.
  • Deploying Databricks Asset Bundles after an update.

For more best practices on collaboration in Databricks Git folders, see Collaborate using Git folders.

Limitations

Source control with AI/BI dashboards has the following limitations:

  • You can commit a maximum of 100 dashboards in a single Git folder. This limit might change during the Public Preview.
  • Git-based jobs, such as jobs referencing Git URLs instead of workspace asset IDs or paths, don't work with dashboards.
  • Dashboard serialization generates long strings, which makes reading and reviewing differences during pull requests difficult.
  • The dashboard file format changes periodically to include new fields and other improvements. During the Public Preview, these changes might appear as differences in Git that you did not initiate.