Git Sync en Grafana: versionar los dashboards en GitHub

1. ¿Qué es Git Sync? #

El principio y lo que cambia.

El principio #

Disponible en: ✓ OSS ✓ Enterprise ✓ Cloud Experimental en Grafana 12, disponible en versión estable a partir de Grafana 13

Git Sync conecta Grafana con un repositorio Git (GitHub): los dashboards y carpetas de una carpeta de Grafana, o de toda la instancia, se almacenan como archivos JSON en una rama y una ruta del repositorio. Ambos lados permanecen sincronizados: un cambio guardado en Grafana se convierte en un commit (o en una pull request), y un commit enviado al repositorio actualiza Grafana.

Es la pieza de « observability as code » integrada en la interfaz: los equipos siguen construyendo sus dashboards visualmente, pero el historial, la revisión y la vuelta atrás pasan por Git.

Grafana guarda en el repositorio mediante commit o pull request; el repositorio actualiza Grafana. — El repositorio se convierte en la fuente de verdad de los dashboards sincronizados.

¿Git Sync o provisioning por archivos? #

Criterio	Provisioning por archivos	Git Sync
Sentido	Archivos → Grafana (solo lectura en la interfaz)	Grafana ⇄ Git (en ambos sentidos)
Modificar un dashboard	Editar el JSON y volver a desplegar	En la interfaz, y después commit o pull request
Revisión	En tu cadena CI/CD	Pull request abierta desde Grafana
Infraestructura	Acceso al sistema de archivos del servidor	Un repositorio de GitHub y un token
Grafana Cloud	No (sin acceso a los archivos)	Sí

A tener en cuenta: el provisioning clásico (lección anterior) sigue siendo la solución adecuada para orígenes de datos o dashboards impuestos y no modificables; Git Sync conviene a los dashboards que los equipos hacen evolucionar.

2. Puesta en marcha #

Requisitos, token y conexión del repositorio.

Requisitos #

Grafana 12 (función experimental) o Grafana 13 y posteriores; en Grafana Cloud, la función se ofrece en el stack.
En Grafana 12 autoalojado: activar los feature toggles provisioning y kubernetesDashboards.
Un repositorio de GitHub dedicado (o una carpeta dedicada en un repositorio) y el rol de administrador en Grafana.
Para la sincronización inmediata, una URL pública de Grafana accesible por los webhooks de GitHub; si no, Grafana consulta el repositorio a intervalos regulares.

# 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

El token de GitHub #

Crea un fine-grained personal access token limitado al repositorio, con los permisos: Contents (lectura y escritura), Metadata (lectura), Pull requests (lectura y escritura) y Webhooks (lectura y escritura). Dale una fecha de caducidad y apúntala: cuando caduque, la sincronización se detiene.

Error común: usar un token clásico sobre todos tus repositorios. Limita siempre el token al único repositorio sincronizado.

Conectar el repositorio #

Abre Administration › Provisioning (según la versión: Administration › General › Provisioning) y después Configure Git Sync.
Pega el token, la URL del repositorio, la rama (por ejemplo main) y la ruta de los archivos (por defecto grafana/).
Elige el destino: una carpeta de Grafana (recomendado para empezar) o toda la instancia.
Elige si los dashboards existentes deben exportarse al repositorio en la primera sincronización.
Configura la sincronización: webhook (inmediata) y/o intervalo de consulta, y guarda.

Requisitos, token de GitHub, Provisioning, repositorio, destino y sincronización. — La pestaña Events de la conexión muestra después cada sincronización y sus errores.

3. Trabajar en el día a día #

Guardar, revisar, volver atrás.

Guardar un dashboard #

Un dashboard sincronizado lleva la etiqueta Provisioned. Al guardar, Grafana propone escribir directamente en la rama configurada o crear una nueva rama y abrir una pull request. Con una pull request, el dashboard solo se actualiza en Grafana una vez fusionada la rama.

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

Cada carpeta del repositorio corresponde a una carpeta de Grafana; cada archivo JSON es un dashboard.

Modificar desde Git #

Un commit en la rama (edición del JSON, cambio de nombre, eliminación) se aplica a Grafana en el siguiente webhook o en la siguiente consulta. Eliminar un archivo elimina el dashboard. Para volver atrás, basta con revertir el 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. Límites y buenas prácticas #

Evitar sorpresas desagradables.

Límites #

Los recursos sincronizados son los dashboards y las carpetas; alertas, orígenes de datos y usuarios dependen de otras herramientas (provisioning, Terraform, API).
GitHub es el proveedor compatible; comprueba la compatibilidad con GitHub Enterprise y otras forjas en la documentación de tu versión.
En Grafana 12, la función es experimental: sin soporte y sujeta a cambios.
Un dashboard sincronizado no debe gestionarse también mediante provisioning por archivos ni mediante Terraform.

Buenas prácticas #

Empezar por una carpeta piloto en lugar de toda la instancia.
Proteger la rama principal e imponer la pull request para las carpetas críticas.
Añadir una comprobación en CI (JSON válido, sin UID duplicados).
Usar una cuenta de servicio o un token dedicado, con rotación planificada.
Documentar en el README del repositorio qué carpeta de Grafana corresponde a qué carpeta de Git.

Buena práctica: mantén estables los UID de los dashboards: sirven de clave entre Grafana y el repositorio, y los enlaces entre dashboards dependen de ellos.