Git Integration Workflow

What Git integration connects

Git integration exists so that several developers can change the same Fabric content safely: every change has a history, a review, and a way back. The integration works at the workspace level. Developers version the items of a workspace in a single process, and the workspace structure, including subfolders, is preserved in the repository.

The supported Git providers are Azure DevOps, GitHub, and GitHub Enterprise, and each one is supported in its cloud-based version only. An on-premises server is not an option, and neither is a GitHub Enterprise Server on a private network.

Two things must be in place before anyone connects:

• A Fabric capacity, which is needed to use Git integration.
• The tenant switch Users can synchronize workspace items with their Git repositories. GitHub users need a second switch that allows synchronization with GitHub repositories.

The connection itself is narrow. A workspace connects to one branch and one folder at a time. The repository can hold many branches and many folders, but the workspace follows only the pair chosen in workspace settings. If the folder name is left blank, the content is created in the root folder.

Not every item type supports Git. A workspace with unsupported items can still be connected, and the rule for those items is simple: unsupported items are ignored. They are not saved or synced, and they are not deleted either. They appear in the Source control panel, but you can't commit or update them.

Some supported item types are still in preview for Git integration, so check the list of supported items before you plan a workspace around it.

Who can do what

What you can do depends on two sets of permissions at once: your workspace role in Fabric and your permissions in the Git repository. The Fabric side is the one that exam scenarios test most.

In words: only a workspace Admin can connect a workspace to a repository, sync it, or disconnect it. The Contributor role, with write permission on all items, is enough to commit and to update. A Viewer can't perform any Git action and can't see any Git information in the workspace.

Two extra conditions can apply to commit and update. If a tenant switch blocks updates by nonowners, you must also be the owner of the item, and where an item has external dependencies you need Build permission on them.

Changing the branch of a connected workspace is the operation with an exception. By default, Switch branch and Checkout new branch require the Admin role. A workspace Admin can turn on the workspace setting Allow users with at least Contributor role to change Git branch. When it is on, Members and Contributors who have write access to all items can switch branches and check out new branches.

Three details about that setting:

• It is configured per workspace. There is no tenant-level switch for it.
• It requires an active Git connection on the workspace.
• It does not change who can connect or disconnect: those actions stay Admin-only.

On the Git side, the pattern is read versus write. In Azure Repos, updating from Git needs only Read. Committing needs Read and Contribute, and the branch policy must allow direct commits.

Connect and sync

A workspace Admin connects from Workspace settings, under Git integration: choose the provider, the repository, the branch, and the folder, and then select Connect and sync. The first sync makes the two locations hold the same content, and what it does depends on what is already there.

If both the workspace and the Git branch have content, you have to decide which direction the sync goes. Fabric does not merge the two sets. Committing the workspace exports all supported workspace content to Git and overwrites the current Git content. Updating the workspace overwrites the workspace content with the Git content.

The second direction is the risky one. A Git branch can always be restored to a previous state, while a workspace can't, so Fabric asks you to confirm before an update overwrites the workspace.

One more point for shared workspaces: the Git connection is per user. Each person who works in a connected workspace configures their own connection to the provider.

Read the Git status

After the connection, the workspace shows a Git status column. It compares each item in the workspace with the same item in the connected branch, and it tells you which button you need next.

The Source control icon at the top of the workspace shows the number of items that differ between the workspace and the branch. When everything is synced, it displays a 0. Its panel has two lists: Changes, for items changed in the workspace that need a commit, and Updates, for items changed in the branch that need to be pulled into the workspace.

Commit, update, and undo

Anything you save in a connected workspace is saved in the workspace only. It reaches Git when you commit it, and three commands manage that gap.

Commit sends workspace changes to the branch, and it is selective: when more than one item changed, you choose which items to commit. There is one block to know. If there are new commits in the Git branch, Commit is disabled until you update the workspace.

Update pulls the branch into the workspace, and it is not selective. Update always updates the entire branch and syncs to the most recent commit. You can't select specific items to update. If the same item changed in the workspace and in the branch, Update is disabled until the conflict is resolved.

You can sync in only one direction at a time: you can't commit and update together.

Undo throws away saved workspace changes that you decide not to commit. The selected items revert to how they were when the workspace was last synced. Take care with new items: undoing an added item permanently deletes it.

A variant helps when Commit is blocked. Commit to new branch creates a new branch from the last synced state and commits your changes there in one action. It works even when incoming updates disable the normal commit. The new branch is not connected to the workspace, and the workspace state does not change.

Resolve a conflict

A conflict occurs when the same item changes in both the workspace and the Git branch. The item shows the status Conflict, and Commit is disabled. When you select Update, a Resolve Conflicts button appears, and it lists every conflicted item with two choices.

Keep current content keeps the workspace version, and after the update the item's status becomes Uncommitted changes, because the workspace version is not committed to the branch yet. Accept incoming changes ends in Synced.

A second way is to revert one side. Undo returns conflicted items in the workspace to their last synced state, which loses the workspace changes. In Azure DevOps, the git revert command takes the branch back instead.

Two more paths exist, and they are opposites in how much they keep.

Disconnecting and reconnecting the workspace lets you choose a sync direction again. It is a blunt tool: reconnecting overwrites all items in the workspace or in the branch, not just the conflicted ones.

Resolving in Git keeps both sets of changes. Use it when you are not sure which version to keep and don't want to revert:

1. From the Source control panel, check out a new branch that starts at the last synced commit.
2. Commit your workspace changes into that new branch.
3. In Git, resolve the conflicts and merge the new branch into the original branch.
4. In Fabric, switch the workspace back to the original branch.

Checking out a new branch keeps the current workspace state, so uncommitted changes are retained. That is why this path loses nothing.

Branch out, check out, and switch

The Branches tab of the Source control panel offers three actions. They sound alike, and they differ in which workspace they touch and whether its content changes.

Branch out to another workspace creates a new branched workspace, or reuses an existing one, and connects it to a new Git branch based on the last commit of the source workspace. The source workspace keeps its branch. Creating a new workspace this way also needs the tenant switch Create workspaces.

Checkout new branch creates a branch from the last synced commit and changes the Git connection of the current workspace. It doesn't change the workspace content.

Switch branch overrides all items in the workspace with the content of the selected branch.

Each action has a catch that decides real cases.

• You can't switch branches if the workspace has uncommitted changes. Commit them first, and then switch.
• When you switch, an item that exists in the old branch but not in the new one is deleted from the workspace. The new branch must also contain the same directory as the current one.
• Branch out asks whether to create a new workspace or to use an existing one. By default, all items of the source branch arrive in the target workspace. The preview option Select items individually brings only the items you choose, and all their dependencies are required.
• When you branch out to an existing workspace, items there that aren't saved to Git might be deleted. Commit what you want to keep before you start. You must be an Admin of that target workspace, or a Member or Contributor there with the change-branch setting on.
• Branch out needs an available capacity, and only items that Git supports are available in the new workspace.

What travels with each item

Git stores item definitions, not data. That one sentence explains most surprises after a sync, and two item types show it best.

For a lakehouse, only metadata is tracked: the display name, the description, a logical GUID that identifies the lakehouse across workspaces, SQL analytics endpoint metadata, and OneLake shortcuts metadata.

Tables and the folders in the Files section are not tracked or versioned in Git. Their data is always preserved during Git operations: a sync never overwrites it, and a sync never copies it to another workspace either. Shortcut definitions do travel, and a Git update overrides the state of the shortcuts in the workspace: they are created, updated, or deleted to match the incoming state.

For a notebook, Git stores source files. A committed notebook is stored as a source file such as notebook-content.py, not as a standard .ipynb file, because that format is easier to review in a Git diff. The file keeps the notebook metadata, including the default lakehouse and the attached environment, together with the markdown cells and the code cells.

Two consequences follow:

• Notebook cell output isn't included when syncing to Git. Results stay in the workspace where the notebook ran.
• The default lakehouse ID stays in the notebook metadata when you sync to another workspace, so you may need to bind the notebook to the new lakehouse by hand. Lakehouse Auto-Binding, enabled in the notebook settings, lets Fabric resolve the correct default lakehouse for each Git-connected workspace.

The general rule also covers recovery: Git integration re-creates item definitions only and does not restore item data.

Limits to plan around

Most Git integration failures in a large project come from a limit that nobody checked. These are the numbers worth knowing.

A workspace can contain a maximum of 1,000 items, and if the Git branch contains more than 1,000 items, syncing the content to the workspace fails. The fix is to split the items across workspaces linked to different branches, or across folders of one branch. The maximum file size is 25 MB. A single commit is limited to 125 MB with Azure DevOps and a user account, 25 MB with Azure DevOps and a service principal, and 50 MB with GitHub, so a large change on GitHub may need several commits. A branch name can have up to 244 characters, the full path of a file name can have up to 250 characters, and folder structure is kept up to 10 levels deep.

Some setups are not supported at all:

• Sovereign clouds, B2B users, and Git submodules.
• MyWorkspace, which can't connect to a Git provider.
• Workspaces with template apps installed.

Three more rules affect daily work:

• Cross-geo: if the workspace and an Azure DevOps repository are in different regions, the tenant admin must enable cross-geo export. This restriction does not apply to GitHub.
• Sensitivity labels are not supported, and exporting items that carry a label might be disabled.
• Duplicate names are not allowed: an update, commit, or undo fails if two items share a name.

Key takeaways

• Connection: Git integration supports Azure DevOps, GitHub, and GitHub Enterprise in their cloud versions, and only a workspace Admin can connect a workspace.
• First sync: if both the workspace and the branch have content, you choose which side overwrites the other.
• Commit and update: Commit is disabled while the branch has new commits. Update always brings the entire branch.
• Conflicts: Keep current content ends in Uncommitted changes. To keep both versions, check out a new branch, commit there, merge in Git, and switch back.
• Branch switching: it is Admin-only unless the workspace setting that delegates it to Contributors is on.
• Per item: a lakehouse sends only metadata to Git, never table data, and a notebook is stored as a source file, not as an .ipynb file.
• Limits: a workspace holds at most 1,000 items, so a branch with more items fails to sync until the items are split.