💡
Tip: If you take one thing from this episode and ignore the rest, connect your dev workspaces to Git today. Everything else in this series builds on that one move: validation, promotion, automation. And it costs you half an hour.
## How Fabric's Git integration actually works
The mechanic that shapes everything else is this: **Git integration is configured per workspace, and a workspace connects to exactly one folder in one branch of one repository.**
![](https://cdn.hashnode.com/uploads/covers/671484a48d12bd1dd2a63eb4/41f11116-969e-41e6-b6de-42b7a5a7fd99.png align="center")
Four things to know before you design around it:
**Providers.** Azure DevOps, GitHub and GitHub Enterprise (cloud only in all three cases). Azure DevOps can live in a *different* tenant than your Fabric tenant, which comes up more often than you'd think in consultancies and post-merger estates.
**Authentication.** With Azure DevOps you can connect as yourself (the automatic credential, using your Entra identity) or through a configured connection that supports OAuth 2.0 **or a service principal**. And the service principal option is the one that matters, because it's what lets automation connect a workspace with no human signed in. GitHub's source control connector uses a **personal access token**. That asymmetry is worth knowing up front. If unattended automation is where you're heading, Azure DevOps currently gives you the cleaner identity story. (It's also the reason FabricOps supports both providers but treats the git credential as a *connection* rather than a login.)
**What travels.** Item definitions, not data. A lakehouse in Git is `lakehouse.metadata.json` and `shortcuts.metadata.json`. It's the shape of the thing, not a single row inside it. Semantic models arrive as TMDL, reports as PBIR, notebooks as source files. Coverage is broad these days. Very nearly every item type is supported, though some are still marked preview, including the two you'd least expect: reports and semantic models. And if a workspace does hold something unsupported, you can still connect it. Those items are simply invisible to Git. They aren't committed, synced or deleted, and they never appear in the source control pane at all. They're flagged as *Unsupported* in the workspace's Git status column, which is the only place you'll see them. Either way, check the [current list](https://learn.microsoft.com/fabric/cicd/git-integration/intro-to-git-integration) rather than trusting this blogpost.
**Folders are preserved.** If you organise items into folders inside a workspace, those folders appear in the repo, and vice versa. Nested up to ten levels, empty folders aren't committed. And a small trap, connecting a workspace that already has folders to a branch that doesn't yet have them shows up as uncommitted changes. Commit first, update second.
There's more in the box these days than when I first started doing this: selective branching, related branches, comparing changes before you sync, branched workspaces, variable libraries for environment-specific values, and tooling in VS Code. I'm deliberately not going deep on any of it here. The branching *workflow* will be covered in a later episode. For now, all you need is the shape: workspace → repo → branch → folder.
*One caveat worth saying out loud before we build on this: Git makes your platform versionable, not reproducible. A branch tells you what the items should look like. It doesn't create the workspaces, wire the connections or promise that dev and prod are the same shape. That's a different problem... and again something I will cover in a later episode.*
## The repo that mirrors your architecture
Here's the part I actually care about. You have seven layers (or three, or four. That is Episode 2's spectrum). A Git connected workspace connects to one folder. So:
> **One layer = one workspace = one repo folder.**
That's it. That's the whole design. It sounds almost too simple to write down and it's the thing that makes everything downstream tractable.
This is the top of the [FabricOps](https://github.com/gronnerup/FabricOps) repo. So a real one and not just something idealised:
```plaintext
FabricOps/
├── .azure-pipelines/ # Azure DevOps pipeline definitions
├── .github/ # GitHub Actions workflows
├── automation/ # Scripts, environment definitions, IaC
├── documentation/ # Docs and design notes
└── solution/ # The platform layers themself
├── core/
├── ingest/
├── prepare/
├── store/
├── model/
├── present/
└── orchestrate/
```
The subfolders of the `solution` folder **are** the layers from Episode 2, one by one, same names. No mapping table, no translation layer, no tribal knowledge. Someone who has read the architecture diagram can navigate this repo and someone who has read the repo can draw the architecture diagram.
Go one level deeper and you get the items:
```plaintext
solution/
├── store/
│ ├── Landing.Lakehouse/
│ ├── Base.Lakehouse/
│ └── Curated.Lakehouse/
│ ├── .platform
│ ├── lakehouse.metadata.json
│ └── shortcuts.metadata.json
├── ingest/
│ ├── FabricOps_API.Notebook/
│ └── FabricOps_SQL.DataPipeline/
├── prepare/
│ ├── FabricOps_functions.Notebook/
│ ├── Engineering/
│ │ └── FabricOps_enrich.Notebook/
│ └── Utils/
│ └── ManageWorkspaceIcons.Notebook/
├── model/
│ └── FabricOps.SemanticModel/
│ ├── definition.pbism
│ └── definition/ # TMDL
├── present/
│ └── FabricOps.Report/
│ ├── definition.pbir
│ ├── definition/ # PBIR
│ └── StaticResources/
├── orchestrate/
│ └── Load FabricOps.DataPipeline/
└── core/
└── Metadata.SQLDatabase/
```
A few things worth pointing out because they're the details people trip over:
* **Every item is a folder named** `