Versionamento com Git para projetos PBIP

Fluxo prático: repositório, branches, PRs, diffs legíveis e boas práticas para time

TL;DR: Dentro da pasta do PBIP, inicialize um repositório Git, mantenha um .gitignore que exclua cache e arquivos locais (ex.: cache.abf e localSettings.json), normalize EOL com .gitattributes, trabalhe em branches por feature, faça commits pequenos (idealmente com Conventional Commits), abra Pull Requests e revise os diffs (TMDL/JSON) antes de publicar.

Por que isso é a “virada de chave” no BI

Quando o Power BI vira PBIP, você deixa de “versionar um arquivo” e passa a versionar um projeto. A consequência prática é enorme:

• Diff legível (medidas, M, propriedades de visuais, relacionamentos).
• PR com revisão real (não “confia e publica”).
• Histórico auditável (o que mudou, por quem e por quê).
• Colaboração com menos risco (branches, testes, rollback).

Antes de começar: o que não versionar

Projetos PBIP usam uma pasta .pbi/ com arquivos locais e cache. Em especial:

• **/.pbi/cache.abf (cache / binário — conflito garantido)
• **/.pbi/localSettings.json (config local — não é do time)

Esses itens devem ficar fora do Git para evitar repositório pesado e conflitos binários.

Preparando o repositório Git

No diretório do seu PBIP:

# 1) Inicialize o repositório
git init

# 2) Crie/ajuste .gitignore e .gitattributes (recomendado)

# 3) Adicione os artefatos do projeto
git add .

# 4) Primeiro commit
git commit -m "feat: inicia projeto Power BI em PBIP"

# 5) Vincule ao remoto (GitHub, Azure DevOps, GitLab etc.)
git branch -M main
git remote add origin <URL_DO_SEU_REPOSITORIO>
git push -u origin main

.gitignore sugerido (PBIP “na vida real”)

Comece por aqui e adapte conforme o time:

# --- PBIP / Power BI Desktop (evite cache e configs locais) ---
**/.pbi/localSettings.json
**/.pbi/cache.abf

# (Opcional) se seu time preferir, ignore a pasta toda:
# **/.pbi/

# --- Evite binários do Power BI no versionamento ---
*.pbix
*.pbit
*.pbids

# --- SO/IDE ---
.DS_Store
Thumbs.db
.vscode/
.idea/
*.user
*.suo

# --- Logs e temporários ---
*.log
tmp/

Por que isso importa? Ignorar cache.abf e localSettings.json reduz ruído e remove a principal fonte de conflito binário. Cada dev faz o refresh local quando necessário.

.gitattributes sugerido (menos “diff falso”, mais review)

O objetivo é reduzir ruído e normalizar fim de linha (principalmente em times mistos Windows/macOS).

* text=auto

# Definições do PBIP / PBIR
*.pbip text eol=lf
*.pbir text eol=lf

# Artefatos comuns do report/model
*.json text eol=lf
*.tmdl text eol=lf
*.tmsl text eol=lf
*.bim  text eol=lf
*.m    text eol=lf
*.dax  text eol=lf

Depois de adicionar o .gitattributes, vale renormalizar uma vez:

git add --renormalize .
git commit -m "chore(git): normaliza EOL para artefatos do PBIP"

Fluxo de trabalho com branches e PRs

1. Crie uma branch por mudança (uma intenção por PR):

git checkout -b feat/ajuste-csat

2. Edite o projeto abrindo o .pbip no Power BI Desktop.

3. Teste localmente:

• refresh (quando aplicável)
• filtros/slicers críticos
• medidas DAX novas/alteradas
• navegação e interações

4. Commits pequenos e descritivos:

git add -A
git commit -m "fix(model): ajusta medida de CSAT para novos status"
git commit -m "feat(report): adiciona cartão de CSAT no resumo"

5. Suba a branch e abra um PR:

git push -u origin feat/ajuste-csat

6. Review do PR (diffs + validação no Desktop).

7. Merge na main = estado aprovado para publicar.

Padrão de commits (Conventional Commits)

Exemplos úteis para BI:

• feat(model): adiciona medidas de CAC e ROI
• fix(report): ajusta interação entre slicers
• refactor(model): renomeia medidas e reorganiza pastas
• chore(git): adiciona regras de EOL e ignores
• docs: adiciona evidências e screenshots do PR

Code review eficaz para BI

Um PR bom de Power BI é engenharia + contexto. Checklist prático:

• DAX: medida nova/alterada tem nome bom, contexto correto e não quebrou agregações.
• Power Query (M): mudança é determinística, sem credenciais hardcoded, com passos bem nomeados.
• Relacionamentos: cardinalidade e direção continuam corretas (evite ambiguidade).
• Visuais: mudança de campos/ordem/formatos tem justificativa e não impacta performance.
• Contexto visual: se mexeu em UX, inclua 1–3 screenshots/GIFs no PR.

Dica que salva time: quando possível, separe PRs de modelo e de layout. Review fica mais rápido e conflitos diminuem.

Onde as mudanças costumam aparecer (pra achar rápido)

• Report: páginas, visuais, interações, navegação e configurações de layout.
• SemanticModel: tabelas, medidas, relacionamentos, parâmetros e definições do modelo.

Na prática, isso te ajuda a revisar com foco:

• mexeu em DAX/M? olhe SemanticModel
• mexeu em visual/página? olhe Report

Resolvendo conflitos (sem trauma)

Conflito aparece quando duas pessoas editam o mesmo artefato (mesma página, mesmo visual, mesma medida).

Estratégia que funciona:

1. Atualize cedo (não deixe a branch “envelhecer”):

git fetch origin
git rebase origin/main
# ou git merge origin/main

2. Resolva o conflito no editor (VS Code ajuda bem).

3. Abra o .pbip no Desktop e valide (obrigatório):

• o relatório abre?
• medidas calculam?
• visuais renderizam?
• refresh funciona?

4. Para reduzir conflito no futuro: combine ownership por páginas/domínios (ex.: Financeiro, Operação, Comercial).

Publicação e ambientes (Dev → Test → Prod)

• Publicação segue via Power BI Desktop: abrir o .pbip e publicar no workspace.
• Para times, Deployment Pipelines (quando fizer sentido) ajudam a promover artefatos com governança.
• Para ambientes, use parâmetros (DEV/TEST/PROD) e evite credenciais em arquivo versionado.

Automação (opcional, mas “adulto”)

Se você quer elevar o nível de governança com pouco atrito:

• Branch protection (PR obrigatório + 1 aprovação).
• CODEOWNERS para exigir revisão em áreas sensíveis (modelo, queries, etc.).
• Template de PR com passos de validação.
• Tags/Releases para marcar o que foi publicado: v2025.12.12 (data) ou v1.8.0 (semver).

Mini-template de PR (copiar e colar)

## O que mudou?
- [ ] Modelo (DAX / relações / tabelas)
- [ ] Query (M / parâmetros)
- [ ] Relatório (páginas / visuais / navegação)

## Como validar?
- Passo 1:
- Passo 2:

## Evidências (se UI mudou)
- Screenshot/GIF:

Checklist rápido

• [ ] Repositório inicializado dentro da pasta PBIP
• [ ] .gitignore ignorando **/.pbi/cache.abf e **/.pbi/localSettings.json
• [ ] .gitattributes normalizando EOL
• [ ] Trabalho sempre em branch (nunca direto na main)
• [ ] Commits pequenos e descritivos
• [ ] PR com revisão dos diffs + evidência visual quando necessário
• [ ] Merge aprovado e publicação controlada por ambientes

Conclusão

PBIP te dá artefatos legíveis; Git te dá histórico, revisão e colaboração. Juntos, eles transformam BI em um fluxo de engenharia: você enxerga o que mudou, por quem, quando e por quê — antes de virar impacto em produção.

Se quiser elevar mais um degrau, o próximo passo é padronizar um “repo template” para dashboards (README, PR template, CODEOWNERS e convenções de nomes). Aí seu BI vira um produto com esteira, não só um relatório.