Git integration

In the ninth hub session, on Thursday, November 5, Nikolai told a story against himself. At his previous job, a colleague had edited a production notebook directly to fix an urgent problem, and in doing so overwrote two weeks of someone else's unsaved changes. Nobody could say which version had been running the night before, and the team spent a week rebuilding what had been lost. Version control, he said, is how a team stops relying on memory. In Fabric that means Git integration.

What Git integration does

Git integration connects a Fabric workspace to a branch of a Git repository. Once connected, the definitions of supported items in the workspace, such as notebooks, pipelines, semantic models, reports, lakehouse and warehouse definitions, Dataflows Gen2 and many others, can be committed to the branch, and changes made in the branch can be brought into the workspace. Each item is stored as a folder of text files: code for a notebook, JSON for a pipeline, a model definition in TMDL for a semantic model, and a small metadata file describing the item. Because they are text, Git can show exactly what changed between versions, line by line, and who changed it.

Git holds definitions, not data. The rows in a lakehouse table, the files in its Files area and the data in a warehouse are not in the repository. Committing a lakehouse saves its definition, such as its name and shortcuts in supported cases, so that it can be recreated elsewhere, but not its contents. Data has its own protection, as lessons 4 to 6 described: Delta history, soft delete, restore points and reloading from raw data.

Providers and requirements

Fabric supports three Git providers: Azure DevOps, GitHub and GitHub Enterprise, all in their cloud-hosted forms; on-premises Git servers are not supported. Harrow & Finch already used Azure DevOps for the StockLine code, so the hub used a new Azure DevOps repository called finch-data-hub. The tenant setting that allows users to synchronize workspace items with Git repositories must be on, and for GitHub there are separate settings. Connecting a workspace to a repository is done by a workspace admin, who signs in to the provider and chooses the organization, project, repository, branch and folder. After that, Contributors who also have write access to the repository can commit and update.

finch-data-hub/
  sales/                              <- folder connected to FDH Sales [Dev]
    lh_curated.Lakehouse/
      .platform                       <- item type, name and logical ID
      lakehouse.metadata.json
    nb_clean_sales.Notebook/
      .platform
      notebook-content.py
    pl_nightly_load.DataPipeline/
      .platform
      pipeline-content.json
    Sales Overview.SemanticModel/
      .platform
      definition/
        model.tmdl
        tables/FactSales.tmdl

Status, commit and update

The source control pane in a connected workspace shows each item's status. An item can be synced, meaning the workspace and the branch agree; uncommitted, meaning it was changed in the workspace and not yet committed; update required, meaning the branch has a newer version than the workspace; or in conflict, meaning it changed in both places. The pane has two tabs. Changes lists uncommitted items, which can be selected and committed with a message. Updates lists what has changed in the branch, and Update all applies those changes to the workspace. Updates are applied to all items together, not one at a time, so a workspace always reflects one consistent commit.

# Work out each item's Git status from three versions:
# what the last sync saw, what the workspace has now, and what the branch has now
items = {
    "nb_clean_sales":  {"synced": "v3", "workspace": "v4", "branch": "v3"},
    "pl_nightly_load": {"synced": "v2", "workspace": "v2", "branch": "v2"},
    "Sales Overview":  {"synced": "v5", "workspace": "v5", "branch": "v6"},
    "lh_curated":      {"synced": "v1", "workspace": "v2", "branch": "v3"},
}

def status(i):
    changed_here = i["workspace"] != i["synced"]
    changed_there = i["branch"] != i["synced"]
    if changed_here and changed_there: return "conflict"
    if changed_here: return "uncommitted (commit it)"
    if changed_there: return "update required (update the workspace)"
    return "synced"

for name, versions in items.items():
    print(f"{name:16} {status(versions)}")

nb_clean_sales   uncommitted (commit it)
pl_nightly_load  synced
Sales Overview   update required (update the workspace)
lh_curated       conflict

Conflicts

A conflict means the same item changed in the workspace and in the branch since the last sync. Fabric does not merge the two silently. The person resolving it can choose to keep the workspace version, overwriting the branch with a new commit, or to accept the branch version, discarding the workspace change, or can resolve the difference in Git itself, for example by editing the files in a branch and merging there, and then updating the workspace. The safest habit is to avoid conflicts: commit small changes often, update before starting work, and do not have two people editing the same item in the same workspace.

Branches and private workspaces

A team that shares one development workspace soon steps on each other's work. Fabric's answer is branching out. From a connected workspace, a person can branch out to a new workspace: Fabric creates a new branch from the current one and a new workspace connected to it, and syncs the items into it. The person works there, commits to the feature branch, and when the work is ready, opens a pull request in Azure DevOps or GitHub to merge the feature branch into the main branch. After review and merge, the shared development workspace is updated from main.

The hub adopted that pattern on November 5. The main branch is connected to FDH Sales [Dev], and nobody edits that workspace directly. Ines branched out to build a new returns table, in a workspace called FDH Sales [Ines], and committed three times over two days. Her pull request was reviewed by Nikolai, who asked for one change to a column name, and merged on November 9. Updating FDH Sales [Dev] took under a minute. Private workspaces created by branching out need a capacity and count against it, so the team agreed to delete them when their branch is merged.

Power BI projects and text formats

Power BI Desktop can save work as a Power BI project, a folder with the .pbip extension, instead of a single .pbix file. The project stores the semantic model in TMDL, a readable text format for tabular models, and the report in the enhanced report format PBIR, as text files. That makes Desktop work fit the same Git workflow: Keiko can develop a report on her laptop, commit the project folder to a feature branch, and let Git integration bring it into the workspace. Text formats also make reviews meaningful, because a reviewer sees that a measure's formula changed rather than that a binary file changed.

One repository, several workspaces

A single repository can serve several workspaces, each connected to its own folder. The hub's finch-data-hub repository has a folder for each domain, sales, stores and supply, and each domain's development workspace is connected to its folder on main. Workspace folders, from lesson 3, are mirrored as subfolders in the repository, so the structure a developer sees in Fabric matches the structure a reviewer sees in Azure DevOps. Keeping all three domains in one repository made shared standards easy to enforce, such as a branch policy that requires one reviewer for every pull request into main; Elena set that policy in Azure DevOps on November 6.

Only development workspaces are connected to Git in the hub's design. Test and production workspaces receive content through the deployment pipeline described in lesson 10, so that nothing reaches production except a version that was committed, reviewed and deployed. Some teams instead connect each stage's workspace to its own branch, such as main for development and release for production, and promote by merging branches. Both patterns are valid, and the exams expect candidates to recognize each. The important principle is the same in both: production is never where changes are first made.

Git integration also changes how a new team member starts. When a third engineer joins the hub in 2027, she will not need anyone to explain which version of each notebook is current. She will clone the repository, read the commit history and branch out to her own workspace, with every item defined exactly as the team left it.

Automation

Everything the source control pane does can also be done through the Fabric REST APIs, which is how teams run Git operations from Azure DevOps pipelines or GitHub Actions: commit, update from Git, check status and connect workspaces. Some teams go further and deploy entirely from Git, using tools such as the open-source fabric-cicd library to publish items from a repository folder into a test or production workspace, without a deployment pipeline at all. Lesson 10 compares that approach with Fabric's built-in deployment pipelines.

What to commit and how often

Teams new to Git tend to commit too rarely, which turns every commit into a large, hard-to-review bundle. The hub's guideline was one commit per logical change, with a message that says why, not just what: 'Exclude cancelled orders from FactSales load' rather than 'update notebook'. Notebooks are a special case, because they can hold outputs and cell results; Fabric commits notebook code and settings, and the team made a habit of clearing large outputs before committing so diffs stayed readable. Secrets never go in item definitions: connections and credentials are stored in Fabric's connection settings or in Azure Key Vault, not in a notebook cell that would be committed to the repository for anyone with read access to see.

Nikolai also asked that every pull request into main describe how the change was tested, for example 'ran nb_clean_sales on the October 28 extract; row counts match StockLine'. That single sentence, he said, would save more time in a year than any tool.