DevOps & Observability

Git Integration in Microsoft Fabric: A Practical Development Workflow

How Fabric Git integration really works day to day: workspace and branch, commit and update, branching out, pull requests, conflicts, drift and permissions.

By JaviPublished 11 min readIntermediate

Fabric Git integration is the feature that lets a team stop treating a workspace as the only copy of their work. Notebooks, pipelines, semantic models, reports, Lakehouse and Warehouse definitions become files in a Git repository, with history, branches and pull requests.

It is also easy to misuse. Teams connect a shared workspace to main, let five people edit it, and discover that Git integration did not give them isolation, review or deployment. It gave them version history of a shared mess.

This guide is about the development workflow: how a change moves from an engineer’s workspace into a reviewed commit on main. Promoting that commit to QA and production is a separate job, covered in Microsoft Fabric CI/CD with fabric-cicd. Keeping those two responsibilities apart is the most important idea in this article.

What Fabric Git integration does

Git integration works at the workspace level. A workspace is connected to one Git repository, one branch and one folder in that repository. Once connected:

  • Each supported item is serialized to a folder of files: a .platform metadata file plus definition files such as notebook-content.py, pipeline-content.json, or TMDL files for a semantic model.
  • Workspace folders are mirrored as folders in Git, up to ten levels deep.
  • A Source control panel shows which items changed in the workspace (to commit) and which changed in the branch (to update).
  • You can commit workspace changes to the branch and update the workspace from the branch.

Supported providers are Azure DevOps, GitHub and GitHub Enterprise, all in their cloud versions. Most common data engineering items are supported, including Lakehouses, notebooks, Spark job definitions, Environments, pipelines, Dataflow Gen2, Warehouses, semantic models and reports, although some item types are still in preview. Check the current list before you depend on a specific item.

What it does not do

Git integration is source control and synchronization. It is not:

  • A deployment tool. It does not promote a commit to QA or production, replace environment-specific IDs, or decide which workspace gets which version. That is what deployment pipelines or fabric-cicd are for.
  • A data backup. It versions item definitions, not data. Lakehouse tables, files in the Files area and Spark views are not tracked; updating a workspace from Git does not overwrite or restore them. A Warehouse is committed as a database project (its schema), not its rows.
  • A review process on its own. Committing from the workspace straight to main is possible, and it skips review entirely unless branch policies stop it.
  • Isolation. One workspace is one runtime. Everyone working in it shares the same items, whatever branch it is connected to.

Once that boundary is clear, the rest of the workflow follows.

Workspace and branch: the one rule that matters

A workspace can be connected to one branch at a time, and every change made in the workspace affects everyone who uses it. Microsoft’s own guidance is therefore that developers should work in separate workspaces, each connected to its own branch, rather than many people sharing one.

That gives a simple rule:

One active change, one branch, one workspace.

The rule produces this flow:

  1. 1Feature branch
  2. 2Fabric development workspaceConnected to the feature branch
  3. 3Edit and test items in the workspace
  4. 4Commit from the Source control panel
  5. 5Pull request into main
  6. 6Review and merge
  7. 7Deployment processQA, then production
Feature-branch workflow

The deployment step at the end is deliberately not part of Git integration. Deployed workspaces are not connected to Git; they are updated by the release pipeline from a reviewed commit.

Setting up a development workspace

A workspace admin connects the workspace to a repository, branch and folder from Workspace settings → Git integration. Point the folder at the directory your deployment tooling reads (for example a workspace/ folder), so what developers commit is exactly what the pipeline deploys.

On the first connection, Fabric syncs the two sides:

  • If either the workspace or the branch is empty, content is copied from the non-empty side.
  • If both have content, you choose the direction. Committing the workspace overwrites the branch content; updating the workspace from Git overwrites the workspace content.

Read that choice carefully. A Git branch can always be restored to an earlier commit; a workspace overwritten by an update cannot. When in doubt, commit the workspace to a new branch first.

The Git connection is per user. Each person working in a connected workspace authenticates to the Git provider with their own account. Do not share a personal access token across a team.

Branch-per-developer or a shared development workspace

There are two common development setups.

Branch per developer (recommended). Each engineer uses the Branch out action in the Source control panel. Fabric creates a new Git branch from the last commit of the source workspace and either creates a new workspace connected to it or switches an existing one. The new workspace is linked to its source as a branch workspace, which makes it easy to navigate back. Selective branching lets you bring only some items into the new workspace, as long as you also select their dependencies.

Advantages: real isolation, small focused pull requests, and no one overwrites anyone else’s notebook. Cost: more workspaces, and each one needs its own data to test against.

Shared development workspace. One workspace connected to a shared dev branch, used by a small team. It is simpler, and it works when two or three people coordinate closely. It breaks down as the team grows: one person’s half-finished change is everyone’s problem, commits mix unrelated work, and reviews become meaningless.

A practical compromise is a shared integration workspace that only receives merged changes, plus individual branch workspaces for editing. Nobody edits the integration workspace directly; it is updated from main and used to check that merged work fits together.

Syncing: commit and update

Two operations move changes between the workspace and the branch.

Commit (workspace → Git). The Changes section lists items modified in the workspace. You can select which items to commit and add a message. The compare view can also commit specific files within an item for supported items. If the branch has new commits you have not pulled, commit is disabled until you update. Fabric will not let you commit on top of a branch state you have not seen.

Update (workspace ← Git). The Updates section lists items changed in the branch. Unlike commit, update always applies the whole branch to the latest commit; you cannot pick individual items. If the same item changed in both places, update is disabled until the conflict is resolved.

That asymmetry shapes the daily routine:

  1. Start the day with update so your workspace matches the branch.
  2. Make changes, test them in the workspace, then commit small, coherent sets of items.
  3. Update again before committing if someone else pushed to your branch.

Because notebooks are stored as source files, commit messages and diffs are readable in pull requests. Keep notebooks focused, and pass runtime values through parameters rather than editing code per environment; Microsoft Fabric Notebook Parameters covers that pattern.

Pull requests and protected main

Fabric does not run pull requests; your Git provider does. That is a feature: review, branch policies, required approvers and build validation all live where your engineering process already lives.

Recommended setup:

  • Protect main. Require pull requests, at least one reviewer and a passing validation build. Direct commits from a workspace to main should be rejected by branch policy.
  • Validate in CI. Check that item folders are well formed, that the deployment parameter file is valid, and that no development IDs leaked into files the deployment does not rewrite.
  • Review item definitions, not only code. A pipeline JSON change, a new Lakehouse shortcut or a semantic model relationship is as reviewable as a Python cell.
  • Merge, then deploy. After the merge, the release pipeline deploys main to the next environment. Nobody copies items between workspaces by hand.

After a merge, developers update their workspaces (or create a fresh branch workspace from main) for the next change.

Conflict scenarios

A conflict happens when the same item changed in the workspace and in the branch since the last sync. The item shows a Conflict status, commit is disabled, and update offers Resolve conflicts.

You have four ways out:

  1. Choose a version per item in the UI. Accept incoming changes overwrites the workspace version with the branch version. Keep current content keeps the workspace version, which then needs to be committed. The compare view shows both versions side by side before you decide.
  2. Revert to the last synced state. Undo returns conflicted workspace items to their last synced version; on the Git side you can revert commits.
  3. Resolve in Git. Use Checkout new branch to create a branch from the last synced commit, commit your workspace changes to it, merge it with the original branch in your Git provider (resolving the conflict there), then switch the workspace back to the original branch.
  4. Manual update after a failed update. An update can also fail without a direct conflict, for example when a dependent item was renamed or deleted. Fabric shows which item failed so you can fix and retry.

Most conflicts come from two people editing the same item in the same branch. Branch-per-developer workspaces make them rare; when they happen, resolving them in Git with a normal merge is usually the clearest option.

Workspace drift

Drift is the gap between what the branch says and what the workspace contains. In a development workspace, some drift is normal: it is your uncommitted work. Problems start when drift becomes permanent:

  • Long-lived uncommitted changes. Work that sits for days in a workspace is invisible to reviewers and lost if the workspace is overwritten. Commit to a feature branch early; the branch is cheap.
  • Items the integration does not track. Data, Lakehouse tables and files, and connections are not in Git. Document how a fresh branch workspace gets the data it needs to test, or every developer will invent their own setup.
  • Deployed workspaces connected to Git. A QA or production workspace connected to a branch gives people a second way to change it. Keep deployed workspaces disconnected and update them only through the release pipeline.
  • Default Lakehouse bindings. Notebook definitions carry their default Lakehouse in metadata. Fabric can auto-bind notebooks to the matching Lakehouse in another workspace, but verify the binding after branching out; a branch workspace notebook that still writes to the source workspace’s Lakehouse is a quiet form of drift.

Permissions

Permissions come from two places, and both must allow an action:

Action Fabric workspace Git provider
Connect, disconnect, change connection Admin Read access to the repository
Commit workspace changes Contributor or higher, with write access to all items Write access, and branch policy must allow a direct commit to that branch
Update the workspace from Git Contributor or higher, with write access to all items Read access
Switch branch or check out a new branch Admin, or Member/Contributor when the workspace allows it Read; create-branch permission for a new branch
Branch out to another workspace Contributor or higher Read and create-branch permission

Viewers cannot see Git information or perform Git actions. Tenant admins must enable Git integration, and cross-geo exports for Azure DevOps when the workspace and repository are in different regions. Branch policies on main are what actually stop direct commits, so set them in the Git provider; Fabric respects them.

Common mistakes

  • Many developers in one workspace on one branch, expecting Git to isolate them.
  • Committing directly to main from a workspace because branch policies were never configured.
  • Treating Git integration as deployment, by connecting QA and production workspaces to branches and “updating” them.
  • Expecting Git to restore data. It restores definitions; tables and files are untouched.
  • Choosing “update workspace” on first connect without checking which side has the newer work.
  • Huge commits that mix unrelated items, which make review and conflict resolution painful. GitHub and Azure DevOps also apply commit size limits.
  • Sharing one personal access token for the whole team instead of per-user connections.
  • Hard-coding environment values in notebooks, so every promotion needs an edit instead of a parameter.

Recommendation

Use Git integration for what it is designed for: versioning item definitions and moving them between a developer’s workspace and a branch. Give each active change its own branch and branch workspace, protect main with pull requests and validation, and treat a merge to main as the only input to deployment.

Then hand over to a deployment process that knows about environments. Git integration answers “what changed and who approved it”. fabric-cicd answers “what is running in QA and production”. Keep those answers separate and both stay trustworthy. For how these workspaces fit into the wider platform, see Designing a Scalable Microsoft Fabric Architecture.

Tags

  • Microsoft Fabric
  • Git
  • DevOps
  • CI/CD