Source control dashboards

This article explains how to use Databricks Git folders for version control and collaborative dashboard development. It also provides guidance on implementing CI/CD processes to develop and deploy dashboards across different workspaces.

Preview

This feature is in Public Preview.

Overview

Using Databricks Git folders for dashboards provides better visibility into changes and history, making collaboration more efficient. It also simplifies deploying dashboards to production and enables you to recover previous versions, serving as a reliable backup solution.

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

You can use Databricks Git folders to track and manage changes to draft dashboards. All changes in a tracked dashboard are reflected in the dashboard draft. Publishing and scheduling configurations, such as warehouse selection and schedule creation, are not tracked. To manage these configurations, use the UI or automate changes using Databricks Asset Bundles or the AI/BI REST API. See dashboard and the Lakeview REST API reference.

note

AI/BI dashboards were previously known as Lakeview dashboards. The Lakeview API retains that name.

• To learn more about using bundles for dashboard management, see dashboard.
• For details about publishing and scheduling dashboards via the REST API, see the Lakeview API reference.

Databricks Git folders provide a centralized way to manage common Git operations for dashboards and other workspace objects. To learn more, see Git integration for 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

As with other workspace objects, permissions set at the folder level apply to all objects within that folder. Dashboards in a Git folder inherit the parent folder’s permissions in addition to any dashboard-specific permissions. Users must have CAN_MANAGE permission to perform most Git operations. To learn more, see Folder ACLs and Git folder ACLs.

Recommended development workflow

Users should clone the repository into their own Databricks Git folder, use feature branches, and submit pull requests. The following table outlines suggestions for using Git folders to manage dashboards during different phases of development and deployment.

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.	The dashboard is now source controlled in a remote Git 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 can work independently. Dashboards are version controlled.	Dashboard files are in 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 techniques with Git and 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. Dashboards in the same folder can be shared with different audiences.	No 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 in Git folders.

Limitations

Consider the following limitations when using source control with AI/BI dashboards:

• A maximum of 100 dashboards can be committed in a single Git folder. This limit might be modified during the Public Preview period.
• Git-based jobs, such as jobs referencing Git URLs instead of workspace asset IDs or paths, are not supported.
• Dashboard serialization generates long strings, making 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 period, these changes might appear as differences in Git that are unrelated to user-initiated edits.