Power BI Desktop Projects - GIT Version Control

Power BI

Introduction

There are many components that make a Power BI report. Trying to determine which component change or failure caused a problem in production can be time consuming.

Having the capability to revert back to a prior report version is critical. In this article, we are going to cover why version control is essential and which report components need to be managed. Manually managing report definitions is time-consuming and therefore skipped by most developers. While different report development lifecycle options are available, the focus remains on the Power BI Project Type. The new Power BI Project File Type solves many previous tedious tasks and allows for natural source control tool integrations. This article focuses on the citizen developer but touches on possible enterprise processes.

Note: At the time of this article creation, the Power BI Project file feature is in public preview.

Why do I need version control?

Many articles have been devoted to the subject. Here are some reasons:

The ability to roll back to a previous known working version in case of unforeseen production issues.
The ability to review the history of supporting file changes before and after development work.
Review differences between files and merge the changes.
Team members can review changes before they are released into production.
Key requirement for deployment pipeline automation.

Power BI version control requirements

There are different development options for Power BI. For example, you can implement a single-file development or shared dataset approach. Data can be sourced from files, REST API, or a data warehouse. With more than 100 data connectors, the possible project dependency options are outside the article scope. Here are some basic environment high-level dependencies to consider:

Report visualization definitions and static resources
Report model definitions and measures
Data serving layer objects (SQL)
Power BI Service Apps
Power BI Service Data Flows

Some environments and projects do not have all of these BI layer requirements. However, every Power BI project does have to manage the visualizations and model definitions. This article is going to focus on the Power BI report file, which makes up the visualizations and data model.

Power BI file types

Before choosing a version control solution, you must consider your development strategy. There are some basic Power BI file type strategies. These strategies depend on your team and data size.

PBIX - Single report file solution (report and dataset): This is great for a single developer and small teams that do not plan to share data across reports. However, as the number of reports grow and your data serving layer matures, more efficient and scalable strategies become necessary.
PBIX - Shared dataset: Report authors and data modelers are different people. One dataset may be used in multiple reports now or in the future.
PBIT - Power BI Template: This file type only contains the report definition and/or dataset. The file needs to be saved to the desktop and data imported using a live connection before the development work starts. Reports with large datasets may choose this option.

Each of these options works with a compressed file type. The version control solution should cover the entire solution as a unit of control.

Power BI version control options

Now that you picked your report development strategy, where are you going to store the files?

SharePoint or OneDrive

I have listed both of these options together because they have very similar features and capabilities. SharePoint does offer the capability to add file checkin comments in addition to version history. For this reason, I would choose a SharePoint document library over OneDrive.

Pros
- Easy to implement. In case of a production issue, the Power BI team can quickly restore from a prior version.
- View SharePoint version history comments.
- UI based. No extra commands to remember.
Cons
- Binary file format. The report definition and data model are not separated out. It is very time-consuming to compare changes over time. Files must be downloaded locally. (PBIX) The data is saved with the report file.
- Data security. If there is sensitive data that needs to be removed from history at a later time, you have to delete historical files. It is a ‘all or nothing’ approach. Your change history is gone. The ability to restore from a prior version is gone.
- Large reports can take up a lot of storage.
- No easy pipeline integration options. Heavy custom scripting is required.

Classic Git - PBIX/PBIT file strategy

Pros
- With Power BI Premium capacity, you can implement deployment pipelines. See license comparison. Note: You still have to republish Power BI Service Apps. Dependent datasets are available immediately to the App after pipeline deployment, and updated visualizations are not. There is a risk of App breaking changes.
Cons
- It is saved in a compressed format. You cannot use the normal Git tools to compare detailed changes in the report. You could not determine if one measure was changed or a table relationship was added. Every issue debugging task would start with downloading the file locally to reproduce the error instead of review the history of commits.
- Git repositories have file size limitations. Larger PBIX files would require you to enable large file format. See Git Large File Format.

Custom Scripting

Using custom scripting language like Python, C#, or PowerShell, developers can leverage interfaces like the Power BI REST API to execute pipeline tasks. Pipeline tasks, like dataset and report updates, can be automated. See Power BI REST API and REST API Deployment Pipelines.

Pros
- Power BI definitions and source code can be exported and saved as text files.
- Granular administrative actions can be executed.
Cons
- Requires custom scripting resources, development time, and maintenance. The likelihood of version control adoption will be low depending on the amount of required steps and the diversion from a typical development version control flow.

Problem statement

Managing Power BI files in a document library is fast, but will have long term downsides. Git and Github have many tools to manage and compare text readable content effectively. How can the report definition and model be managed using a version control system, like Git, easily?

Power BI Project file types

Microsoft has released a public preview of the new Power BI Project file type. Power BI authors can now save their PBIX files as PBIP files.

Project BI Project File Type

Power BI report and model definitions are saved as JSON files.

Now, individual versions differences can be merged together.

What about managing static resources like images? Those are uncompressed and available for individual commits.

Getting started

Step 1 - Enable preview feature.
Open Power BI Desktop and navigate to File | Options and settings. Select the Power BI Project save option.
Step 2 - Save the Power BI report to project file type.
Open an existing PBIX report and Save As PBIP. Notice all of the metadata has been saved to the Dataset and Report folders. This Power BI report is ready to be committed to Github.

Note: If you save your PBIX and PBIP in the same working folder, update the .gitignore file to exclude files with .pbix file extension. This is very handy if the PBIX is in the same local Git repository folder.
Step 3 - Create a Git repo and integrate it locally.
- Option 1 - Command based
  - Create a repository.
  - Clone your repository to a local report project folder.
  - Add your report files to your Git project.
- Option 2 - UI approach
  - Use Visual Studio Code to perform the steps above.
Step 4 - Make your edits and commit to Github
Open the PBIP file, make your edits, and publish your changes to the Power BI Service. Whoops, you cannot publish to the Power BI Service. The button is disabled.

The Project file type feature is in public preview. For now, continue to make your changes in the PBIX file. A possible flow might be the following steps. Test and publish your changes. After publishing, save your PBIX file to a PBIP file type. Stage, commit, and publish your changes to Github. Because you added the PBIX file extension to the .gitignore file earlier, you will not have to worry about accidentally saving the PBIX file to the repository.
Note: Any changes to the PBIP files outside of Power BI Desktop will not be reflected until the application is restarted.

Fabric Git Power BI Workspace integration

This article focuses on Power BI Project Types. However, I thought it was important to mention another method of Power BI version control. If you are developing in Fabric, then managing via Git and Workspaces is worth mentioning.

Dependencies

Premium capacity license
Fabric enabled
Active Azure account registered to the same user that is using the Fabric workspace

Note: This feature is in public preview at the moment.

Warning: “During the Commit to git process, the Fabric service deletes any files inside the item folder that aren’t part of the item definition.”

Before committing to this strategy, you should understand the limitations and requirements. There a few limitations might not work for your team, report, or model.

Feature limitations

Git recommendations

Before development create a new branch from the main branch.
Make small changes and merge back to main frequently. Avoid difficult branch testing and review.
During development, merge from main to your branch to resolve conflicts on a regular basis. Do not wait for a major push.

Summary

The new Power BI Project type holds a lot of promise. It will allow Power BI report developers to save their report versions to a source code repository, like Github, at a granular level. No longer will you be forced to save the data with the definition files. You can use the existing free tools to compare report changes. Existing deployment pipeline workflows can be leveraged instead of custom scripting.

References

The first step starts with you

Get in touch!

The bigger the challenge, the more excited we get. Don’t be shy, throw it at us. We live to build solutions that work for you now and into the future. Get to know more about who we are, what we do, and the resources on our site. Drop a line and let’s connect.

powerbi