How to Add Power BI Project in GitHub

Tired of managing file versions like Final_Report_v2.pbix, Final_Report_v3_USE_THIS_ONE.pbix, and Final_Report_v3_absolute_final.pbix? You can bring the sanity of software development version control to your business intelligence work by integrating Power BI with GitHub. This article will walk you through exactly how to set up your Power BI projects in GitHub for seamless version tracking, collaboration, and peace of mind.

Why Bother Putting Power BI on GitHub?

For years, Power BI files (.pbix) have been a bit of a challenge for version control. They were single, large binary files - essentially black boxes that tools like Git couldn't properly read. If you wanted to see what changed between two versions, you had to open both files side-by-side and manually hunt for differences. Collaboration meant emailing files back and forth, leading to confusion about which version was the most current.

That all changed when Microsoft introduced Power BI Project files (.pbip). Instead of being one monolithic file, a .pbip saves your report as a folder containing separate, human-readable definition files (mostly JSON text files). This structure is perfect for version control systems like Git because they excel at tracking line-by-line changes in text.

Connecting Power BI to GitHub gives you several powerful advantages:

Complete Version History: Every change you make and save (a "commit" in Git terms) is recorded. You can look back at the entire history, see who changed what and when, and revert to any previous version if a mistake is made.
Meaningful Change Tracking: Instead of guessing what's different, you can see the exact code that was modified. Did someone change a DAX measure from a SUM to an AVERAGE? GitHub will show you that specific line change in the dataset definition file.
Improved Collaboration: Team members can work on different parts of a report simultaneously using branches. They can then merge their changes together in a controlled way, reducing the risk of overwriting each other's work. Pull requests allow for code reviews on DAX measures or report layouts before they become official.
A Single Source of Truth: No more wondering if you have the latest file. The main branch in your GitHub repository becomes the undisputed, authoritative version of your report.

Prerequisites: What You’ll Need Before You Start

Before you get started, make sure you have the following ready to go. Everything is free to get started with.

Power BI Desktop: The latest version, installed on your computer.
A GitHub Account: If you don't have one, you can sign up for free at github.com/join.
Git Installed: To save your project locally and send it to GitHub, you need Git. You can either use a visual client like GitHub Desktop (recommended for beginners) or install Git to use from the command line.

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

The ability to save as a .pbip file is currently a preview feature in Power BI Desktop, so you need to enable it first. It only takes a second.

Open Power BI Desktop.
Go to File > Options and settings > Options.
In the Options window, go to the Preview features section.
Check the box next to "Power BI Project (.pbip) save option".
Click OK and then restart Power BI Desktop for the change to take effect.

Once you restart, you’ll have a new option in your "Save as" menu.

Step 2: Save Your Report as a Power BI Project (.pbip)

Now, let's convert a standard .pbix file into the new project format. You can either open an existing report you want to put under version control or start a new one.

With your report open, go to File > Save as.
In the "Save as type" dropdown menu, you will now see "Power BI project file (*.pbip)". Select it.
Choose a location on your computer to save the project and click Save.

Instead of a single .pbix file, Power BI will create a folder that contains your project files. For instance, if you save your file as "Monthly Sales Report," you’ll get a new folder named "Monthly Sales Report" with all the project components inside.

You’ll notice that the main file is Monthly Sales Report.pbip. This is a very small pointer file, the real magic is inside the subfolders that were created alongside it.

Step 3: What’s Inside a .pbip Folder?

When you look inside the new project folder, you’ll see a specific structure. The two most important subfolders are the ones named after your report and dataset:

[Your_Report_Name].Report: This contains the definition for your report canvas - its pages, visuals, layouts, and formatting. The most important file here is report.json. This file details everything about your report visuals. When you move a chart, change a color, or add a text box, the changes are recorded inside this JSON file.
[Your_Report_Name].Dataset: This holds the definition of your data model. It includes information about your data sources, Power Query transformations, table relationships, and all your DAX measures. Any change to your data model will be captured here.

These plain text files (especially report.json) are exactly what GitHub needs to track changes effectively.

Step 4: Setting Up Your GitHub Repository

Now let's create a home for our project on GitHub.

Log in to your GitHub account.
In the top-right corner, click the "+" icon and select "New repository."
Give your repository a name (e.g., "power-bi-sales-reports").
You can add a short description. It's good practice.
Choose whether to make it Public or Private. For work projects, you'll usually want Private.
Important: Initialize the repository with a README file and a .gitignore file. For the .gitignore template, select "Visual Studio" as it’s a good starting point for filtering out unnecessary developer files that Windows might create. We may need to add to it later.
Click "Create repository."

Step 5: Connecting Your Local Project to GitHub

You've got your Power BI project saved locally and a blank repository waiting on GitHub. Now it's time to connect the two. We’ll cover the user-friendly approach with GitHub Desktop.

Using GitHub Desktop (The Easy Way)

GitHub Desktop provides a visual interface for Git commands, which makes the whole process simpler.

Open the GitHub Desktop application.
Go to File > Clone repository.
Select the repository you just created on GitHub from the list and choose a local path where you want to store it on your computer. Click Clone.
Now, navigate to where you originally saved your .pbip project files. Copy the contents of that folder (including the .pbip file and the subfolders).
Paste these copied files and folders into the new repository folder that GitHub Desktop just created.
Switch back to GitHub Desktop. You’ll see a list of all your new files light up under the "Changes" tab. Essentially, Git has detected that you added a bunch of new files to the folder.
In the bottom-left corner, you'll see a summary box. This is where you package your changes into a commit. Write a short, descriptive summary like "Initial commit of sales report project."
Click the "Commit to main" button. This saves a snapshot of your project in your local Git history.
Finally, click the "Push origin" button at the top of the window. This "pushes" your local commit up to the GitHub server.

Go back to your repository page on GitHub and refresh it. You'll now see all your Power BI project files safely stored online!

Step 6: Making and Tracking Your First Change

This is where it all comes together. Let’s make a small change to our report and see how Git and GitHub track it.

In Power BI Desktop, open your .pbip project file.
Make a simple, visible change. For example, change the title of a visual or the color of a bar chart.
Save your report (Ctrl + S).
Now, go back to GitHub Desktop. You'll see one or more files listed under "Changes". If you changed a visual, you’ll almost certainly see report.json listed.
Click on report.json. GitHub Desktop will show you a "diff" - a color-coded comparison of the file before and after your change. The removed lines appear in red, and the added lines appear in green. You will be able to pinpoint the exact line of code representing the color change you just made.
Satisfied with the change? Write a commit message describing what you did (e.g., "Updated theme color for main sales chart").
Click "Commit to main" and then "Push origin."

You've now successfully updated your project and have a historical record of what was changed and why. If that color change turned out to be a mistake, you could easily revert to the previous commit.

Best Practices for Managing Power BI Projects in GitHub

To get the most out of this setup, keep these tips in mind:

Write Clear Commit Messages: A message like "updated report" isn't helpful. Be specific yet concise: "Added conditional formatting to sales table" or "Fixed DAX measure for YTD profit." This context is invaluable when looking back through the history.
Use Branches for New Features: Instead of committing everything directly to your main branch, create a separate branch when working on a significant new feature (like building a new report page). This keeps your main branch stable while you experiment. Once your feature is complete and tested, you can merge the branch back into main.
Commit Frequently: Save your work in small, logical chunks. Don't wait until you've made 50 changes to commit everything at once. Committing after completing a single task (e.g., finishing one DAX measure, or finalizing one visual) makes your history much easier to read and troubleshoot.

Final Thoughts

By connecting Power BI Desktop to GitHub using the .pbip file format, you elevate your report creation from a solo, error-prone craft into a structured, collaborative engineering process. You gain a powerful safety net with a full version history, clear insight into every change, and a framework for your team to work together efficiently.

Just as GitHub and Power BI bring structure and clarity to your reporting projects, we believe the process of getting insights from your data should be simple and frictionless. We built Graphed to do just that by connecting all your scattered marketing and sales data sources into one place. This lets you create reports and ask questions in plain English - no technical skill required. You can have a real-time, cross-platform dashboard up and running in seconds, giving you back the time to make decisions instead of wrestling with data.