Versionando projetos Power BI com Git, GitHub e VS Code

As quatro ferramentas

Quatro ferramentas independentes que, juntas, resolvem o problema mais comum de qualquer equipe de BI: saber qual é a versão certa do relatório.

PBIX ou PBIP

A distinção mais importante do guia. Os dois formatos abrem no Power BI Desktop e geram o mesmo relatório, mas só o PBIP funciona com controle de versão.

Instalação e configuração inicial

Seis passos, uma vez por máquina.

1. Criar a conta no GitHub

   Em github.com/signup, use o e-mail corporativo. O nome de usuário aparece em todos os commits e Pull Requests, então escolha algo profissional.

   

2. Configurar a autenticação

   O GitHub não aceita senha na linha de comando. O Git Credential Manager já vem com o instalador do Git para Windows: no primeiro git push abre uma janela do navegador, você entra na conta e as credenciais ficam salvas. A alternativa é gerar um Personal Access Token com escopo repo e usá-lo no lugar da senha.

   Ative a autenticação em dois fatores

   Obrigatória em muitas organizações. Configure em Settings → Password and authentication.

3. Instalar o Git

   Baixe em git-scm.com/downloads. Os padrões servem para quase tudo, mas confirme a tela do PATH.

   

4. Instalar o VS Code

   Baixe em code.visualstudio.com e marque "Adicionar ao menu de contexto do Explorer", que permite abrir qualquer pasta no editor com o botão direito.

5. Instalar o Power BI Desktop

   Prefira a versão da Microsoft Store, que se atualiza sozinha. Depois habilite o formato em Arquivo → Opções e configurações → Opções → Recursos de Versão Preliminar → Power BI Project (.pbip) save option e reinicie o programa.

   Sem essa opção marcada, o PBIP não aparece

   Se "Power BI project files (*.pbip)" não estiver na lista de tipos ao salvar, o recurso não foi habilitado ou o Desktop não foi reiniciado.

6. Instalar as extensões recomendadas

   No VS Code, Ctrl+Shift+X e instale:

   GitHub Pull Requests

   Cria, revisa e aprova Pull Requests dentro do editor.

   GitHub Copilot

   Sugere código DAX/M e escreve mensagens de commit.

   Power BI / TMDL

   Realce de sintaxe para os arquivos .tmdl do modelo.

   Material Icon Theme

   Ícones por tipo de arquivo, para não se perder na árvore do PBIP.

   

Verificando a instalação

No PowerShell ou no terminal do VS Code (Ctrl+'), um número de versão confirma que está tudo certo.

PS C:\> git --version
git version 2.47.0.windows.1

Configuração inicial obrigatória

O Git precisa saber quem você é para assinar os commits. Roda uma única vez por computador: a flag --global vale para todos os projetos.

git config --global user.name "Seu Nome"
git config --global user.email "seu@email.com"
git config --list

Vale padronizar outros três comportamentos que evitam dor de cabeça em equipe:

# branch principal chamada "main" em todo projeto novo
git config --global init.defaultBranch main

# VS Code como editor padrão de mensagens e conflitos
git config --global core.editor "code --wait"

# evita o aviso de divergência no git pull
git config --global pull.rebase false

Transformando um PBIP em projeto versionado

Quatro passos: abrir no VS Code, inicializar o Git, criar o .gitignore e fazer o primeiro commit.

O que é, na prática, um projeto PBIP

Ao salvar como .pbip, o Power BI Desktop não grava um arquivo: grava uma pasta, com o relatório e o modelo semântico separados, em texto puro.

Estrutura de pastas do projeto

Esta é a árvore que o Git vai versionar:

Passo a passo

1. Abrir a pasta no VS Code

   Abra a pasta raiz, a que contém o .pbip — não uma subpasta.

   PowerShell — pelo terminal

   cd "C:\Projetos\Vendas-LATAM"
   code .

2. Inicializar o repositório

   No terminal integrado (Ctrl+'), o comando cria a subpasta oculta .git, onde todo o histórico fica guardado.

   PowerShell — inicializar

   PS ~\Vendas-LATAM> git init
   Initialized empty Git repository in C:/Projetos/Vendas-LATAM/.git/

   Nunca apague a pasta .git

   Ela é o repositório. Apagá-la remove todo o histórico local de uma vez.

3. Criar o .gitignore

   Cache e credenciais não devem ir para o repositório. Crie o arquivo na raiz com este conteúdo:

   .gitignore

   # --- Power BI ---------------------------------------
   # cache local do modelo (pesado e específico da máquina)
   .pbi/localSettings.json
   .pbi/cache.abf
   **/.pbi/localSettings.json
   **/.pbi/cache.abf
   
   # não versione o binário junto do projeto
   *.pbix
   
   # --- Credenciais e dados ----------------------------
   *.env
   credenciais*
   *.xlsx
   *.csv
   
   # --- Sistema operacional ----------------------------
   Thumbs.db
   desktop.ini
   .DS_Store
   
   # --- Temporários ------------------------------------
   ~$*
   *.tmp

   Gere o arquivo automaticamente

   O gitignore.io monta o arquivo a partir das suas tecnologias. Combine o resultado com as regras de Power BI acima.

4. Primeiro commit

   git add . coloca as alterações na área de preparo e git commit grava a fotografia no histórico.

   PowerShell — primeiro commit

   git add .
   git commit -m "Primeiro commit"
   [main (root-commit) a1b2c3d] Primeiro commit
    24 files changed, 1843 insertions(+)

Criando o repositório no GitHub

O histórico já existe na sua máquina. Agora ele precisa de um endereço na nuvem para a equipe acessar o mesmo projeto.

Vale preencher o README.md, que o GitHub exibe na página do repositório: o que o relatório mostra, quais são as fontes de dados, qual .pbip abrir e quem aprova os Pull Requests.

Conectando o repositório remoto

Depois de criar, o GitHub mostra a URL na caixa Quick setup. O origin é apenas um apelido para ela — a convenção universal para "o repositório principal na nuvem".

# HTTPS: recomendado para começar, usa o Credential Manager
git remote add origin https://github.com/bi-latam/vendas-latam-pbip.git
git remote -v

# SSH: exige cadastrar uma chave, mas não pede senha
# git@github.com:bi-latam/vendas-latam-pbip.git

O primeiro push

A flag -u vincula a branch local main à origin/main. Depois disso, um simples git push já sabe para onde enviar.

# garante que a branch local se chama main
git branch -M main

git push -u origin main
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Clone e sincronização

git clone baixa o projeto e todo o histórico para uma máquina nova. É uma operação de primeira vez.

Novo integrante na equipe

Carla entrou no time hoje e não tem nada da pasta do projeto. Depois de receber acesso ao repositório, três comandos resolvem:

# 1. vá para a pasta onde os projetos ficam
cd "C:\Projetos"

# 2. clone: cria a pasta já com o .git dentro
git clone https://github.com/bi-latam/vendas-latam-pbip.git

# 3. entre e abra no VS Code
cd vendas-latam-pbip
code .

Carla agora tem os arquivos, o histórico completo e o origin configurado.

Quem já tem o projeto não clona de novo

Esta é a confusão mais frequente de quem está começando: clone não é atualizar. Clonar cria uma segunda pasta independente, e aí você edita a errada, perde commits locais que ainda não subiram e não vê as branches em andamento. Quem já tem o projeto usa git pull, que traz apenas o que mudou.

# ver em que branch você está e se há algo pendente
git status

# trazer as novidades do remoto para a branch atual
git pull

# só consultar o que mudou, sem alterar seus arquivos
git fetch

Alternativa visual: GitHub Desktop

Se a linha de comando ainda intimida, o GitHub Desktop faz clone, commit, pull e push por botões, executando os mesmos comandos por baixo.

Workflow completo de desenvolvimento

O ciclo que você vai repetir todos os dias, sempre na mesma ordem.

1. Criar a branch

Nunca trabalhe direto na main, e parta sempre de uma base atualizada.

git checkout develop
git pull origin develop
git checkout -b feature/novo-kpi

2. Alterar no Power BI Desktop

Crie a medida, ajuste o visual, salve (Ctrl+S) e feche o Desktop. Fechar importa: arquivos abertos podem gerar alterações "fantasmas".

3. Verificar o status

O comando que você vai digitar mais vezes na vida. Ele responde em que branch você está e o que mudou.

PS ~\Vendas-LATAM> git status
On branch feature/novo-kpi
Changes not staged for commit:
  modified:   Vendas.SemanticModel/definition/tables/Vendas.tmdl
  modified:   Vendas.Report/definition/pages/pages.json

4. Adicionar e commitar

Prefira a mensagem com prefixo: fica muito mais fácil ler o histórico depois.

# tudo o que mudou, ou um arquivo específico
git add .

git commit -m "feat: criação do KPI LATAM" -m "Medida DIVIDE(Receita, Meta) e card na página Visão Geral."

5. Enviar para o GitHub

git push origin feature/novo-kpi

Branches: trabalhando em paralelo sem colisão

Uma branch é uma linha de trabalho independente: você experimenta, quebra e refaz sem afetar o relatório que está em produção.

Comandos essenciais de branch

# listar branches locais (o * marca a atual) e todas, com o remoto
git branch
git branch -a

# criar e mudar, ou apenas mudar
git checkout -b feature/dashboard-latam
git checkout develop

# renomear a branch atual
git branch -m feature/nome-correto

# apagar local e no GitHub
git branch -d feature/dashboard-latam
git push origin --delete feature/dashboard-latam

Por que vale a pena

• Isolamento: sua medida pela metade não quebra o relatório de ninguém.
• Paralelismo real: três pessoas em três frentes, sem fila pelo arquivo.
• Reversão barata: se a ideia não prestou, apaga-se a branch.

Boas práticas

# bons nomes de branch
feature/kpi-margem-latam
fix/relacionamento-calendario
hotfix/medida-ytd-duplicando
release/2026.09

# nomes que atrapalham a equipe
teste2
ana
correcoes-finais-v3

Pull Request: pedindo para juntar o trabalho

O Pull Request (PR) é um pedido formal de merge de uma branch em outra. É onde a revisão por pares acontece — e onde o PBIP mostra seu valor.

Na prática, o PR é uma página no GitHub que reúne os commits, o diff de cada arquivo, os comentários da equipe e o botão que executa o merge. Para um projeto Power BI, isso significa que um colega consegue ler a medida DAX que você escreveu, comentar na linha específica e sugerir ajustes antes de a mudança chegar ao relatório oficial.

Fluxo do Pull Request

Como abrir o Pull Request

1. Dê o push da sua branch

   PowerShell

   git push origin feature/novo-kpi

2. Abra o link que o Git devolveu

   Ou vá ao repositório e clique em Compare & pull request.

3. Confira as branches: base → compare

   base é para onde o código vai (develop); compare é de onde vem (feature/novo-kpi). Trocar as duas é o erro mais comum de quem começa.

4. Escreva a descrição e marque revisores

   A descrição responde o que, por que e como testar. Marque pelo menos um colega em Reviewers e clique em Create pull request.

Modelo de descrição

## O que muda
- Nova medida `[KPI LATAM]` = DIVIDE( [Receita], [Meta] )
- Card do KPI na página "Visão Geral"

## Por que
Demanda #38: a diretoria comercial precisa acompanhar o
atingimento de meta por país no painel de receita.

## Como testar
1. `git checkout feature/novo-kpi` e abra o `Vendas.pbip`
2. Atualize os dados e vá para a página "Visão Geral"
3. Confira o card: deve exibir 104,2% para set/2026

## Checklist
- [x] Testado no Power BI Desktop
- [x] Sem credenciais ou dados sensíveis no commit
- [ ] Validado pelo time de negócio

Merge: juntando as linhas de trabalho

Merge traz os commits de uma branch para outra. O Git tenta fazer isso sozinho e consegue na maioria das vezes.

# 1. vá para a branch que vai RECEBER as alterações
git checkout develop

# 2. garanta que ela está atualizada
git pull origin develop

# 3. traga a branch de origem
git merge feature/novo-kpi

Fast-forward

Acontece quando a branch de destino não recebeu commits novos desde que a feature nasceu: o Git só move o ponteiro para a frente e o histórico fica linear. Para registrar explicitamente a integração, force um commit de merge com git merge --no-ff feature/novo-kpi.

Merge commit

O caso mais comum em equipe: as duas branches avançaram, mas em arquivos ou linhas diferentes. O Git junta tudo automaticamente e cria um commit com dois pais, preservando as duas histórias.

Merge conflict

O Git para quando as duas branches alteraram a mesma linha do mesmo arquivo. Nada é perdido nem sobrescrito: a decisão fica com você, e o próximo capítulo mostra como resolver.

Auto-merging Vendas.SemanticModel/definition/tables/Vendas.tmdl
CONFLICT (content): Merge conflict in Vendas.SemanticModel/definition/tables/Vendas.tmdl
Automatic merge failed; fix conflicts and then commit the result.

Qual estratégia usar no botão do GitHub

Resolução de conflitos

Conflito não é erro nem defeito: é o Git avisando que duas pessoas tiveram ideias diferentes sobre a mesma linha. Resolver é escolher — e testar.

Como o conflito aparece

Ana e Bruno editaram a mesma medida [KPI LATAM] no Vendas.tmdl, cada um na sua branch.

PS> git pull origin develop
Auto-merging Vendas.SemanticModel/definition/tables/Vendas.tmdl
CONFLICT (content): Merge conflict in .../tables/Vendas.tmdl
Automatic merge failed; fix conflicts and then commit the result.

# ver quais arquivos precisam de decisão
PS> git status
  both modified:   Vendas.SemanticModel/definition/tables/Vendas.tmdl

Entendendo os marcadores

O Git escreve as duas versões dentro do arquivo. Entre <<<<<<< HEAD e ======= fica a sua versão; entre ======= e >>>>>>>, a que está chegando da outra branch. Os marcadores não são código: são sinalização temporária que você precisa remover.

    measure 'Receita' = SUM( Vendas[Valor] )

<<<<<<< HEAD
    measure 'KPI LATAM' =
        DIVIDE( [Receita], [Meta] )
        formatString: 0.0%
=======
    measure 'KPI LATAM' =
        DIVIDE( [Receita YTD], [Meta YTD] )
        formatString: 0.00%
>>>>>>> develop

Como resolver

O VS Code detecta os marcadores e oferece botões no topo do arquivo:

1. Converse antes de escolher

   No exemplo, a versão correta era uma terceira: [Receita YTD] com formatação de uma casa decimal. Um conflito quase sempre revela divergência de entendimento, não um problema técnico.

2. Edite o arquivo e remova todos os marcadores

   Vendas.tmdl — resolvido

       measure 'KPI LATAM' =
           DIVIDE( [Receita YTD], [Meta YTD] )
           formatString: 0.0%
           description: Atingimento de meta acumulado no ano.

   Marcador esquecido = projeto corrompido

   Se sobrar um <<<<<<< no TMDL ou no JSON, o Power BI Desktop se recusa a abrir o projeto. Busque por <<< antes de commitar.

3. Teste antes do merge

   Arquivo resolvido não significa relatório funcionando. Abra o projeto e valide:

   • O .pbip abre e o modelo atualiza sem erro de DAX.
   • A medida devolve o número esperado, conferido contra uma fonte conhecida.
   • Nenhuma medida ficou duplicada, efeito colateral do "Accept Both".

4. Marque como resolvido e conclua

   PowerShell — finalizar

   # sinaliza ao Git que o arquivo está resolvido
   git add Vendas.SemanticModel/definition/tables/Vendas.tmdl
   git commit -m "merge: resolve conflito na medida KPI LATAM"
   git push origin feature/novo-kpi

Quando quiser voltar atrás

# cancela o merge e volta tudo ao estado anterior
git merge --abort

# lista apenas os arquivos em conflito
git diff --diff-filter=U

Colaboração entre desenvolvedores

Um cenário real: dois analistas, um projeto, uma semana de trabalho. Ana cuida do modelo semântico; Bruno cuida dos visuais.

O cenário, passo a passo

1. Cada um clona e cria a sua branch

   O clone é uma vez por máquina; a branch nasce sempre de uma develop atualizada.

   Ana e Bruno — cada um na sua máquina

   git clone https://github.com/bi-latam/vendas-latam-pbip.git
   cd vendas-latam-pbip
   git checkout develop
   git pull origin develop
   
   # Ana
   git checkout -b feature/kpi-margem
   
   # Bruno
   git checkout -b feature/pagina-comparativo

2. Commitam ao longo do dia e dão push

   Commits pequenos, um por ideia concluída. Não espere o fim da semana.

   Ana — durante o trabalho

   git add .
   git commit -m "feat: medida de margem bruta por país"
   git push origin feature/kpi-margem

3. Criam os Pull Requests e revisam um ao outro

   Ana abre PR de feature/kpi-margem para develop e coloca Bruno como revisor; Bruno faz o mesmo com a branch dele. Revisão cruzada: cada um olha o trabalho do outro.

4. Merge para develop e depois para main

   Aprovados, os dois PRs entram em develop. O primeiro merge costuma ser fast-forward e o segundo gera um merge commit, o que é esperado. Depois que a develop é validada pelo negócio, abre-se um PR dela para a main, que passa a ser a versão oficial.

Os comandos de sincronização

# === TODA MANHÃ, antes de abrir o Power BI ===
git status
git pull origin develop

# === A CADA DOIS DIAS, alinhe sua feature com a base ===
git checkout feature/kpi-margem
git pull origin develop

# === DEPOIS DE UM MERGE APROVADO ===
git checkout develop
git pull origin develop
git branch -d feature/kpi-margem

Boas práticas para equipes Power BI

Sete acordos simples que transformam Git de "ferramenta que atrapalha" em processo que a equipe nem percebe mais.

Mensagens de commit

O padrão Conventional Commits usa um prefixo que diz a natureza da mudança, e o histórico passa a se ler como um changelog.

Combinados adicionais

• Feche o Power BI Desktop antes de pull, merge ou troca de branch.
• Nunca commite credenciais nem planilhas de origem: para isso existe o .gitignore.
• Documente as medidas no próprio modelo, no campo description: a documentação viaja com o projeto.
• Padronize a nomenclatura de tabelas, colunas e medidas antes de escalar o time.

Publicação e entrega final

O projeto foi aprovado pelo negócio. Falta o último trecho: de develop para main, e da main para o Serviço do Power BI.

Depois do merge final

Com o PR de develop para main aprovado, todos alinham a máquina local com a nova versão oficial — e vale marcar a entrega com uma tag.

git checkout main
git pull

# marca o ponto exato do que foi publicado
git tag -a v1.3 -m "Release 1.3: KPI LATAM e página comparativa"
git push origin v1.3

Três regras depois da entrega

# apagar a branch local e a do GitHub
git branch -d feature/novo-kpi
git push origin --delete feature/novo-kpi

# limpar referências de branches que já não existem no remoto
git fetch --prune

# === começar a próxima demanda ===
git checkout develop
git pull origin develop
git checkout -b feature/proxima-melhoria

Comandos Git mais utilizados

A referência rápida do dia a dia: treze comandos cobrem mais de 95% do trabalho em um projeto Power BI.

Comandos de emergência

# descartar alterações de um arquivo (CUIDADO: não tem volta)
git restore Vendas.Report/definition/report.json

# desfazer o último commit, mantendo as alterações nos arquivos
git reset --soft HEAD~1

# guardar temporariamente o que você está fazendo
git stash
git stash pop

# corrigir a mensagem do último commit (antes do push)
git commit --amend -m "feat: mensagem corrigida"

# o histórico de TUDO que você fez: o salva-vidas do Git
git reflog

Recursos úteis

Documentação oficial para consultar quando este guia não for suficiente. Todos os links abrem em nova aba.

Para ir além