Convert PBIX to PBIP and PBIR: A Team Migration Plan
Saving as PBIP takes a minute. Changing how a team works takes a plan. Repository layout, what to commit, branching, reviews and a phased rollout.
Core Engineering Takeaways
- •PBIP saves a report and model as folders of text: TMDL for the semantic model and PBIR for the report, which Microsoft documents as generally available and the default report format.
- •PBIX remains the single-file format; PBIP is for content a team maintains together.
- •Commit the definition folders; ignore local settings and the data cache.
- •Roll out in phases: one model end-to-end first, then reviews and CI, then the rest of the estate.
1. Why move from PBIX at all
A .pbix file is a binary. For one analyst that is fine. For a team it causes the same problems every time:
- Two people cannot work on the same file without one overwriting the other.
- Nobody can review a change: you cannot diff a binary.
- "What changed between last month and now?" has no answer.
- Rolling back means hunting for an older copy on SharePoint.
Power BI Projects (PBIP) save the same content as folders of text files. The semantic model is stored as TMDL (Tabular Model Definition Language) and the report as PBIR (the enhanced report format). Microsoft documents PBIR as generally available and the default report format. Text means Git can diff, review, merge and roll back every change — and Fabric Git integration can sync workspaces with a repository.
PBIX is not going away: it remains the single-file format, and it is still the right choice for personal and throwaway work.
2. What a PBIP project looks like
Saving a report as a Power BI project produces something like this:
Sales.pbip
Sales.SemanticModel/
definition/
model.tmdl
relationships.tmdl
tables/
Sales.tmdl
Customer.tmdl
Date.tmdl
.pbi/
Sales.Report/
definition/
report.json
pages/
<page>/page.json
<page>/visuals/<visual>/visual.jsonEach table is its own TMDL file containing its columns, measures and partitions, so a change to one measure shows up as a few lines in one file. Each report page and visual is its own JSON file in PBIR.
If your version of Power BI Desktop still lists project or TMDL options under preview features, enable them before saving.
3. What to commit and what to ignore
Commit the .pbip file and the definition folders. Do not commit machine-specific or data files — in particular the local settings and the cached data in the .pbi folders, which can be large and may contain data:
**/.pbi/localSettings.json
**/.pbi/cache.abfPower BI Desktop generates a .gitignore with sensible defaults when it creates a project; review it rather than replacing it. The PBIP readiness checker generates a starter .gitignore and pipeline for your setup.
Also keep credentials and connection secrets out of the repository. Parameters for server and database names are fine; passwords and keys are not.
4. A workflow the team will actually follow
Keep it simple to start:
mainis what is in production. Protect it: changes arrive only through pull requests.- Short-lived feature branches for each change ("add margin measures", "fix date table").
- Pull requests with one reviewer who checks the TMDL diff: measure logic, naming, descriptions, relationship changes.
- A deployment step from
mainto the production workspace — Fabric Git integration, deployment pipelines, or a CI job — so nobody edits production by hand.
Resist the urge to design the perfect branching strategy on day one. A team that reliably reviews every change on a simple flow is far ahead of one with an elaborate strategy nobody follows.
5. What reviewing a TMDL change looks like
The payoff of PBIP is that a change becomes a small, readable diff. Adding a description and changing a format string on a measure looks like this in a pull request:
+ /// Net sales after returns, excluding tax
measure 'Total Sales' = SUM ( Sales[Amount] )
- formatString: #,0
+ formatString: $#,0A reviewer can see exactly what changed and ask the right questions in seconds. A useful review checklist for TMDL pull requests:
- Measure logic: does the DAX do what the description says? Are there whole-table FILTERs, unsafe divisions or measure references inside iterators?
- Names and descriptions: business-friendly, consistent, and present on everything a user can see.
- Relationships: any new bidirectional or many-to-many relationship needs a reason in the PR description.
- Columns: new high-cardinality columns (IDs, timestamps) need a reason too — they cost memory on every refresh.
- Report changes: PBIR diffs show which pages and visuals changed; check that removed visuals were meant to go.
Keep pull requests small. A PR that changes one measure and its description is reviewed in a minute; one that touches forty files is approved without being read.
6. Add automated checks
Once changes flow through pull requests, add checks that run on every PR. Good first rules:
- Measures without descriptions.
- Naming conventions (no
Measure 1, no technical prefixes in user-facing names). - Risky DAX patterns: division without
DIVIDE, whole-tableFILTER, measure references inside iterators. - Bidirectional relationships added without a justification.
Start by reporting, not blocking: let the team see the findings for a few weeks, fix the existing backlog, then make the most important rules blocking. BIKit Lite is a quality gate for PBIP/TMDL that produces exactly this kind of PR report.
7. A phased rollout plan
- Pilot one model end-to-end (1–2 weeks of normal work). Convert it, put it in a repository, make a real change through a pull request, deploy it. The goal is to find the friction, not to be fast.
- Write down the workflow as a one-page playbook, based on what actually happened in the pilot.
- Add CI checks in report-only mode.
- Convert the next models in order of how often they change — frequently edited models benefit most.
- Make key checks blocking once the backlog is fixed.
Expect the first few pull requests to feel slow. That passes quickly, and what remains is a team that can answer what changed, who changed it and why for every model in production.
If you want help getting there, the PBIP, Git & CI/CD setup sprint delivers the repository, workflow, checks and first converted models with your team.
How ready is your team for PBIP?
Score your workflow and get a generated .gitignore and starter pipeline, or have the setup done with your team.
Get the next Engineering Note
Practical DAX, semantic model and Fabric notes. 1–2 a month, unsubscribe any time.