Version Control with Git for Power BI Projects: A New Approach

As Power BI becomes more integral to enterprise data reporting, managing and versioning Power BI reports has traditionally been a challenge for development teams. The traditional Power BI file format (.PBIX) wasn’t designed for collaboration or version control, leading to difficulties when multiple developers worked on the same reports. 

Enter Power BI Project Files (.PBIP) and Git integration. With this new feature, Power BI developers can finally collaborate effectively using modern source control systems like Git. In this blog, we’ll walk through how to use Git for Power BI Projects, showcasing best practices for setting up workflows and handling common challenges that arise during development. 

Goodbye PBIX, Hello PBIP 

Historically, versioning Power BI reports involved managing large, opaque PBIX files. These files bundled all the report elements—data models, visualizations, queries—into a single binary file, making it impossible to track granular changes, such as edits to individual queries or report elements. 

To address these issues, Microsoft introduced Power BI Project files (.PBIP), which breaks down the PBIX file into individual text files. These files store metadata about the report and data model in JSON and TMDL format, making them easier to manage and version with Git or other source control systems. 

Here’s what’s new with Power BI Projects: 

• Text-Formatted Files: Each report and semantic model element is saved as a separate, human-readable JSON file. 
• Git Integration: These JSON files can be tracked in Git, allowing developers to manage versions, collaborate through branching and merging, and review changes through pull requests. 
• External Tool Support: You can use tools like Visual Studio Code to view and edit the report structure, helping you manage changes outside of Power BI Desktop. 

Setting Up Git for Power BI Projects 

In this section, we’ll walk through the steps to set up Git integration for a Power BI project, from creating a branch to merging changes into the main repository. Before diving into version control and collaboration, it’s important to set up your Power BI Project file (PBIP) correctly. If you’re working on a new project or converting an existing Power BI file (PBIX), follow these steps to save your project in the new Power BI Project format and get it ready for Git integration. 

Step 1: Enable Power BI Project File in Power BI Desktop 

Power BI Project files (.PBIP) are currently a preview feature in Power BI Desktop, so you’ll need to enable it before saving your work as a project: 

• Navigate to File > Options and settings > Options > Preview features. 
• Check the box next to Power BI Project (.pbip) save option to enable the feature. 

This will allow you to save your Power BI report and data model as a project file, breaking them into individual text files for easier version control. 

Step 2: Save Your Power BI File as a Project 

Once the feature is enabled, you can save your work as a project: 

1. Open your Power BI Desktop file (PBIX), or start a new Power BI project. 
2. To save it as a project, go to File > Save as, and choose Power BI Project (.PBIP) as the file type. 

When you save the file, Power BI Desktop creates a folder structure containing individual text files that represent different parts of your report, such as: 

• <project name>.SemanticModel: Contains files related to the semantic model. 
• <project name>.Report: Contains files related to the Power BI report. 

Power BI Desktop automatically generates a .gitignore file to exclude unnecessary files, such as localSettings.json and cache.abf, from Git tracking. 

Step 3: Viewing Your Power BI Project Structure 

After saving your Power BI file as a project, you’ll notice some changes: 

• Title Bar Indicator: The Power BI Desktop title bar will show that you’re working on a project file. Clicking on the title bar will open a flyout with options to locate project files or open the folder in File Explorer. 

• Project Folder Structure: In File Explorer, you can view the folder structure that Power BI Desktop has created. The report elements are split into multiple folders and files, each containing JSON or other metadata formats that can be edited externally if needed. 

Step 4: Set Up Your Git Repository 

Once your Power BI project is saved in its new structure, it’s ready to be tracked in Git. Here’s how to set up Git: 

1. Initialize a Git Repository: If your project isn’t already tracked by Git, open the terminal or Git Bash and navigate to your project folder, then initialize a repository:
   git init
2. Clone Your Repository: If your project is already in a remote Git repository, clone the repo to your local machine:
   git clone https://your-repo-url
3. Commit Your Project Files: After saving the Power BI project and setting up the Git repository, commit the relevant project files to Git. Be sure to review the .gitignore file to ensure unnecessary files are excluded:
   git add .
   git commit -m “Initial commit of Power BI project” 

Step 5: Create a Feature Branch 

When starting work on a new feature or report modification, always create a new branch: 

1. In Visual Studio Code, ensure you’re on the latest version of the main branch by pulling the latest changes. 
2. Create a new branch with a meaningful name, such as feature/new-report-section:
   git checkout -b feature/new-report-section
3. Open the Power BI Project file in Power BI Desktop and make the necessary changes to your report. 

Step 6: Commit and Push Changes 

After making the desired changes in Power BI, save your work, and return to Visual Studio Code: 

1. Stage the modified files using the Git Source Control tab in VS Code. 
2. Write a meaningful commit message describing the changes made:
   git commit -m “Added new report section for quarterly sales”
3. Push your changes to the remote repository:
   git push origin feature/new-report-section

Step 7: Create a Pull Request 

Once your changes are pushed, you’ll want to merge them back into the main branch through a pull request: 

1. Go to your repository in Azure DevOps or GitHub and create a pull request. 
2. Review the changes and request approval from your peers, if necessary. 
3. Once approved, merge the changes into the main branch. 

Overcoming Common Pitfalls 

While Git integration with Power BI has made collaboration easier, it’s not without its challenges. Here are a few issues you might encounter, and how to address them: 

1. Sync Issues: Avoid using cloud-synced directories like OneDrive or SharePoint for your Git repository. These can cause conflicts with Git, leading to corrupted files or out-of-sync branches. Instead, store your repository locally or on Azure DevOps, Github or equivalent to prevent these issues.
2. Editing Files with External Tools: Not all files in Power BI Projects are meant to be edited outside of Power BI Desktop. Unsupported changes made in external tools like Visual Studio Code can result in errors or prevent Power BI Desktop from opening the project. Stick to modifying only supported files, such as JSON files for model and report definitions, and always test changes in Power BI Desktop after editing.
3. Handling Line Endings: Power BI Desktop uses CRLF as the end-of-line format. To avoid unnecessary diffs and potential issues with line endings, configure Git to handle line endings automatically by enabling autocrlf. On windows, it’s as easy as running
   git config –global core.autocrlf true 

Deploying Power BI Projects  

There’s a couple of ways we can deploy Power BI Projects to a PowerBI Workspace. 

1. Git Integration with Workspaces:
   Sync specific branches with a workspace. This would result in several branches you would want to protect from directly committing to. One for each workspace you would like to sync your reports to. E.g.: dev/tst/acc/prd
   This feature is still in preview and has a lot of prerequisites, such as Fabric
   Capacity or Premium Per User Workspaces, but seems to work stable already. I think it has the most potential for Power BI Developers who are not entirely familiar with Devops.
   This method opens up the possibility to replace parameters or datasources using an Azure Devops Pipeline (or Github Action) after your PR is approved. 
   Read more on https://learn.microsoft.com/en-us/fabric/cicd/git-integration/intro-to-git-integration?tabs=azure-devops
2. Deploy using a service principal from Azure Devops. Program manager Rui Romano from the Power BI Team shared a sample Azure Devops Pipeline on Github, which can be used and adjusted for this: https://github.com/microsoft/Analysis-Services/blob/master/pbidevmode/sample-ado-pipelines/DeployPBIP.yml
   However, there is a big downside when using this approach:
   Whenever you deploy to a workspace, the service principal becomes owner of the Semantic Model. But if the data sources of that semantic model require an external login (which they usually do), you need to log in to the workspace on powerbi, take over ownership of the report and log in to those data sources. But after your next deploy, the service principal will have taken over your Semantic model again, and you need to start the cycle again. So, not ideal. 
3. The option we eventually went for with our client: Classic Power BI Deployment pipelines.
   
   A feature that has been a staple for Deploying Power BI Reports to different workspaces but is firmly locked within the web ui. It does enable us to replace parameters and data sources across environments with deployment rules.
   The flow for a PowerBI developer goes like this: 

• Create a feature branch to develop your changes to the report/model. 
• Have your colleagues review your changes by means of a pull request to the main branch. 
• After your changes are approved, you are responsible for deploying it to the development workspace, after which it is the responsibility of the release manager to deploy the reports to tst,acc & prd using the classic deployment pipeline. 

Conclusion: Git and Power BI—A Powerful Combination 

The introduction of Power BI Projects and Git integration is a significant leap forward in how Power BI developers collaborate on reports. By breaking down PBIX files into text-based JSON files, Microsoft has made it possible to bring version control, branching, and merging into the Power BI development lifecycle. 

While the features are still in preview and have some rough edges, they already offer tremendous benefits for teams looking to streamline their workflows. As this feature evolves, we can expect even more improvements that make Git and Power BI a natural fit for CI/CD pipelines and enterprise-level development.