Workspace Version Control

Connect a workspace to a repository

Source control exists so that several developers can make incremental workspace updates frequently and reliably, with the usual Git advantages: a history of what changed, review before anything lands, and a way back.

Fabric Git integration connects a workspace to a remote repository in Azure DevOps or GitHub. Continuous integration automation built around it — validating a pull request, updating an integration workspace from Git — runs in any runner: GitHub Actions, Azure Pipelines, or a self-hosted one. With the Azure DevOps provider, service principal support lets those flows authenticate without a signed-in user.

The connection is made once for the workspace, in workspace settings, and the tenant setting for Git integration has to be enabled first.

The scope of that connection is the detail people get wrong.

The repository connection applies at the workspace level: a single branch in the repository is associated with the workspace. The repository can hold many branches, but only the code in the branch selected in workspace settings directly affects that workspace. Nothing arrives from the other branches until the selection changes or a merge brings their content into the selected one.

Because a workspace is shared, development has to happen somewhere isolated. Fabric gives two options for that isolated environment: an IDE on the local machine, such as Power BI Desktop or Visual Studio Code, or a different Fabric workspace. The development process itself is the same whichever release option the team later chooses.

Commit the database, then update it back

For a Fabric SQL database the integration works in two directions, and the two directions do different things.

Committing converts the live database into code. Create a table, a stored procedure, or another object; open the Source control panel; select the database and choose Commit. The service reads the object definitions from the database and writes them to the remote repository. From then on the history of those definitions is visible in the repository's source view, and every later edit is committed the same way.

Updating goes the other way: it validates the code in the repository before applying a differential change to the database — only what differs is applied.

What the team gains from that round trip is ordinary Git practice applied to database objects: a history of definitions over time, plus branching, merging, and pull-request review of the code that describes them.

One quirk is worth expecting. Straight after an update, the database may show as Uncommitted, because Git integration compares the whole generated file content for an item and small unintended differences — inline column attributes, for instance — can appear. Committing back from the Fabric web interface re-syncs the definition with what a commit generates.

Release option one: Git as the source of truth

Once a pull request is merged into the team's shared branch, the release process begins — and Fabric offers more than one shape for it.

In the Git integration option, every deployment originates from the repository. Each stage of the release pipeline has its own dedicated primary branch — Dev, Test, and Prod — feeding the matching workspace. When a pull request to the Dev branch is approved and merged, a release pipeline updates the Dev workspace, and the upload comes straight from the repository into the workspace through the Fabric Git APIs. A pull request then carries the content to the Test branch with the same review and approval as any other, another release pipeline updates the Test workspace, and Prod repeats the pattern.

Choose it when the repository must be the single source of truth and the origin of all deployments, when the team follows Gitflow with multiple primary branches, and when no build environment needs to alter the files before deployment.

Release option two: one branch and the Items APIs

In the Fabric Items APIs option, all deployments come from the same branch — Main — and the branching strategy is trunk-based. Each stage has its own build and release pipeline, and those pipelines can spin up a build environment that runs unit tests and scripts that change item definitions before upload: the data source connection, the connections between items, or parameter values that must differ per stage. Definitions are then uploaded with Fabric's item definition APIs, using tooling such as the fabric-cicd Python library or the bulk import operation for item definitions.

Two consequences distinguish this model. Test and Prod are not connected to Git at all; their content is pushed to them from Main. And not every dependency needs rewriting — some bind automatically through logical IDs when deployed to a new workspace — so the build scripts handle only what does not.

Release option three: Git only through Dev

Git integration can also stop at development. In this option the repository is connected only up to the Dev stage; from there, content moves directly between the Dev, Test, and Prod workspaces through Fabric deployment pipelines.

The sequence is still a release process. Once a pull request to Main is approved and merged, a build pipeline uploads the changes to Dev through the Fabric Git APIs and can trigger post-deployment operations or tests there. A release pipeline then deploys Dev to Test, where automated and manual tests take place after deployment. When the tests are complete and the release manager approves, the deployment to Prod runs.

That option suits teams that use source control for development purposes only and prefer to deploy changes directly between the stages of the release pipeline.

It also assumes the Fabric-native controls are enough: deployment rules, autobinding, and the available APIs to manage per-stage configuration, plus the other deployment pipeline features — viewing the changes inside Fabric before promoting, and deployment history. Two more conditions come with it: deployments in Fabric deployment pipelines have a linear structure, and creating and managing the pipeline needs permissions beyond the workspace connection.

Many organizations end up combining options rather than picking one, so the models are worth recognizing by their constraints rather than by name.

Leave the generated SQL project file alone

The repository does not only hold object definitions. It also holds a SQL project file, which carries metadata about the database and is what lets Fabric bring extra functionality into source control and deployment pipelines.

Fabric generates and updates that project file automatically. Manual edits to it are overwritten by source control integration on the next commit from Fabric, so anything you hand-write there is temporary. The one supported addition is local: to build the project on your own machine with tools such as SQL Server Management Studio or the SQL projects extension for Visual Studio Code, you can add a reference to the master.dacpac file.

Three metadata properties are what Fabric adds to that file.

The exclusion is the subtle one: shared query scripts are versioned like everything else, but they are not treated as objects the database model must validate.

Branch out, review, and merge back

Branch out to new workspace, from the Branches tab of the Source control menu, is how a developer gets an isolated environment without leaving Fabric. Name the branch and the workspace, and Fabric creates both: the branch in the repository, populated with the committed contents of the branch the workspace is connected to, and the workspace in Fabric.

For a SQL database, the new database contains the objects that were checked into source control — and its tables are new and empty. Definitions travel with the branch; data does not.

Reviewing a change then follows normal team practice. Work on the database in the secondary branch workspace, commit those changes from the Source control panel, and open a pull request from the secondary branch to the primary branch in Azure DevOps or GitHub, where the difference in database code between the two workspaces is visible.

Completing the pull request updates source control — and there it stops. The database in the primary Fabric workspace is not changed by the merge. To change the primary database, update the primary workspace from source control with the Update button on the Source control panel. That separation is useful: the release manager decides when merged definitions actually reach the primary database.

Send scripts along with the deployment

Some database work has to accompany an update rather than follow it by hand, and that is what pre-deployment and post-deployment scripts are for. They are part of the SQL project, so they are versioned with everything else, and the same capability applies to deployment pipelines.

Managing static data is the standard case. In the Fabric query editor, write a query containing a repeatable MERGE that sets the rows of a lookup table, rename it, move it to Shared Queries, and use its context menu to Set as Post-deployment Script. From then on it runs automatically as part of any update from source control and any deployment pipeline deployment, and it can be edited either in the Fabric query editor or locally in Visual Studio Code and committed like any other file.

Scripts also cover a documented gap: database-level settings such as collation and compatibility level are not included in source control or deployment pipeline integration. For settings you can apply with T-SQL after the database is created, modify the database with scripts after deployment.

Key takeaways

• One workspace, one branch: Git integration connects a workspace to Azure DevOps or GitHub, and only the branch selected in workspace settings affects it. Isolate development in a local IDE or a separate workspace.
• Two directions: committing reads live object definitions into the repository; updating validates the repository code and applies a differential change to the database.
• Three release shapes: Gitflow with a branch per stage and the Git APIs; trunk-based with build scripts and the Items APIs, leaving Test and Prod disconnected from Git; or Git through Dev only, with deployment pipelines promoting between workspaces.
• The project file belongs to Fabric: it is generated and updated automatically, manual edits are overwritten, and it excludes .sharedQueries from model validation while keeping those scripts in source control.
• Merging is not deploying: a completed pull request updates the repository, and the primary workspace changes only when it is updated from source control. Branch-out brings definitions but leaves the new tables empty.
• Use scripts for the rest: post-deployment scripts carry controlled static data through both delivery paths, and collation and compatibility level need scripts after deployment.