This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation As code Observability as code Git Sync

Introduction to Git Sync

Git Sync in Grafana lets you manage your dashboards as code as JSON files stored in GitHub. You and your team can version control, collaborate, and automate deployments efficiently.

How it works

Git Sync is bidirectional and works both with changes done directly in GitHub as well as in the Grafana UI.

• When you provision resources with Git Sync you can modify them from within the Grafana UI or within the GitHub repository. Changes made in either the repository or the Grafana UI are bidirectional.
• Any changes made in the provisioned files stored in the GitHub repository are reflected in the Grafana database. By default, Grafana polls GitHub every 60 seconds. The Grafana UI reads from the database and updates the UI to reflect these changes.

Provisioning folder

Git Sync creates a folder for all the synchronized resources to live under. You can continue to have unprovisioned resources outside that folder.

Make changes in Grafana

Whenever you modify a dashboard directly from the UI, Grafana can commit changes to Git upon saving. You can configure settings to either enforce PR approvals before merging in your repository, or allow direct commits.

Grafana periodically polls GitHub at a regular internal to synchronize any changes. The default polling interval is 60 seconds, and you can change this setting in the Grafana UI.

• If you enable the webhooks feature, repository notifications appear almost immediately.
• Without webhooks, Grafana polls for changes at the specified interval.

Make changes in your GitHub repositories

With Git Sync, you can make changes to the files in the provisioned folder in GitHub and see them in Grafana. Automated workflows ensure those changes are automatically represented in the Grafana database by updating Git. The Grafana UI reads the database and updates the UI to reflect these changes.

Known limitations

Git Sync is under development and the following limitations apply.

Synced resources

• You can only sync dashboards and folders. Refer to Supported resources for more information.
• If you’re using Git Sync in Grafana OSS and Grafana Enterprise, some resources might be in an incompatible data format and won’t be synced.
• Full-instance sync is not available in Grafana Cloud and is experimental in Grafana OSS and Grafana Enterprise. Refer to Choose what to synchronize for more details.
• When migrating to full instance sync, during the synchronization process your resources will be temporarily unavailable. No one will be able to create, edit, or delete resources during this process.
• If you want to manage existing resources with Git Sync, you need to save them as JSON files and commit them to the synced repository. Open a PR to import, copy, move, or save a dashboard.
• Restoring resources from the UI is currently not possible. As an alternative, you can restore dashboards directly in your GitHub repository by raising a PR, and they will be updated in Grafana.

Authentication

• You can only authenticate in GitHub using your Personal Access Token token.

Permission management

• You cannot modify the permissions of a provisioned folder after you’ve synced it.
• Default permissions are: Admin = Admin, Editor = Editor, and Viewer = Viewer. Refer to Roles and permissions for more information.

Compatibility

• Support for native Git, Git app, and other providers, such as GitLab or Bitbucket, is on the roadmap.

Supported resources

Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet.

If you’re using Git Sync in Grafana OSS or Grafana Enterprise, some supported resources might be in an incompatible data format. If this happens, syncing will be blocked. Compatibility issues will be fixed with an upcoming migration tool.

Resource states

A resource can be:

Git Sync instance states

An instance can be in one of the following Git Sync states:

• Unprovisioned: None of the instance’s resources are being managed by Git Sync.
• Partially provisioned: Some of the resources are controlled by Git Sync.
• Fully provisioned: All supported resource types are managed by Git Sync. Note that unsupported resources are not managed.

Common use cases

You can use Git Sync for the following use cases:

Version control and auditing

Organizations can maintain a structured, version-controlled history of Grafana dashboards. The version control lets you revert to previous versions when necessary, compare modifications across commits, and ensure transparency in dashboard management.

Additionally, having a detailed history of changes enhances compliance efforts, as teams can generate audit logs that document who made changes, when they were made, and why.

Automated deployment and CI/CD integration

Teams can streamline their workflow by integrating dashboard updates into their CI/CD pipelines. By pushing changes to GitHub, automated processes can trigger validation checks, test dashboard configurations, and deploy updates programmatically using the grafanactl CLI and Foundation SDK.

This reduces the risk of human errors, ensures consistency across environments, and enables a faster, more reliable release cycle for dashboards used in production monitoring and analytics.

Collaborative dashboard development

With Git Sync, multiple users can work on dashboards simultaneously without overwriting each other’s modifications. By leveraging pull requests and branch-based workflows, teams can submit changes for review before merging them into the main branch. This process not only improves quality control but also ensures that dashboards adhere to best practices and organizational standards.

Additionally, GitHub’s built-in discussion and review tools facilitate effective collaboration, making it easier to address feedback before changes go live.

Multi-environment synchronization

Enterprises managing multiple Grafana instances, such as development, staging, and production environments, can seamlessly sync dashboards across these instances. This ensures consistency in visualization and monitoring configurations, reducing discrepancies that might arise from manually managing dashboards in different environments.

By using Git Sync, teams can automate deployments across environments, eliminating repetitive setup tasks and maintaining a standardized monitoring infrastructure across the organization.

Disaster recovery and backup

By continuously syncing dashboards to GitHub, organizations can create an always-updated backup, ensuring dashboards are never lost due to accidental deletion or system failures.

If an issue arises, such as a corrupted dashboard, unintended modification, or a system crash, teams can quickly restore the latest functional version from the Git repository. This not only minimizes downtime but also adds a layer of resilience to Grafana monitoring setups, ensuring critical dashboards remain available when needed.

Build dashboards as code

Because dashboards are defined in JSON files, you can enable as-code workflows where the JSON file is an output from Go, TypeScript, or another coding language in the format of a dashboard schema.

To learn more about creating dashboards in a coding language to provision them for Git Sync, refer to the Foundation SDK documentation.

Explore Git Sync

• Set up Git Sync
  Instructions for setting up Git Sync, so you can provision GitHub repositories for use with Grafana.
• Add non-provisioned resources from Grafana
  Export non-provisioned resources from Grafana.
• Work with provisioned dashboards
  Update, save, and modify provisioned resources in Grafana using Git Sync.
• Manage provisioned repositories with Git Sync
  Instructions for working with Git Sync to perform common tasks, such as saving dashboards to GitHub and synchronizing changes with Grafana.
• Git Sync deployment scenarios
  Learn about common Git Sync deployment patterns and configurations for different organizational needs
  • Single instance Git Sync
    Synchronize a single Grafana instance with a Git repository
  • Git Sync for development and production environments
    Use separate Grafana instances for development and production with Git-controlled promotion
  • Git Sync with regional replication
    Synchronize multiple regional Grafana instances from a shared Git location
  • Git Sync for high availability environments
    Run multiple Grafana instances serving traffic simultaneously, synchronized via Git Sync
  • Multiple team Git Sync
    Use multiple Git repositories with one Grafana instance, one repository per team