Power BI Project Format (PBIP) + Git + CI/CD

The foundation of modern Power BI source control. PBIP folder structure, TMDL internals, merge strategies, and CI pipelines that validate every change.

Updated April 202617 min readBy Power BI Consulting

Quick Answer

PBIP is the Git-native Power BI save format. Every new project in 2026 should be PBIP. TMDL is the text-first format for the semantic model, and it diffs cleanly in pull requests. Combined with Fabric Git integration, CI pipelines running Tabular Editor BPA, and automated deployment via XMLA, PBIP is the foundation of enterprise Power BI ALM.

1. Anatomy of a PBIP Project

SalesAnalytics.pbip             # Project manifest (small JSON file)
SalesAnalytics.SemanticModel/
    definition/
        model.tmdl              # Root model definition
        tables/
            Customer.tmdl       # Per-table definitions
            Product.tmdl
            Sales.tmdl
            Calendar.tmdl
        cultures/
            en-US.tmdl          # Localization metadata
        relationships.tmdl      # Relationship definitions
        roles.tmdl              # RLS role definitions
    diagramLayout.json          # Model view diagram positions
SalesAnalytics.Report/
    definition.pbir             # Report definition
    report.json                 # Report structure
    StaticResources/            # Images, themes
.gitignore
README.md

2. TMDL Example

// tables/Sales.tmdl
table Sales
    lineageTag: 7f3e4d-sales-fact

    measure 'Total Revenue' = SUM(Sales[Amount])
        formatString: $#,0;-$#,0
        displayFolder: Revenue

    measure 'Total Revenue YoY %' =
        VAR Current = [Total Revenue]
        VAR Prior =
            CALCULATE([Total Revenue],
                SAMEPERIODLASTYEAR('Calendar'[Date])
            )
        RETURN DIVIDE(Current - Prior, Prior)
        formatString: 0.0%;(0.0%)
        displayFolder: Revenue

    column Amount
        dataType: decimal
        sourceColumn: Amount

    column OrderDate
        dataType: dateTime
        sourceColumn: OrderDate

    partition Sales = m
        mode: import
        source = "
            let
                Source = Sql.Database(ServerName, DatabaseName),
                FactSales = Source{[Schema=\"dbo\",Item=\"FactSales\"]}[Data]
            in
                FactSales
        "

Every object is explicit and indented. Measures, columns, partitions, and lineage tags are all visible. A code reviewer can evaluate a pull request without opening any Power BI tool.

3. Recommended .gitignore

# Power BI cache and local settings
*.pbix
*.pbit
.pbi/cache/**
*/.pbi/cache.abf
*/.pbi/localSettings.json
*/.pbi/mashup.cache

# OS
.DS_Store
Thumbs.db

# Editor
.vscode/
.idea/

Commit the TMDL and .pbip files. Exclude any binary PBIX, Power BI Desktop cache files, and local environment settings.

4. Branching Strategy

  • main: protected, requires pull request and passing CI.
  • feature branches: developers create a branch per change. Open pull requests back to main.
  • release branches: optional for major version milestones; tag with semantic versions.

For Fabric Git integration, most teams connect the Development workspace to a long-lived "workspace/dev" branch that auto-syncs. Merges from feature branches into this branch trigger the workspace to update.

5. CI Pipeline Steps

  1. Checkout: pull the feature branch.
  2. Tabular Editor BPA: run Microsoft's Best Practice Analyzer rules on the .SemanticModel folder. Fail on Critical and Major violations.
  3. TMDL lint: custom rules (naming conventions, required descriptions, forbidden patterns).
  4. DAX smoke tests: deploy to a test workspace, run expected-result queries, validate.
  5. Report JSON lint: check for hardcoded URLs, missing accessibility tags, or inconsistent themes.
  6. Status check: publish results to the pull request. Block merge if any step fails.

For detailed CI/CD examples see our deployment pipelines and CI/CD guide.

Frequently Asked Questions

What is PBIP format?

PBIP stands for Power BI Project format. It is a folder-based, text-first save format that replaces the legacy binary PBIX format for source-controlled development. A PBIP project contains a .pbip file (the project manifest), a .SemanticModel folder (TMDL definition of the model), and a .Report folder (JSON definition of the report canvas). Because every artifact is text-based, PBIP projects work naturally with Git, diff cleanly in pull requests, and merge without conflicts in most cases.

How do I enable PBIP in Power BI Desktop?

Open Power BI Desktop. Go to File > Options and Settings > Options. Select Preview features. Check "Power BI Project (.pbip) save option" and "Store semantic model using TMDL format". Restart Power BI Desktop. Now when you save, choose Save As and pick the Power BI Project format. Existing PBIX files can be converted by opening them and re-saving as .pbip.

What is TMDL?

TMDL stands for Tabular Model Definition Language. It is a human-readable YAML-like format for defining Power BI semantic models. Every table, column, measure, relationship, role, and perspective is represented as indented text. TMDL diffs are meaningful in pull requests: changing a measure formula appears as a 3-line diff, not a 50MB binary diff. TMDL is the replacement for the legacy JSON-based Tabular Model Scripting Language.

Can PBIX and PBIP coexist?

Yes, but avoid mixing them within a single project. You can have some repos in PBIX format and others in PBIP. Within one project, pick PBIP and stay with it. Power BI Desktop can open both formats, and Save As converts between them, but mixing within a Git repository creates confusion. For any new project, use PBIP.

How do PBIP merge conflicts work?

Most conflicts are text-mergeable in Git. If two developers add new measures to different display folders, the merge is automatic. If two developers modify the same measure, the conflict appears on the specific TMDL lines and can be resolved manually. The one place conflicts can be painful is the report JSON file, which is less diff-friendly than TMDL. To minimize report conflicts, avoid having multiple developers edit the same report page simultaneously; instead, have them work on different pages or different PBIP files.

Can I author TMDL directly without Power BI Desktop?

Yes. Tabular Editor 3 has full TMDL support and is often the preferred authoring environment for experienced Power BI developers. Direct TMDL editing with Tabular Editor is faster than Power BI Desktop for measure-heavy work. Power BI Desktop is better for visual report authoring and initial data import. Most teams use both: Desktop for reports, Tabular Editor for model.

How does Fabric Git integration interact with PBIP?

Fabric Git integration reads and writes PBIP format directly. When you connect a Fabric workspace to a Git repository, the workspace contents appear as PBIP folders in the repo. Changes in the workspace appear as commits. Changes pushed to the repo apply to the workspace. This means your Git repo can serve as both the source control for desktop-authored changes and the sync layer for workspace-authored changes. It is the foundation of modern Power BI ALM.

Can I validate PBIP in CI builds?

Yes. Run Tabular Editor 2 Command Line (free) against the .SemanticModel folder to execute Best Practice Analyzer rules. Parse the .Report JSON with a linter for visual-level checks. Run DAX unit tests via XMLA endpoint against a deploy-and-test workspace. Reject the pull request if any validation step fails. This is the standard enterprise CI pattern.

Moving to PBIP and Git?

Our consultants help teams migrate from PBIX to PBIP, set up Fabric Git integration, and build validation pipelines. Contact us for an ALM maturity assessment.

Ready to Transform Your Data Strategy?

Get a free consultation to discuss how Power BI and Microsoft Fabric can drive insights and growth for your organization.