Manage branches in Microsoft Fabric workspaces

The goal of this article is to present Fabric developers with different options for building CI/CD processes in Fabric, based on common customer scenarios. This article focuses more on the continuous integration (CI) part of the CI/CD process. For a discussion of the continuous delivery (CD) part, see manage deployment pipelines.

This article outlines a few distinct integration options, but many organizations use a combination of them.

Prerequisites

To integrate Git with your Microsoft Fabric workspace, you need to set up the following prerequisites for both Fabric and Git.

Fabric prerequisites

To access the Git integration feature, you need one of the following:

In addition, the following tenant switches must be enabled from the Admin portal:

These switches can be enabled by the tenant admin, capacity admin, or workspace admin, depending on your organization's settings.

Git prerequisites

Git integration is currently supported for Azure DevOps and GitHub. To use Git integration with your Fabric workspace, you need the following in either Azure DevOps or GitHub:

  • An active Azure account registered to the same user that is using the Fabric workspace. Create a free account.
  • Access to an existing repository.

Development process

The Fabric workspace is a shared environment that accesses live items. Any changes made directly in the workspace override and affect all other workspace users. Therefore, Git best practice is for developers to work in isolation outside of the shared workspaces. There are two ways for a developer to work in their own protected workspace.

To work with branches using Git integration, first connect the shared development team’s workspace to a single shared branch. For example, if your team uses one shared workspace, connect it to the main branch in your team’s repository, and sync between the workspace and the repo. If your team’s workflow has multiple shared branches like Dev/Test/Prod branches, each branch can be connected to a different workspace.

Then, each developer can choose the isolated environment in which to work.

Scenario 1 - Develop using client tools

If the items you're developing are available in other tools, you can work on those items directly in the client tool. Not all items are available in every tool. Items that are only available in Fabric need to be developed in Fabric.

The workflow for developers using a client tool like Power BI Desktop should look something like this:

  1. Clone the repo into a local machine. (You only need to do this step once.)

  2. Open the project in Power BI Desktop using the local copy of the PBIProj.

  3. Make changes and save the updated files locally. Commit to the local repo.

  4. When ready, push the branch and commits to the remote repo.

  5. Test the changes against other items or more data by connecting the new branch to a separate workspace, and uploading the semantic model and reports using the update all button in the source control panel. Do any tests or configuration changes there before merging into the main branch.

    If no tests are required in the workspace, the developer can merge changes directly into the main branch, without the need for another workspace.

  6. Once the changes are merged, the shared team’s workspace is prompted to accept the new commit. The changes are updated into the shared workspace and everyone can see the changes to those semantic models and reports.

Diagram showing the workflow of pushing changes from a remote Git repo to the Fabric workspace.

For a specific guidance on how to use the new Power BI Desktop file format in git, see Source code format.

Scenario 2 - Develop using another workspace

For a developer who works in the web, the flow would be as follows:

  1. From the Branches tab of the Source control menu, select Branch out to new workspace.

    Screenshot of source control branch out option.

  2. Specify the names of the branch and workspace. The new branch created based on the branch connected to the current workspace.

    Screenshot of branch out specifying the name of the new branch and workspace.

  3. Select Branch out.

    Fabric creates the new workspace and branch. You're automatically taken to the new workspace.

    The workspace syncs with your feature branch, and becomes an isolated environment to work in, as illustrated. You can now work in this new isolated environment. This might take a few minutes. See troubleshooting tips for more information on branching out.

    Diagram showing the workflow of commits.

  4. Save your changes and commit them into the feature branch.

  5. When ready, create a PR to the main branch. The review and merge processes are done through Azure Repos based on the configuration your team defined for that repo.

Once the review and merge are complete, a new commit is created to the main branch. This commit prompts the user to update the content in the Dev team's workspace with the merged changes.

See branching out limitations for more information.

Release process

The release process begins once new updates have completed a Pull Request process and merged into the team’s shared branch (such as ‘Main’, ‘Dev’ etc). From this point, we will outline the different options to build a release process in Fabric. You can find the different considerations for the release process in manage deployment pipelines.

Switch branches

If your workspace is connected to a Git branch and you want to switch to another branch, you can do so quickly from the Source control panel without disconnecting and reconnecting.
When you switch branches, the workspace syncs with the new branch and all items in the workspace are overridden. If there are different versions of the same item in each branch, the item is replaced. If an item is in the old branch, but not the new one, it gets deleted. To switch between branches, follow these steps:

  1. From the Branches tab of the Source control menu, select Check out new branch.

    Screenshot of source control check out a new branch option.

  2. Specify the branch you want to connect to. This branch must contain the same directory as the current branch.

  3. Select Check out branch.

If you have any unsaved changes in the workspace, they will be lost if you switch branches without saving them first. Select Cancel to go back and save your changes before switching branches.

Screenshot of workspace settings screen asking if you're sure you want to switch branches.