Git Sync: version dashboards in GitHub

1. What is Git Sync? #

The principle and what it changes.

The principle #

Available in: ✓ OSS ✓ Enterprise ✓ Cloud Experimental in Grafana 12, generally available from Grafana 13

Git Sync connects Grafana to a Git repository (GitHub): the dashboards and folders of a Grafana folder, or of the whole instance, are stored as JSON files in a branch and path of the repository. Both sides stay in sync: a change saved in Grafana becomes a commit (or a pull request), and a commit pushed to the repository updates Grafana.

It is the built-in « observability as code » building block: teams keep building dashboards visually, while history, review and rollback go through Git.

Git Sync or file provisioning? #

Good to know: classic provisioning (previous lesson) remains the right choice for data sources or locked, non-editable dashboards; Git Sync suits dashboards that teams keep improving.

2. Setup #

Prerequisites, token and repository connection.

Prerequisites #

• Grafana 12 (experimental feature) or Grafana 13 and later; on Grafana Cloud, the feature is offered in the stack.
• Self-managed Grafana 12: enable the provisioning and kubernetesDashboards feature toggles.
• A dedicated GitHub repository (or a dedicated folder in a repository) and the administrator role in Grafana.
• For immediate sync, a public Grafana URL reachable by GitHub webhooks; otherwise Grafana polls the repository at a regular interval.

# grafana.ini (self-managed Grafana 12)
[feature_toggles]
provisioning = true
kubernetesDashboards = true

docker run -d --name grafana -p 3000:3000 \
  -e GF_FEATURE_TOGGLES_ENABLE=provisioning,kubernetesDashboards \
  grafana/grafana:latest

The GitHub token #

Create a fine-grained personal access token scoped to the repository, with these permissions: Contents (read and write), Metadata (read), Pull requests (read and write) and Webhooks (read and write). Give it an expiry date and track it: when it expires, syncing stops.

Common mistake: using a classic token that covers all your repositories. Always scope the token to the synced repository only.

Connect the repository #

1. Open Administration › Provisioning (depending on the version: Administration › General › Provisioning) then Configure Git Sync.
2. Paste the token, the repository URL, the branch (for example main) and the files path (default grafana/).
3. Choose the target: a Grafana folder (recommended to start) or the whole instance.
4. Choose whether existing dashboards are exported to the repository during the first sync.
5. Set the sync method: webhook (immediate) and/or polling interval, then save.

3. Day-to-day work #

Save, review, roll back.

Saving a dashboard #

A synced dashboard carries the Provisioned label. When saving, Grafana offers to write directly to the configured branch or to create a new branch and open a pull request. With a pull request, the dashboard is only updated in Grafana once the branch is merged.

grafana/
├── web-team/
│   ├── service-overview.json
│   └── api-latency.json
└── infra/
    └── kubernetes-nodes.json

Each repository folder maps to a Grafana folder; each JSON file is a dashboard.

Editing from Git #

A commit on the branch (editing the JSON, renaming, deleting) is applied to Grafana on the next webhook or poll. Deleting a file deletes the dashboard. To roll back, simply revert the commit (git revert).

git pull
# fix a threshold in the JSON
git commit -am "api-latency: alert threshold at 300 ms"
git push
# go back to the previous version
git revert HEAD && git push

4. Limits and best practices #

Avoiding bad surprises.

Limits #

• Synced resources are dashboards and folders; alerts, data sources and users belong to other tools (provisioning, Terraform, API).
• GitHub is the supported provider; check GitHub Enterprise and other forges support in your version's documentation.
• In Grafana 12 the feature is experimental: unsupported and subject to change.
• A synced dashboard must not also be managed by file provisioning or by Terraform.

Best practices #

• Start with a pilot folder rather than the whole instance.
• Protect the main branch and require pull requests for critical folders.
• Add a CI check (valid JSON, no duplicate UIDs).
• Use a dedicated service account or token, with scheduled rotation.
• Document in the repository README which Grafana folder maps to which Git folder.

Good practice: keep dashboard UIDs stable: they are the key between Grafana and the repository, and links between dashboards depend on them.