Basic concepts in Git integration

This article explains basic Git concepts and the process of integrating Git with your Microsoft Fabric workspace.

Permissions

• In order to use Git integration, your organization's administrator must enable it by your organization's administrator.
• If the workspace and Azure repo are in two different regions, the tenant admin must enable cross-geo export. This restriction doesn't apply to GitHub.
• The actions you can take on a workspace depend on the permissions you have in both the workspace and Git, as listed in the next sections.

Required Git permissions for popular actions

The following list shows what different workspace roles can do depending on their permissions in their Git repo:

• Admin: Can perform any operation on the workspace, limited only by their Git role.
• Member/Contributor: Once they connect to a workspace, a member/contributor can commit and update changes, depending on their Git role. For actions related to the workspace connection (for example, connect, disconnect, or switch branches) seek help from an Admin.
• Viewer: Can't perform any actions. The viewer can't see any Git related information in the workspace.

Required Fabric permissions for popular actions

Workspace roles

The following table describes the permissions needed in the Fabric workspace to perform various common operations:

Operation	Workspace role
Connect workspace to Git repo	Admin
Sync workspace with Git repo	Admin
Disconnect workspace from Git repo	Admin
Switch branch in the workspace (or any change in connection setting)	Admin
View Git connection details	Admin, Member, Contributor
See workspace 'Git status'	Admin, Member, Contributor
Update from Git	All of the following: Contributor in the workspace (WRITE permission on all items) Owner of the item (if the tenant switch blocks updates for nonowners) BUILD on external dependencies (where applicable)
Commit workspace changes to Git	All of the following: Contributor in the workspace (WRITE permission on all items) Owner of the item (if the tenant switch blocks updates for nonowners) BUILD on external dependencies (where applicable)
Create new Git branch from within Fabric	Admin
Branch out to a new workspace	Admin, Member, Contributor

Git roles

The following table describes the Git permissions needed to perform various common operations:

Azure Repos

Operation	Git permissions
Connect workspace to Git repo	Read=Allow
Sync workspace with Git repo	Read=Allow
Disconnect workspace from Git repo	No permissions are needed
Switch branch in the workspace (or any change in connection setting)	Read=Allow (in target repo/directory/branch)
View Git connection details	Read or None
See workspace 'Git status'	Read=Allow
Update from Git	Read=Allow
Commit workspace changes to Git	Read=Allow Contribute=Allow branch policy should allow direct commit
Create new Git branch from within Fabric	Role=Write Create branch=Allow
Branch out to a new workspace	Read=Allow Create branch=Allow

GitHub Repos

• If you're using a fine-grained access token, the following permissions are needed for common operations:

  Operation	Git permissions
  Connect workspace to Git repo	Contents= Access: Read
  Sync workspace with Git repo	Contents= Access: Read
  Disconnect workspace from Git repo	No permissions are needed
  Switch branch in the workspace (or any change in connection setting)	Contents= Access: Read (in target repo/directory/branch)
  View Git connection details	Contents= Access: Read or None
  See workspace 'Git status'	Contents= Access: Read
  Update from Git	Contents= Access: Read
  Commit workspace changes to Git	Contents= Access: Read and write branch policy should allow direct commit
  Create new Git branch from within Fabric	Contents= Access: Read and write
  Branch out to a new workspace	Content=Read and write

• If you're using classic access token, the repo scope must be enabled:

  

Connect and sync

Only a workspace admin can connect a workspace to a Git Repos, but once connected, anyone with permissions can work in the workspace. If you're not an admin, ask your admin for help with connecting.

When you connect a workspace to Git, Fabric syncs between the two locations so they have the same content. During this initial sync, if either the workspace or Git branch is empty while the other has content, the content is copied from the nonempty location to the empty one. If both the workspace and Git branch have content, you have to decide which direction the sync should go.

• If you commit your workspace to the Git branch, all supported workspace content is exported to Git and overwrites the current Git content.
• If you update the workspace with the Git content, the workspace content is overwritten, and you lose your workspace content. Since a Git branch can always be restored to a previous stage while a workspace can’t, if you choose this option, you're asked to confirm.

If you don’t select which content to sync, you can’t continue to work.

Connect to a shared workspace

If you try connecting to a workspace that's already connected to Git, you might get the following message:

Go to the Accounts tab on the right side of the Source control panel, choose an account, and connect to it.

Git status

After you connect, the workspace displays a Git status column that indicates the sync state of each item in the workspace in relation to the items in the remote branch.

Each item has one of the following statuses:

• Synced (the item is the same in the workspace and Git branch)
• Conflict (the item was changed in both the workspace and Git branch)
• Unsupported item
• Uncommitted changes in the workspace
• Update required from Git
• Item is identical in both places but needs to be updated to the last commit

Sync information

As long as you’re connected, the following information appears at the bottom of your screen:

• Connected branch
• Time of last sync
• Link to the last commit that the workspace is synced to

Source control pane

On top of the screen is the Source control icon. It shows the number of items that are different in the workspace and Git branch. When changes are made either to the workspace or the Git branch, the number is updated. When the workspace is synced with the Git branch, the Source control icon displays a 0.

Select the Source control icon to open the Source control panel.

The source control pane has three tabs on the side:

• Commits and updates
• Branches
• Account details

Commits and updates

When changes are made either to the workspace or the Git branch, the source control icon shows the number of items that are different. Select the source control icon to open the Source control panel.

The Commit and update panel has two sections.

Changes shows the number of items that were changed in the workspace and need to be committed to Git.
Updates shows the number of items that were modified in the Git branch and need to be updated to the workspace.

In each section, the changed items are listed with an icon indicating the status:

• new
• modified
• deleted
• conflict

The Refresh button on top of the panel updates the list of changes and updates.

Commit

• Items in the workspace that were changed are listed in the Changes section. When there's more than one changed item, you can select which items to commit to the Git branch.
• If there were updates made to the Git branch, commits are disabled until you update your workspace.

Update

• Unlike commit and undo, the Update command always updates the entire branch and syncs to the most recent commit. You can’t select specific items to update.
• If changes were made in the workspace and in the Git branch on the same item, updates are disabled until the conflict is resolved.

Read more about how to commit and update. Read more about the update process and how to resolve conflicts.

Branches

The Branches tab of the Source control panel enables you to manage your branches and perform branch related actions. It has two main sections:

• Actions you can take on the current branch:

  • Branch out to new workspace (any role): Creates a new workspace and new branch based on the last commit of the branch connected to the current workspace. It connects to the new workspace and new branch.
  • Checkout new branch (must be workspace admin): Creates a new branch based on the last synced commit in the workspace and changes the Git connection in the current workspace. It doesn't change the workspace content.
  • Switch branch (must be workspace admin): Syncs the workspace with another new or existing branch and overrides all items in the workspace with the content of the selected branch.

  

• Related branches.
  The Branches tab also has a list of related workspaces you can select and switch to. A related workspace is one with the same connection properties as the current branch, such as the same organization, project, repository, and git folder.
  This allows you to navigate to workspaces connected to other branches related to the context of your current work, without having to look for them in your list of Fabric workspaces.
  Click on an item in the list to open the relevant workspace.

  

See Branching out limitations for more information.

Account details

The Account details tab shows details of the GitHub account that the user is connected to. It has two sections. The top section shows the Git provider and the account name. The bottom section shows the repository and branch that the workspace is connected to. Currently, this tab is only available for workspaces connected to GitHub.

GitHub account details include:

• Git account details

  • Provider
  • Account name

• Git repository

• Branch

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.
• Workspaces with template apps installed can't be connected to Git.
• Submodules aren't supported.
• Sovereign clouds aren't supported.

Azure DevOps limitations

• 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.
• If your organization set up conditional access, make sure the Power BI Service has the same conditions set for authentication to function as expected.
• The commit size is limited to 125 MB.

GitHub limitations

• Only cloud versions of GitHub are supported. On-prem isn't supported.
• GitHub can't enforce cross-geo validations.
• The total combined size of files to commit at once is limited to 50 MB. Therefore, if you have several items to commit, it might sometimes be necessary to separate them into a few separate commits. For more information about committing files, see our troubleshooting guide.

GitHub Enterprise limitations

Some GitHub Enterprise settings aren't supported. For example:

• IP allowlist
• Private networking
• Custom domains

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.
• If the item’s display name has any of these characteristics, The Git folder is renamed to the logical ID (Guid) and type:
  • Has more than 256 characters
  • Ends with a . or a space
  • Contains any forbidden characters as described in directory name limitations

Directory name limitations

• The name of the directory that connects to the Git repository has the following naming restrictions:

  • The directory name can't begin or end with a space or tab.
  • The directory name can't contain any of the following characters: " / : < > \ * ? |

• The item folder (the folder that contains the item files) can't contain any of the following characters: " : < > \ * ? |. If you rename the folder to something that includes one of these characters, Git can't connect or sync with the workspace and an error occurs.

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 project file (.pbip) and upload it to Git using CRLF.
• Refreshing a semantic model using the Enhanced refresh API causes a Git diff after each refresh.

Related content

• Manage branches
• Resolve errors and conflicts