O Grafana Git Sync guarda seus dashboards como arquivos JSON em um repositório Git e mantém os dois lados sincronizados. Quem edita o painel na interface gera um commit ou um pull request. Quem altera o arquivo no Git vê o dashboard mudar no Grafana.
Isso resolve um problema clássico de NOC: o dashboard do plantão muda sem aviso, ninguém sabe quem mexeu e não existe versão anterior para voltar. Neste artigo você vê como o Grafana Git Sync funciona no Grafana 13, como configurá-lo com GitHub e quais limites aparecem em produção.
TL;DR
- O Grafana Git Sync sincroniza dashboards e pastas com um repositório Git, com histórico, revisão por pull request e rollback.
- O recurso chegou à disponibilidade geral no Grafana 13, com autenticação por GitHub App e suporte a GitLab, Bitbucket e Git puro.
- Alertas e data sources ficam fora da sincronização. Use Terraform para eles.
- A documentação recomenda no máximo 1.000 recursos por conexão de repositório.
Por que dashboards editados na interface viram risco
Dashboards editados direto na interface têm três problemas em operação: não deixam histórico confiável, não passam por revisão e não se copiam com segurança entre ambientes. Cada edição sobrescreve a anterior. Quando um painel quebra no meio de um incidente, ninguém consegue ver o que mudou.
A documentação do Grafana lista os ganhos de levar os dashboards para o Git: histórico de versões, rollback, trilha de auditoria, automação de CI/CD, consistência entre ambientes e backup a partir do repositório.
O Grafana 13 foi apresentado no GrafanaCON 2026, em abril, e colocou o Git Sync em disponibilidade geral. O anúncio do Grafana 13 diz ainda que os dashboards provisionados por API, Terraform ou Git Sync continuam funcionando com o novo schema dos dynamic dashboards.
Como o Grafana Git Sync funciona
O Grafana Git Sync liga um local do Git (repositório, branch e caminho) a uma instância do Grafana. O Grafana cria uma pasta em Dashboards, em geral com o nome do repositório, e coloca ali os dashboards daquele local. Uma instância pode conectar vários repositórios, branches ou caminhos.
A sincronização funciona nos dois sentidos. Em OSS e Enterprise, o Grafana consulta o repositório a cada 60 segundos por padrão, e no Grafana Cloud o padrão é 300 segundos. Com webhooks, a mudança aparece quase na hora.
O escopo é estreito de propósito: o Grafana Git Sync cuida de dashboards e pastas. Alertas, data sources e painéis avulsos não são sincronizados, segundo a documentação oficial do Git Sync.
Fluxo de edição do Grafana Git Sync
Ao editar um dashboard provisionado, você clica em Save dashboard e informa branch, pasta do repositório, nome do arquivo e comentário de commit. A aba Changes mostra o diff. Depois você escolhe Open a pull request in GitHub e faz o merge pelo fluxo normal do time.
Esse comportamento é configurável. Na conexão, você liga ou desliga a abertura de pull request ao salvar, o push direto na branch e o modo somente leitura.
Duas regras valem para o dia a dia. Para excluir um dashboard, apague o arquivo no repositório, porque a interface não exclui. Para restaurar, abra um pull request que devolva o arquivo, porque a restauração pela interface não existe hoje.
Provedores Git compatíveis
| Provedor | Autenticação | Edições |
|---|---|---|
| Git puro | Personal Access Token | Cloud, OSS, Enterprise |
| GitHub | Personal Access Token ou GitHub App | Cloud, OSS, Enterprise |
| GitLab | Personal Access Token | Cloud, Enterprise |
| Bitbucket | API token com escopos | Cloud, Enterprise |
Git puro, GitLab e Bitbucket exigem o Grafana 12.4 ou superior, e GitLab e Bitbucket têm funcionalidade limitada por enquanto. O Git puro aceita só Smart HTTP v2, sem SSH.
Configuração com GitHub passo a passo
Antes de começar, confirme o que a documentação pede. Você precisa de uma instância do Grafana (Cloud, OSS ou Enterprise) com direitos de administrador e de um provedor Git compatível. Se for usar webhooks ou renderização de imagens, a instância precisa estar acessível pela internet.
O feature toggle provisioning vem ligado por padrão no Grafana Cloud e, a partir do Grafana 13, também em OSS e Enterprise. Você não precisa ativá-lo à mão. Os requisitos completos estão em Before you begin.
Crie o GitHub App
Prefira o GitHub App ao Personal Access Token. O token precisa vir de uma conta com papel de administrador no repositório e fica preso a uma pessoa. O app é uma instalação com permissões fixas nos repositórios que você escolher.
- Crie o app com um nome único e use a URL do seu Grafana como página inicial.
- Desative a opção Active do webhook.
- Defina as permissões do repositório: Administration (read-only), Contents (read and write), Metadata (read-only), Pull requests (read and write) e Webhooks (read and write).
- Limite a instalação à sua conta, gere a chave privada (arquivo PEM) e instale o app nos repositórios que serão sincronizados.
- Anote o App ID, o Installation ID (está na URL da página da instalação) e a chave privada.
Conecte o repositório no Grafana
Em Administration > General > Provisioning, escolha GitHub e selecione Connect to a new app. Informe App ID, Installation ID, chave privada e a URL do repositório. Em seguida, defina a branch (o padrão é main) e o caminho opcional dentro do repositório.
Em Choose what to synchronize, escolha entre uma pasta nova ou a raiz, dê um nome de exibição e selecione Synchronize with external storage. Você pode criar até 10 conexões.
As configurações finais reúnem o intervalo de sincronização, o modo somente leitura, as opções de pull request e push, as prévias de dashboard e os webhooks. Termine em Finish.
Para produção, deixe o pull request ligado e o push direto desligado, e proteja a branch main no GitHub com revisão obrigatória. Assim, nenhuma mudança chega ao painel do plantão sem revisão.
Defina o Path como dashboards e organize os arquivos por domínio:
dashboards/
├── aws/
│ ├── ec2-visao-geral.json
│ └── rds-saude.json
└── noc/
└── plantao-resumo.jsonSe o seu Git roda em rede privada, o Grafana auto-hospedado (13.0.4, 13.1.1 ou superior) bloqueia por padrão hosts que resolvem para endereços privados. Libere só o host necessário no grafana.ini, porque ele recebe o seu token Git a cada sincronização:
ini
[provisioning]
allowed_git_urls = git.interno.example.comValidação no pull request com GitHub Actions
Como o Grafana Git Sync abre pull requests, o repositório é o lugar certo para barrar erro antes do merge. O workflow abaixo garante JSON válido e uid presente e único em todos os arquivos.
yaml
name: validar-dashboards
on:
pull_request:
paths:
- "dashboards/**/*.json"
jobs:
validar:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: JSON válido
run: find dashboards -name '*.json' -print0 | xargs -0 -n1 jq empty
- name: uid presente e único
run: |
set -euo pipefail
uids=$(find dashboards -name '*.json' -print0 | xargs -0 -n1 jq -r '(.uid // .metadata.name // "")')
if echo "$uids" | grep -q '^$'; then echo "Há dashboard sem uid"; exit 1; fi
dup=$(echo "$uids" | sort | uniq -d)
if [ -n "$dup" ]; then echo "uid duplicado: $dup"; exit 1; fiMantive o fallback .metadata.name para o caso de seus arquivos usarem o schema v2 dos dynamic dashboards. Confira o formato real dos seus arquivos antes de ativar a regra.
Grafana Git Sync, Terraform ou API: qual usar
A página de opções de deploy do Grafana descreve três caminhos.
| Opção | Indicada para | Custo da escolha |
|---|---|---|
| Git Sync | Times que já trabalham com Git e não querem pipeline próprio | Menos controle sobre o processo de deploy |
| Terraform | Times com fluxo de Terraform existente | Aprender Terraform, se você ainda não usa |
| API do Grafana | Quem precisa de controle total | Mais código para escrever e manter |
A API é a base dos outros dois métodos, segundo o Grafana.
Minha recomendação: use o Grafana Git Sync para dashboards e pastas, e o Terraform para o que ele não cobre, como data sources e alertas. Cada ferramenta fica com um tipo de recurso, o que evita dois donos para o mesmo objeto.
Limites e armadilhas em produção
Estes são os pontos que mais surpreendem o time depois de migrar para o Grafana Git Sync:
- Escala: a documentação recomenda no máximo 1.000 recursos por conexão. O Grafana Cloud Free permite 1 repositório e 20 recursos, e os demais planos, o OSS e o Enterprise permitem 10 repositórios. Para passar de 1.000, conecte o mesmo repositório várias vezes, cada uma com um caminho diferente, e use sincronização sem pasta.
- UID duplicado: o Git Sync não assume um recurso enquanto existir no Grafana um dashboard não gerenciado com o mesmo UID. Remova o original manualmente antes.
- Instância inteira: a sincronização de toda a instância é experimental, assim como a migração de recursos existentes. Teste fora de produção.
- Rede: no Grafana Cloud, o servidor Git precisa aceitar tráfego dos IPs do Grafana, e os webhooks exigem que ele alcance
*.grafana.net. Se a instância não é acessível pela internet, desative o webhook e use o intervalo de consulta.
Veja os limites de uso do Git Sync antes de planejar a migração, porque os números variam por plano.
Segurança, custo e observabilidade
Segurança. No Grafana Git Sync, use o GitHub App com as cinco permissões listadas e nada além. As pastas provisionadas herdam os papéis por padrão (Admin para Admin, Editor para Editor, Viewer para Viewer), e você ajusta isso nas permissões do Git Sync. Custo. A documentação consultada não descreve cobrança separada para o Git Sync, e os limites dependem do plano do Grafana Cloud. Considere o Image Renderer, opcional, que gera prévias nos pull requests, e a carga extra no banco.
Observabilidade. Acompanhe a conexão do Grafana Git Sync em Administration > General > Provisioning, na aba Repositories. O Grafana Advisor, também em disponibilidade geral no Grafana 13, roda verificações periódicas e aponta data sources com falha, plugins desatualizados e SSO mal configurado.
Conclusão
O Grafana Git Sync transforma dashboards em código revisável: cada mudança passa por pull request, deixa histórico e pode ser revertida pelo repositório. Em troca, ele cobre só dashboards e pastas, recomenda até 1.000 recursos por conexão e exige excluir e restaurar pelo Git.
Comece pequeno. Conecte um repositório vazio com o path dashboards, salve um dashboard de teste e abra o primeiro pull request. Depois leve o fluxo para os painéis do plantão e acrescente o workflow de validação.
