Power BI Projects (PBIP), TMDL, PBIR, Git and CI/CD

Last checked against Microsoft documentation: 14 November 2026

A Power BI Project saves your report and semantic model as plain text files in folders instead of one binary .pbix file. That lets you use Git, pull requests and automated checks, just like software teams do. Microsoft's September 2026 Message Center notice (MC1465770) announced general availability of developer mode and the PBIP format, with PBIR as the default report format.

The three formats in plain words

NameWhat it storesWhy it helps
PBIPThe project folder that holds both the report and the semantic modelOpens in Desktop; Git-ready
PBIRThe report: every page, visual and bookmark in its own JSON fileSmall, readable diffs; fewer merge conflicts; each file has a public JSON schema
TMDLThe semantic model: tables, measures, relationships, roles as readable textOne file per table; easy to review line by line

PBIR is not replacing PBIX. PBIX stays the main file format, and PBIX files now store their report data in PBIR format inside. PBIR-Legacy (the old single report.json) is still supported, but a report edited in current tools is upgraded to PBIR automatically.

What a project folder looks like

text
SalesProject/
├── Sales.Report/
├── Sales.SemanticModel/
├── .gitignore
└── Sales.pbip
  • The .pbip file is a pointer. Opening it opens the report and model together. It is optional: you can also open definition.pbir inside the report folder.
  • Desktop creates a .gitignore if none exists. It skips .pbi/localSettings.json and .pbi/cache.abf, which are local-only files such as the data cache.
  • One folder can hold several reports and models.

TMDL in five rules

  1. Indentation is structure. One tab per level. Wrong indentation is a parse error.
  2. Declare an object with its type and name, such as table Orders or column 'Net Amount'.
  3. Properties use a colon, such as dataType: decimal.
  4. A measure's formula follows an equals sign and may run over several indented lines.
  5. Descriptions use /// on the line directly above the object. Wrap names that contain spaces, dots, equals signs or colons in single quotes.
TMDL
/// Sales fact table
table Orders

	column 'Net Amount'
		dataType: decimal
		sourceColumn: NetAmount
		summarizeBy: sum

	measure 'Total Net' = SUM ( Orders[Net Amount] )
		formatString: $ #,##0

In a project, each table gets its own file in a tables folder. Other objects sit in model.tmdl, relationships.tmdl, expressions.tmdl, dataSources.tmdl, functions.tmdl (your user-defined functions from Lesson 1), and folders for roles, perspectives and cultures. A ref line keeps item order stable so unrelated changes do not show up in diffs.

Inside Desktop you can also edit the model as code in TMDL view, which is generally available. Use Preview to see a diff before you click Apply. TMDL view on the web is still in preview.

Step by step: from one file to a safe release

Part A: save as a project (Power BI Desktop)

  1. Open your report and choose File > Save as > Power BI Project (.pbip).
  2. Pick a short folder path. On Windows the default path limit is 260 characters.
  3. Do not save straight into OneDrive or SharePoint. Saving into a locally synced folder can cause sync problems.

Part B: put it in Git (VS Code)

  1. Open the project folder in VS Code and choose Source Control > Initialize Repository.
  2. Make the first commit with a clear message.
  3. Set Git's autocrlf option, because Desktop writes Windows line endings.
  4. For each change, create a branch, save in Desktop, commit, and open a pull request.

If you edit project files outside Desktop, keep them as UTF-8 without BOM. Desktop notices outside saves and offers to apply them in one click. Reading is fully supported; writing works but, in rare cases, can leave the model inconsistent.

Part C: connect a workspace (Fabric portal)

  1. Connect a Fabric workspace to one branch of an Azure DevOps or GitHub repository. A workspace connects to a single branch.
  2. Give each developer a separate workspace on their own branch. Changes made directly in a shared workspace affect everyone using it. The other option is to work locally in Desktop and VS Code.
  3. Remember that Update always brings in the whole branch up to its latest commit. You cannot pick single items.

Part D: add quality gates (Azure DevOps)

  1. Turn on branch policies for main so nobody commits to it directly and every change needs a pull request.
  2. Add a build pipeline to that policy. Microsoft's sample runs two jobs: Tabular Editor's Best Practice Analyzer checks the semantic model, and PBI Inspector checks the report.
  3. If a rule at a high severity fails, the pull request cannot be completed.

Microsoft notes that Tabular Editor and PBI Inspector are community tools it does not support. The approach also works with other tools.

Part E: deploy to Test and Prod

  1. Option 1, deployment pipelines: promote content from Dev to Test to Prod in Fabric. You can automate it with the Power BI REST APIs or the open-source Power BI automation tools extension for Azure DevOps.
  2. Option 2, fabric-cicd: a Microsoft-backed open-source Python library that publishes semantic models and reports from a PBIP repo into a workspace. It orders items by dependency (models before reports) and swaps environment values from a parameter.yml file, for example different workspace or lakehouse IDs for dev and prod. In Microsoft's sample pipelines, the branch name picks the environment.
  3. For automated runs, use a service principal with at least the Contributor role on the target workspaces. Your tenant admin must enable service principals for Fabric APIs.

Why PBIR helps in daily work

  • Because every visual and page is its own file, Git shows exactly what changed and merges cleanly.
  • You can copy visuals, pages or bookmarks between reports.
  • You can run batch changes by script, such as setting a default page on every report.
  • VS Code can check your edits against the public JSON schema, and Desktop validates changed files when it opens the project.

Watch-outs

  • Sensitivity labels and report page synonyms (the linguistic schema) are not supported in projects.
  • Files with undocumented formats, such as mobileState.json and diagramLayout.json, should not be edited by hand.
  • Desktop-optimized-for-Report-Server does not support PBIP.
  • Converting between PBIX and PBIP only works through Save as in Desktop, not by script.
  • Row-level security role members and incremental refresh partitions cannot be read or set through the Fabric REST API.
  • Desktop publish also uploads the local data cache. Git integration and the Fabric APIs deploy only metadata, so refresh the model after the first deployment.
  • The first deployment of a model that has data sources needs credentials set by hand in the Fabric portal. Later deployments reuse them.
  • Check each item's status on the Git integration page. Some Power BI items there are labelled preview.
  • Admins: the tenant setting that converted reports to PBIR is being removed, because PBIR is no longer opt-in.

Official sources