Git Sync : versionner les dashboards dans GitHub

1. Qu'est-ce que Git Sync ? #

Le principe et ce qu'il change.

Le principe #

Disponible dans : ✓ OSS ✓ Enterprise ✓ Cloud Expérimental en Grafana 12, disponible en version stable à partir de Grafana 13

Git Sync relie Grafana à un dépôt Git (GitHub) : les dashboards et dossiers d'un dossier Grafana, ou de toute l'instance, sont stockés sous forme de fichiers JSON dans une branche et un chemin du dépôt. Les deux côtés restent synchronisés : une modification enregistrée dans Grafana devient un commit (ou une pull request), et un commit poussé dans le dépôt met à jour Grafana.

C'est la brique « observability as code » intégrée à l'interface : les équipes continuent de construire leurs dashboards visuellement, mais l'historique, la revue et le retour arrière passent par Git.

Git Sync ou provisioning par fichiers ? #

À savoir : le provisioning classique (leçon précédente) reste la bonne solution pour des sources de données ou des dashboards imposés et non modifiables ; Git Sync convient aux dashboards que les équipes font évoluer.

2. Mise en place #

Prérequis, jeton et connexion du dépôt.

Prérequis #

• Grafana 12 (fonction expérimentale) ou Grafana 13 et plus ; sur Grafana Cloud, la fonction est proposée dans la pile.
• En Grafana 12 auto-hébergé : activer les feature toggles provisioning et kubernetesDashboards.
• Un dépôt GitHub dédié (ou un dossier dédié dans un dépôt) et le rôle administrateur dans Grafana.
• Pour la synchronisation immédiate, une URL publique de Grafana joignable par les webhooks GitHub ; sinon Grafana interroge le dépôt à intervalle régulier.

# grafana.ini (Grafana 12 auto-hébergé)
[feature_toggles]
provisioning = true
kubernetesDashboards = true

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

Le jeton GitHub #

Créez un fine-grained personal access token limité au dépôt, avec les permissions : Contents (lecture et écriture), Metadata (lecture), Pull requests (lecture et écriture) et Webhooks (lecture et écriture). Donnez-lui une date d'expiration et notez-la : à son expiration, la synchronisation s'arrête.

Erreur courante : utiliser un jeton classique sur tous vos dépôts. Limitez toujours le jeton au seul dépôt synchronisé.

Connecter le dépôt #

1. Ouvrez Administration › Provisioning (selon la version : Administration › General › Provisioning) puis Configure Git Sync.
2. Collez le jeton, l'URL du dépôt, la branche (par exemple main) et le chemin des fichiers (par défaut grafana/).
3. Choisissez la cible : un dossier Grafana (recommandé pour commencer) ou toute l'instance.
4. Choisissez si les dashboards existants doivent être exportés vers le dépôt lors de la première synchronisation.
5. Réglez la synchronisation : webhook (immédiat) et/ou intervalle d'interrogation, puis enregistrez.

3. Travailler au quotidien #

Enregistrer, relire, revenir en arrière.

Enregistrer un dashboard #

Un dashboard synchronisé porte l'étiquette Provisioned. À l'enregistrement, Grafana propose d'écrire directement sur la branche configurée ou de créer une nouvelle branche et d'ouvrir une pull request. Avec une pull request, le dashboard n'est mis à jour dans Grafana qu'une fois la branche fusionnée.

grafana/
├── equipe-web/
│   ├── apercu-service.json
│   └── latence-api.json
└── infra/
    └── noeuds-kubernetes.json

Chaque dossier du dépôt correspond à un dossier Grafana ; chaque fichier JSON est un dashboard.

Modifier depuis Git #

Un commit sur la branche (édition du JSON, renommage, suppression) est appliqué à Grafana au prochain webhook ou à la prochaine interrogation. Supprimer un fichier supprime le dashboard. Pour revenir en arrière, il suffit d'annuler le commit (git revert).

git pull
# corriger un seuil dans le JSON
git commit -am "latence-api : seuil d'alerte à 300 ms"
git push
# revenir à la version précédente
git revert HEAD && git push

4. Limites et bonnes pratiques #

Éviter les mauvaises surprises.

Limites #

• Les ressources synchronisées sont les dashboards et les dossiers ; alertes, sources de données et utilisateurs relèvent d'autres outils (provisioning, Terraform, API).
• GitHub est le fournisseur pris en charge ; vérifiez la prise en charge de GitHub Enterprise et des autres forges dans la documentation de votre version.
• En Grafana 12, la fonction est expérimentale : sans support et susceptible de changer.
• Un dashboard synchronisé ne doit pas être aussi géré par le provisioning par fichiers ou par Terraform.

Bonnes pratiques #

• Commencer par un dossier pilote plutôt que toute l'instance.
• Protéger la branche principale et imposer la pull request pour les dossiers critiques.
• Ajouter une vérification en CI (JSON valide, pas d'UID en double).
• Utiliser un compte de service ou un jeton dédié, avec rotation planifiée.
• Documenter dans le README du dépôt quel dossier Grafana correspond à quel dossier Git.

Bonne pratique : gardez des UID de dashboard stables : ils servent de clé entre Grafana et le dépôt, et les liens entre dashboards en dépendent.