Trying Out Grafana's Git Sync Feature (OSS Edition)

This post is Day 11 of the Grafana Advent Calendar 2025.

Have you ever experienced any of these while using Grafana?

• “The dashboard was working yesterday… did someone change it?”
• “I want to revert it, but I don’t know what was changed…”
• “The dashboards in production and staging environments have drifted apart”

Until now, Grafana didn’t have a native feature to sync dashboards with Git. As a result, managing dashboards required workarounds like exporting to JSON and managing in Git, using external tools like Terraform or Grizzly (now deprecated), or writing custom scripts via the API—all of which were quite cumbersome.

That’s why the introduction of the Git Sync feature in Grafana 12 is such a big deal.

What is Git Sync?

Git Sync is a feature that enables bidirectional synchronization between Grafana dashboards and a GitHub repository. Dashboards are stored in JSON format in the repository and can be version controlled just like regular code.

The main capabilities are:

1. Git-based Management - Track dashboard change history and revert to previous states anytime
2. PR-based Review - Review changes via pull requests before merging
3. Multi-environment Deployment - Deploy the same dashboards across multiple Grafana instances

By default, synchronization occurs every 60 seconds via polling, but with Webhooks configured, you can achieve near real-time sync.

Current Status

As of December 2025, Git Sync is available as an Experimental feature in Grafana OSS/Enterprise.

To use it, you need to meet the following requirements:

• Grafana v12 or later
• Feature Toggles enabled

⚠️ Note: This is still an experimental feature. It is not recommended for production use. We suggest trying it in a staging environment first.

Setup Instructions

Let’s walk through the detailed steps to set up Git Sync.

Here’s the overall flow:

Prerequisites

• Docker installed
• Grafana v12 or later Docker image
• GitHub repository (to store your dashboards)

1. Enable Feature Toggles

To use Git Sync, you need to enable Feature Toggles.

Create a grafana.ini file with the following content:

[feature_toggles]
provisioning = true
kubernetesDashboards = true

Mount this file to the container and start Grafana:

docker run -d \
  --name grafana \
  -p 3000:3000 \
  -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini \
  grafana/grafana:nightly

If you have an existing container, restart it:

docker restart grafana

2. Create GitHub Access Token

Create a Personal Access Token (PAT) for Git Sync to access the GitHub repository.

Step 1: Create a Token on GitHub

Open the GitHub Fine-grained Personal Access Token page.

Step 2: Configure the Token

Set up the token as follows:

• Token name: A descriptive name (e.g., grafana-git-sync)
• Expiration: Choose an appropriate expiration period
• Repository access: Select the target repository

Step 3: Set Permissions

Expand “Repository permissions” and configure the following:

Step 4: Generate and Copy the Token

Click “Generate token” and copy the displayed token.

⚠️ Important: The token is only displayed once. Make sure to copy it and store it in a secure location.

3. Configure Repository Connection

Connect to the GitHub repository from the Grafana UI.

Step 1: Open the Provisioning Page

1. Log in to Grafana with an admin account
2. From the left menu, select Administration → General → Provisioning
3. Click Configure with GitHub

Step 2: Enter Connection Information

Enter the following information:

Path can be any directory you choose. In this example, we’re using the dashboards directory.

After entering the information, click “Choose what to synchronize” to proceed.

4. Choose Content to Sync

Select the synchronization method. There are two options:

Option A: Sync All Resources (Full Instance Sync)

Sync all resources with external storage

• Syncs all dashboards from the entire Grafana instance with the repository
• Only one repository connection can be configured
• Blocked if existing alerts or library panels exist

Option B: Sync by Folder (Folder Sync)

Sync external storage to new Grafana folder

• Syncs repository contents to a specified folder
• Up to 10 repository connections can be configured
• Does not affect existing dashboards

For first-time users, Option B (Folder Sync) is recommended. It has less impact on your existing environment and is safer to experiment with.

Enter a Display name and click “Choose additional settings”.

Since there’s no content to sync in this example, “3. Synchronize with external storage” is skipped. If you have existing dashboards, the sync process will be executed here.

In my environment, the browser crashed during the sync process. The cause is still under investigation, so this step is omitted from this guide.

5. Additional Settings

Finally, you can customize the sync behavior:

Click “Finish” to complete the setup!

Verify Setup

After completing the setup, verify the following:

1. Open the Dashboards menu
2. Confirm that a folder with the configured Display name appears
3. If there are dashboard JSON files in the repository, confirm they have been imported

Dashboards synced via Git Sync will display an icon like the one shown below.

Practical Usage Examples

Let’s look at actual workflows after setting up Git Sync.

I’ve identified roughly three use cases.

Case 1: Edit Dashboard in Grafana UI → Reflect in GitHub

1. Edit the dashboard in Grafana UI
   • Edit the dashboard as usual
   • When saving, you can specify the filename, commit message, and target branch

2. Changes are automatically reflected in GitHub

   • After saving the dashboard, the repository is updated at the configured polling interval
   • Alternatively, use the “Save to GitHub” option for immediate commit

3. Verify changes in commit history

   • Check the commit history in the GitHub repository
     • You can confirm that the commit was made with the specified filename and commit message

Case 2: Edit Dashboard in GitHub → Reflect in Grafana

1. Edit the JSON file directly

   • Edit the dashboard JSON in the repository
     • In this example, I simply updated the dashboard name
   • After editing, commit and push to the repository

2. Grafana syncs automatically

   • After the polling interval, the dashboard is reflected in Grafana
     • When you check if the dashboard was updated, you can confirm that the changes have been incorporated
   • With Webhooks configured, updates occur in near real-time

Case 3: PR-based Review Workflow

With Generate Dashboard Previews enabled, you can review dashboards during PRs as follows:

The benefits of this approach are:

• Review dashboards before changes go live
• With Image Renderer configured, dashboard preview images are automatically attached to PRs
• Easy to revert if issues arise

I wanted to try this out, but it didn’t work properly in my environment, so it’s omitted from this guide.

Known Limitations

Since Git Sync is still an experimental feature, there are several limitations. Review these before implementation.

Syncable Resources

Currently, only the following resources can be synced:

Alerts and library panels are planned for future updates. (Personally, I’m eagerly hoping for alert support to be released soon…)

Other Limitations

• GitHub only: Currently, other platforms (GitLab, Bitbucket, etc.) are not supported
  • GitLab and Bitbucket are on the roadmap
• GitHub Apps not supported: Only Personal Access Tokens (PAT) can be used
• Provisioned folder permissions: Folder permissions cannot be changed after sync
• Full Instance Sync restrictions: Blocked if alerts or library panels exist

Performance Impact

According to the official documentation:

When Git Sync is enabled, the database load might increase, especially for instances with a lot of folders and nested folders. Evaluate the performance impact, if any, in a non-production environment.

The exact impact is unclear, so I plan to investigate this further.

Summary

Git Sync is one of the features that Grafana users have been waiting for, but it seems like there’s still a long road ahead before it’s fully released for OSS.

However, once it reaches GA, I believe it will significantly reduce the maintenance costs we’ve been dealing with, so stay tuned for future updates.

Pros

• Native Integration: Git management without external tools
• Bidirectional Sync: Both UI edits and Git edits work
• PR Workflow: Naturally incorporates review processes
• Easy Setup: Configure with just a few clicks in the GUI

Considerations

• Still an experimental feature (use caution in production)
• Only dashboards and folders supported (alerts not supported)
• GitHub only (GitLab, Bitbucket coming later)

Future Expectations

• Support for alerts and library panels
• Support for GitLab and Bitbucket
• GitHub Apps support

It’s still in the experimental stage, but if you’re interested, give it a try!

Finally

Stay tuned for tomorrow’s Grafana Advent Calendar 2025!

References

• Git Sync | Grafana Documentation
• Set up Git Sync | Grafana Documentation
• Grafana dashboards as code: How to manage your dashboards with Git | Grafana Labs Blog