Version Control for Power BI Development
Understanding Git, branches, commits, and collaboration
You are working as a BI Developer in a fast-paced organization where business decisions depend on accurate and up-to-date reports. Your team builds reports that help management monitor production, sales, downtime, and business performance. A few weeks later, business requests a redesign. They want a better user experience in report layout, additional filters, and visualizations. Another developer needs to add a new measure, while someone else wants to correct a calculation.
Let’s say the business is now using a report that contains an error.
You ask yourself:
- What did I change?
- Which version of the report was working correctly?
- Can I recover the previous version?
- How can I make changes without affecting the business?
- What happens when another developer is working on the same report?
These are the kinds of problems that version control is designed to help solve.
Version control provides a structured way to manage these changes. It keeps a history of development work, allows developers to work on separate changes, and helps teams review and combine their work safely. Git is one of the most widely used version control tools. Power BI supports Git-based development through its project format, PBIP, and Microsoft Fabric provides Git integration for supported workspace items
In this article, we will explore the concept step by step, using practical examples from Power BI development.
- What version control is and why Power BI developers need it.
- How Git, repositories, commits, branches, and merges work.
- How Power BI report files differ from Power BI project files.
- How to set up a development workflow.
- How developers save, review, test, and publish changes.
- How Git integration in Microsoft Fabric fits into the process.
- How to handle access and deployment.
Understanding Version control
Version control is a system that records changes made to files over time.
Instead of saving multiple files such as:
`Downtime_Report_Final.pbix`
`Downtime_Report_Final_v2.pbix`
`Downtime_Report_Final_v3_Updated.pbix`
`Downtime_Report_Final_Really_Final.pbix`
You maintain one structured history that records how the project evolved. Each recorded version represents a particular point in the development process.
Without a controlled process, a developer might overwrite a report that another developer has improved. The team may not know which version is correct or whether the latest version has been tested.
Version control helps answer five important questions:
Components of version control
To understand the full process, you need to understand six terms.
1. Git
Git is the tool that tracks changes. It records project history and allows developers to create versions, compare changes, work in separate branches, and combine their work.
Git is not the same as Power BI or Microsoft Fabric. It works alongside those tools to manage the files that make up your development project.
2. Repository
A repository, often called a repo, is the project folder together with its recorded history.
A Power BI team’s repository might contain:
- Report definitions.
- Semantic model definitions.
- Project settings and supporting files.
- Documentation.
- Relevant configuration files.
The repository can be stored on a developer’s computer and shared through a remote service such as Azure DevOps or GitHub, subject to company policy.
3. Commit
A commit is a recorded snapshot of the project at a particular point in time. For example, a developer might commit a change with the description: Improve downtime report navigationAnother commit might say:Correct production variance calculation
4. Branch
A branch is a separate line of development.
Suppose the main report is working correctly. You need to redesign its layout, but you do not want to disturb the current version while you work.
You create a branch called feature/report-redesign and make the changes there.
The existing main branch remains separate until the team reviews and accepts the redesign.
5. Merge
A merge combines changes from one branch into another. For example, after the report redesign has been reviewed and tested, the team can merge the redesign branch into the main branch.
Merging does not automatically mean the report is ready for production. Required testing and approval must still take place.
6. Remote repository
A remote repository is a shared copy of the project hosted somewhere accessible to the team. Examples include an approved Azure DevOps Git repository or GitHub repository.
When developers send their committed changes to the remote repository, teammates can access those changes according to the repository’s permissions.
How all the components work together
The following diagram shows the basic process.
In simple terms:
1. You work on the Power BI project.
2. Git detects the file changes.
3. You record a commit explaining the work.
4. You share the commit with the remote repository.
5. The team reviews and tests the changes.
6. Approved changes are merged into the main branch.
7. The release is deployed through the organization’s approved process.
Understanding the Git workflow in more detail
Git’s workflow becomes easier when you understand the four places where changes move.
Working folder
This is where you make changes to your project files. For example, you open a Power BI project and change the title of a report page from Downtime Analysis to Plant Downtime Overview.
At this stage, the file has been edited, but the change has not yet been recorded in a commit.
Staging area
The staging area allows you to choose which changes should be included in the next commit. Let’s assume you made 3
- Updated the report title.
- Corrected a measure.
- Added an experimental page that is not ready.
You may want to commit only the title update. The staging area helps you select the intended changes rather than automatically recording everything you have edited.
Local repository
Once you commit, Git records the selected changes in the history on your computer. The commit can include the author information, date, and description of the change.
For example: Redesign downtime report headerYou can create several commits locally before sharing them.
Remote repository
When you push your commits, the changes are sent to the shared repository. Your teammates can then retrieve the changes, inspect them, or use them in a review process.
Common commands
These commands require a Git repository and an appropriate local setup. If you use the Fabric web interface for Git integration, you can perform some operations through that interface instead.
Understanding branches through a practical example
Imagine three developers are working on the same Power BI report:
- Developer A is redesigning the report pages.
- Developer B is correcting a production calculation.
- Developer C is updating documentation.
If all three make changes directly to the main branch, they risk interfering with each other’s work.
Branches give each developer a separate line of development.
Recommended branch names
Use names that describe the purpose of the work.
feature/downtime-page-redesignfix/production-variance-measurefeature/inventory-trenddocs/report-maintenance-guide
A branch should have a clear purpose. This makes it easier for the team to understand what is being developed.
A branch should have a clear purpose. This makes it easier for the team to understand what is being developed.
What is the main branch? The main branch is commonly used as the central, reviewed version of a project. However, Git itself does not guarantee that main is production-ready. Your organization must establish the rules that govern which changes can be merged and released.
What is a pull request? A pull request is a request to review and merge changes from one branch into another. Azure DevOps commonly uses the term pull request, while other platforms may use different names.
A reviewer can check:
- Whether the change meets the requirement.
- Whether the report and calculations still work.
- Whether unnecessary files were changed.
- Whether the developer has documented the change.
- Whether the change is ready to merge.
A review is an opportunity to catch problems before the changes enter the central branch.
Understanding merge conflicts A merge conflict occurs when Git cannot safely decide how to combine changes.
For example, two developers edit the same part of a report definition:
- Developer A changes a page title to
Downtime Overview. - Developer B changes the same title to
Plant Downtime.
Git may need a person to decide which version is correct.
How to resolve a conflict
- Identify the files reported as conflicted.
- Compare the two changes.
- Discuss the intended outcome with the developers or business owner, if necessary.
- Edit the file to reflect the agreed result.
- Validate that the resulting project is correct.
- Complete the merge and test the report.
Do not automatically choose one side simply because it is newer. The right answer depends on the business requirement.
Power BI files: PBIX versus PBIP
This is one of the most important sections for Power BI developers.
What is a PBIX file? A .pbix file is the familiar Power BI Desktop report file. Depending on the report, it can contain report layout, semantic model information, and imported data.
Get Mbuotidem Awak’s stories in your inbox
Join Medium for free to get updates from this writer.
It is convenient for building, saving, and sharing reports. However, it is not structured like a normal folder of text files, which makes it less convenient for reviewing individual changes with Git.
What is a PBIP file? A .pbip file is a Power BI Project file. It acts as an entry point to a project structure that stores report and semantic model definitions in separate folders and files.
The difference at a glance
What does source control mean for PBIP?
Suppose you have a report with five pages. You change the title and navigation on one page. In a project-based workflow, Git can compare supported text-based report definitions to help identify what changed.
Instead of comparing two complete report files manually, the team can review changes to the relevant project files.
The ability to compare a particular change depends on how the definition is represented and which Power BI features are involved. Git should not be treated as a guarantee that every visual or model change will always appear as a simple, readable text difference.
I know this is a long read, but if you’ve made it this far, let’s wrap things up with Setting up version control for a Power BI project
This section describes a practical implementation path for a team beginning to use Git with Power BI.
The example assumes your company uses Power BI Desktop and an approved Git repository, such as Azure DevOps. Microsoft Fabric Git integration is covered separately in the next section.
Phase 1: Define the development process
Before configuring tools, agree on how the team will work.
Decide:
- Who owns the report.
- Who can change the project.
- Who reviews changes.
- Which branch is the central branch.
- What tests are required.
- Who approves production releases.
- Where the repository is hosted.
- How credentials, secrets, and sensitive information will be protected.
For example, the team might adopt this rule:
All report changes must be developed on a separate branch, reviewed by another developer, tested, and approved before being merged into the main branch.
Phase 2: Prepare the Power BI project
- Open the report in Power BI Desktop.
- Confirm that you are working with the correct report and semantic model.
- Check whether your Power BI Desktop version and organizational configuration support PBIP.
- Save or convert the report to the Power BI Project format using the available supported options.
- Review the generated project folders and files.
- Close and reopen the project to confirm it loads correctly.
- Check that the report renders and the model behaves as expected.
Phase 3: Create or select the shared repository
Your organization may already have an Azure DevOps or GitHub repository for Power BI development. If so, follow the existing project standards rather than creating an unapproved repository.
If a new repository is required:
- Create it in the approved organization or project.
- Set the repository name, for example
powerbi-finance-reports. - Configure permissions for developers and reviewers.
- Decide how branches will be protected.
- Add the Power BI project files.
- Add a README file explaining the project and its purpose.
- Commit the initial project version.
Avoid storing passwords, access tokens, private keys, or other secrets in the repository.
Phase 4: Record the initial version
The first commit should establish a clear starting point.
Example commit message: Initial version of operations downtime report
The initial commit gives the team a known baseline against which later changes can be compared. Before proceeding, confirm that the repository contains the expected project files and that authorized team members can access it.
Phase 5: Create a branch for a change
Suppose the business requests a redesign of the downtime report.
Create a branch such as: feature/downtime-report-redesign
Keep the work focused on the redesign rather than mixing it with unrelated changes. If another developer needs to correct a measure, that developer can use a separate branch: fix/downtime-duration-measure
Phase 6: Make and record changes
The developer updates the report in Power BI Desktop, then checks the project changes using Git or the team’s approved interface.
A sensible sequence is:
- Make a small, focused change.
- Open the report and validate it.
- Inspect the changed project files.
- Select the intended changes.
- Commit with a meaningful description.
- Repeat for the next logical change.
Phase 7: Share the branch and request review
Push the branch to the remote repository and open a pull request if your team’s workflow uses pull requests.
Include:
- The business reason for the change.
- The pages, visuals, or calculations affected.
- A summary of the changes.
- Test results.
- Screenshots or other supporting evidence when useful.
Phase 8: Test before merging
For a Power BI report, testing should include more than checking whether the file opens.
Use the following checklist as a starting point:
- Report validation checklist
- The project opens successfully in Power BI Desktop.
- All required report pages load correctly.
- Visuals display the expected data.
- Slicers and filters behave as intended.
- Measures and calculations return the expected results.
- Drill-through, tooltips and navigation work where applicable.
- Data refresh and source connections work in the target environment.
- The change has been reviewed and business requirements are met.
0 of 8 checks completed
Reset
Adapt the checklist to the report. For example, a report using DirectQuery, imported data, row-level security, or complex measures may need additional tests.
Phase 9: Merge the approved change
Once the reviewer has approved the changes and the required checks have passed, merge the branch into the main branch according to the team’s process.
If the review identifies an issue, return to the development branch, fix the issue, commit the fix, and request another review.
Phase 10: Deploy the change
Merging into Git does not, by itself, publish a report to Power BI Service. The release process is a separate step. Depending on the environment, the team may use Power BI publishing, Fabric deployment pipelines, Git-based deployment automation, or another approved release method.
After deployment, validate the report in the target workspace and confirm that permissions, connections, refresh settings, and user access remain correct.
Additional resources
Explore the resources below to deepen your understanding and continue learning.
Git documentation
Understand project structure and source-control support.
Fabric Git integration guide
GitHub’s beginner guide
Follow me on LinkedIn and Twitter for more updates.
