Get started with Git integration (preview)
This article walks you through the following basic tasks in Microsoft Fabric’s Git integration tool:
It’s recommended to read the overview of Git integration before you begin.
Important
This feature is in preview.
Prerequisites
To integrate Git with your Microsoft Fabric workspace, you need to set up the following prerequisites for both Fabric and Git.
Fabric prerequisites
To access the Git integration feature, you need one of the following:
- Power BI Premium license. A Power BI premium license supports all Power BI items only.
- Fabric capacity. A Fabric capacity is required to use all supported Fabric items. If you don't have one yet, sign up for a free trial.
In addition, the following tenant switches must be enabled from the Admin portal:
- Users can create Fabric items
- Users can synchronize workspace items with their Git repositories
- For GitHub users only: Users can synchronize workspace items with GitHub repositories
These switches can be enabled by the tenant admin, capacity admin, or workspace admin, depending on your organization's settings.
Git prerequisites
Git integration is currently supported for Azure DevOps and GitHub. To use Git integration with your Fabric workspace, you need the following in either Azure DevOps or GitHub:
- An active Azure account registered to the same user that is using the Fabric workspace. Create a free account.
- Access to an existing repository.
Connect a workspace to a Git repo
Connect to a Git repo
Only a workspace admin can connect a workspace to a repository, but once connected, anyone with permission can work in the workspace. If you're not an admin, ask your admin for help with connecting. To connect a workspace to an Azure or GitHub Repo, follow these steps:
Sign into Fabric and navigate to the workspace you want to connect with.
Go to Workspace settings
Select Git integration.
Select your Git provider. Currently, Azure DevOps and GitHub are supported.
If you select Azure DevOps, select Connect to automatically sign into the Azure Repos account registered to the Microsoft Entra user signed into Fabric.
Connect to a workspace
If the workspace is already connected to GitHub, follow the instructions for Connecting to a shared workspace.
From the dropdown menu, specify the following details about the branch you want to connect to:
Note
You can only connect a workspace to one branch and one folder at a time.
- Organization
- Project
- Git repository.
- Branch (Select an existing branch using the drop-down menu, or select + New Branch to create a new branch. You can only connect to one branch at a time.)
- Folder (Type in the name of an existing folder or enter a name to create a new folder. If you leave the folder name blank, content will be created in the root folder. You can only connect to one folder at a time.)
Select Connect and sync.
During the initial sync, if either the workspace or Git branch is empty, content is copied from the nonempty location to the empty one. If both the workspace and Git branch have content, you’re asked which direction the sync should go. For more information on this initial sync, see Connect and sync.
After you connect, the Workspace displays information about source control that allows the user to view the connected branch, the status of each item in the branch and the time of the last sync.
To keep your workspace synced with the Git branch, commit any changes you make in the workspace to the Git branch, and update your workspace whenever anyone creates new commits to the Git branch.
Commit changes to git
Once you successfully connect to a Git folder, edit your workspace as usual. Any changes you save are saved in the workspace only. When you’re ready, you can commit your changes to the Git branch, or you can undo the changes and revert to the previous status. Read more about commits.
To commit your changes to the Git branch, follow these steps:
Go to the workspace.
Select the Source control icon. This icon shows the number of uncommitted changes.
Select the Changes from the Source control panel. A list appears with all the items you changed, and an icon indicating if the item is new
, modified
, conflict
, or deleted
.
Select the items you want to commit. To select all items, check the top box.
Add a comment in the box. If you don't add a comment, a default message is added automatically.
Select Commit.
After the changes are committed, the items that were committed are removed from the list, and the workspace will point to the new commit that it synced to.
After the commit is completed successfully, the status of the selected items changes from Uncommitted to Synced.
Update workspace from Git
Whenever anyone commits a new change to the connected Git branch, a notification appears in the relevant workspace. Use the Source control panel to pull the latest changes, merges, or reverts into the workspace and update live items. Read more about updating.
To update a workspace, follow these steps:
- Go to the workspace.
- Select the Source control icon.
- Select Updates from the Source control panel. A list appears with all the items that were changed in the branch since the last update.
- Select Update all.
After it updates successfully, the list of items is removed, and the workspace will point to the new commit that it's synced to.
After the update is completed successfully, the status of the items changes to Synced.
Disconnect a workspace from Git
Only a workspace admin can disconnect a workspace from an Git Repo. If you’re not an admin, ask your admin for help with disconnecting. If you’re an admin and want to disconnect your repo, follow these steps:
- Go to Workspace settings
- Select Git integration
- Select Disconnect workspace
- Select Disconnect again to confirm.
Permissions
The actions you can take on a workspace depend on the permissions you have in both the workspace and the Git repo. For a more detailed discussion of permissions, see Permissions.
Considerations and limitations
General Git integration limitations
- The authentication method in Fabric must be at least as strong as the authentication method for Git. For example, if Git requires multifactor authentication, Fabric needs to require multifactor authentication as well.
- Power BI Datasets connected to Analysis Services aren't supported at this time.
- Sovereign clouds aren't supported.
- The Azure DevOps account must be registered to the same user that is using the Fabric workspace.
- The tenant admin must enable cross-geo exports if the workspace and Git repo are in two different geographical regions.
- The commit size is limited to 125 MB.
GitHub Enterprise limitations
Some GitHub Enterprise settings aren't supported. For example:
- IP allowlist
- Private networking
Workspace limitations
- Only the workspace admin can manage the connections to the Git Repo such as connecting, disconnecting, or adding a branch.
Once connected, anyone with permission can work in the workspace. - The workspace folder structure isn't reflected in the Git repository. Workspace items in folders are exported to the root directory.
Branch and folder limitations
- Maximum length of branch name is 244 characters.
- Maximum length of full path for file names is 250 characters. Longer names fail.
- Maximum file size is 25 MB.
- You can’t download a report/dataset as .pbix from the service after deploying them with Git integration.
- When naming a folder in Git, the logical ID (Guid) is added as a prefix before the type if the item’s display name:
- Has more than 256 characters
- Ends with . or a space
- Contains any of the following characters: " / : < > \ * ? |
Branching out limitations
- Branch out requires permissions listed in permissions table.
- There must be an available capacity for this action.
- All workspace and branch naming limitations apply when branching out to a new workspace.
- When branching out, a new workspace is created and the settings from the original workspace aren't copied. Adjust any settings or definitions to ensure that the new workspace meets your organization's policies.
- Only Git supported items are available in the new workspace.
- The related branches list only shows branches and workspaces you have permission to view.
- Git integration must be enabled.
Sync and commit limitations
- You can only sync in one direction at a time. You can’t commit and update at the same time.
- Sensitivity labels aren't supported and exporting items with sensitivity labels might be disabled. To commit items that have sensitivity labels without the sensitivity label, ask your administrator for help.
- Works with limited items. Unsupported items in the folder are ignored.
- Duplicating names isn't allowed. Even if Power BI allows name duplication, the update, commit, or undo action fails.
- B2B isn’t supported.
- Conflict resolution is partially done in Git.
- During the Commit to Git process, the Fabric service deletes files inside the item folder that aren't part of the item definition. Unrelated files not in an item folder aren't deleted.
- After you commit changes, you might notice some unexpected changes to the item that you didn't make. These changes are semantically insignificant and can happen for several reasons. For example:
- Manually changing the item definition file. These changes are valid, but might be different than if done through the editors. For example, if you rename a semantic model column in Git and import this change to the workspace, the next time you commit changes to the semantic model, the bim file will register as changed and the modified column pushed to the back of the
columns
array. This is because the AS engine that generates the bim files pushes renamed columns to the end of the array. This change doesn't affect the way the item operates. - Committing a file that uses CRLF line breaks. The service uses LF (line feed) line breaks. If you had item files in the Git repo with CRLF line breaks, when you commit from the service these files are changed to LF. For example, if you open a report in desktop, save the .pbip project and upload it to Git using CRLF.
- Manually changing the item definition file. These changes are valid, but might be different than if done through the editors. For example, if you rename a semantic model column in Git and import this change to the workspace, the next time you commit changes to the semantic model, the bim file will register as changed and the modified column pushed to the back of the
- Refreshing a semantic model using the Enhanced refresh API causes a Git diff after each refresh.