Managing Changes in Fabric Notebooks with Version Control Best Practices
You need version control to manage Fabric Notebooks well. Without it, teams can have problems like broken notebooks, lost work, and unclear links. Some common problems are:
No documentation for environments
Sensitive data might leak
Code is hard to keep up and needs manual work
When you use version control, you get clear tracking, better teamwork, and safe deployment. You can see changes, fix mistakes, and keep strong rules with every update.
Key Takeaways
Use version control to keep Fabric Notebooks neat and safe. It also helps you share them with your team.
Set up Git integration by following workspace rules. Connect to GitHub or Azure DevOps if they are supported.
Commit changes often and write clear messages. Use branches for new features. Open pull requests to review work before merging.
Use deployment pipelines to move notebooks safely. Move them through development, testing, and production steps.
Do not put secrets in notebooks. Use secure storage like Azure Key Vault. Always check permissions to keep your work safe.
Setup
Requirements
Before you begin, check that you have what you need to connect Fabric Notebooks to a Git repository.
You must have a Fabric license. If your Fabric SKU is small, you also need a Power BI Pro license.
You need admin rights in your Fabric workspace.
The workspace must let you use Git and have enough space.
Only Fabric items that are supported, like Notebooks, can use Git.
You have to turn on the Git feature in Fabric.
Workspace and branch names must follow the rules. Do not use spaces at the start or end, or special marks like
" / : < > \ * ? |.Save all your work before making a new branch.
B2B collaboration does not work with Git integration.
Sync and commit only go one way at a time. Sensitivity labels do not work.
Tip: If you are just starting, you can find learning modules, tutorials, and help from the Microsoft community. There are user groups, events, and guides to help you learn.
Git Providers
You can link Fabric Notebooks to different Git providers.
Azure DevOps (must be in the same tenant as your Fabric tenant)
GitHub (cloud version)
GitHub Enterprise (cloud version)
Note: Use only the cloud versions that are supported. On-premises or unsupported versions will not work.
Configuration
To set up Git integration, do these steps:
Go to your Fabric workspace and open settings.
Turn on the Git integration feature.
Pick your Git provider from the list.
Type in your repository details and connect your workspace.
Make sure your workspace and branch names follow the rules.
Save any work before you make a new branch.
Use the official guides and tutorials for help.
Helpful Resources:
Version Control Integration
Version control integration lets you see changes and work with your team. It helps keep your Fabric Notebooks safe and neat. This part shows how to link your notebooks to a Git repository. You will also learn how to save your work and use branches for teamwork.
Connect to Repository
Follow these steps to connect your Fabric Notebooks to a Git repository:
Change your workspace runtime to 1.2. Go to Workspace settings. Pick Data Engineering/Science, then Spark compute. Choose '1.2 (Spark 3.4, Delta 2.4)' and save.
Make a
.ymlfile on your computer. This file should say that Git is needed for your environment.Upload the
.ymlfile to your workspace. In Workspace settings, go to Data Engineering/Science, then Library management. Click Add from .yml, merge, and apply the changes.Check if Git works by running this command in a new notebook cell:
%%bash
git --version
When Git is ready, link your workspace to your Git provider. You can use GitHub or Azure DevOps in the workspace settings.
Tip: Use personal access tokens (PATs) for safe connections. Pick tokens that can read and write. If your group uses multifactor authentication, make sure your Fabric workspace uses it too.
You can also use Fabric workspace identity to sign in. This uses a managed service principal. You do not need to handle keys or secrets. It works well with data sources that use Microsoft Entra authentication.
Commit Changes
Saving your changes in Fabric Notebooks keeps your work neat and easy to find. Here are some good tips:
Use clear folders and names. Start notebook names with numbers to show order, like
01_data_prep.ipynb,02_analysis.ipynb.Do not put passwords or secrets in your notebooks. Use GitHub Secrets or other safe places for private info.
Split big notebooks into smaller parts. Put scripts in their own folders so you can use them again.
Use branches and pull requests for new features or tests. This keeps your main code safe.
Use CI/CD pipelines to automate your work. GitHub Actions or Azure DevOps can help you test and deploy notebooks.
Keep track of your models, datasets, and code versions. Use commit messages and Git tags to mark important versions.
Sync your changes between Fabric and your Git repository often. This keeps your work current and easy to check.
Watch your models and data for problems. Use built-in tools and alerts to find issues early.
Note: Always write clear commit messages. Say what changed and why. This helps your team know what you did and makes it easier to fix problems later.
Branch Management
Branch management helps teams work together and keeps development safe. In Fabric, each workspace links to one Git branch. Here is how to manage branches well:
Use a develop branch to test new features before moving them to main.
For each new feature or bug fix, make a feature branch from develop. Link this branch to your own Fabric workspace. This keeps your work separate and avoids mix-ups.
When your work is done, open a pull request to merge your feature branch into develop or main. Ask your team to check your changes.
Protect your main and develop branches. Only allow merges with pull requests, not direct pushes.
Tag releases in the main branch. This helps you know which version is live.
Best Practice: Give each developer their own workspace and branch. This matches industry standards and helps avoid mix-ups. It also makes it easy to see who made each change.
Fabric's way of managing branches is like regular code repositories. Each developer works in their own workspace and branch. They save changes and merge them with pull requests. Deployment pipelines help test and move code from development to production. This makes work faster and cuts down on mistakes.
Treat your notebooks like important development items. Use version control, branching, and code review like you do with regular code. This keeps your projects neat, safe, and ready for production.
Collaboration
Working together on Fabric Notebooks becomes easier when you use version control. You can track changes, review work, and keep your team on the same page. Here is how you can use collaboration features to improve your workflow.
Pull Requests
Pull requests help you share your changes with your team before adding them to the main branch. You can use them to ask for feedback, review code, and make sure everything works well. When you open a pull request, your team can:
See what you changed and why.
Leave comments or suggestions.
Approve or ask for more changes.
Fabric Notebooks support features like automatic checkpoints every five minutes and manual checkpoints for important moments. You can view version history, see who made changes, and compare different versions. This makes it easy to track progress and restore older versions if needed.
Tip: Always create a pull request for big updates. This helps your team catch mistakes early and keeps your project organized.
Merge Conflicts
Merge conflicts happen when two people change the same part of a notebook or data at the same time. You might see this if you and a teammate both update a Delta Lake table or edit the same notebook cell. Here is how you can handle merge conflicts:
Open the file with the conflict. Look for special markers like
<<<<<<<,=======, and>>>>>>>.Decide which changes to keep. You can combine both or pick one.
Remove the conflict markers after you finish editing.
Save and stage the file using
git add <filename>.Repeat for all files with conflicts.
To avoid conflicts, try to work on different parts of the notebook or use clear partition keys when working with data. Do not run multiple streaming queries with the same checkpoint location.
Commit Messages
Good commit messages help your team understand what changed and why. Use a clear format to make your messages easy to read. Try this structure:
type(scope): subject
Body with more details about the change.
Footer with links to issues or extra notes.
Use
typelikefeatfor new features orfixfor bug fixes.Keep the subject short, under 75 characters.
Explain why you made the change in the body.
Link to related issues in the footer.
Write messages as if you are explaining to someone new. Be specific and clear. Good messages make it easier to find and fix problems later.
Deployment Pipelines
Deployment pipelines in Fabric help you move work safely. You can use them to copy, test, and release notebooks and pipelines. Pipelines let you do these steps again and again. They support many types of items and let you use REST APIs to automate.
Environment Promotion
Environment promotion lets you move notebooks and pipelines through stages. These stages are Development, Test, and Production. Pipelines copy your work from one stage to the next. They keep IDs, URLs, and permissions the same. You can pick to deploy everything or just some items. Pipelines track who made changes and when.
Tip: Always check the content between stages before you deploy. This helps you not overwrite important work by accident.
Notebooks do not change parameters by themselves during promotion. You must update parameters by hand when you move notebooks. Microsoft wants to make this better soon.
To promote your work safely:
Compare content in each stage.
Manage who can access and change things.
Use notes to talk with your team.
Change pipeline stages as your project grows.
CI/CD Automation
You can use CI/CD tools like Azure DevOps and GitHub to automate deployments. Many teams use VS Code for Notebooks and Power BI Desktop for models. You build and test on your computer first. Then you push changes to your Git repository. Fabric workspaces connect to one branch, so you manage branches and commits before syncing.
Azure DevOps pipelines help you build and release your work. You can test in a fake production environment. This makes deployments easy to repeat and helps stop mistakes. More groups use these tools as the process gets better.
Deployment Rules
Deployment rules help set up notebooks and pipelines for each environment. Do not put settings right in your notebooks. Instead, save settings in another notebook or file. Use deployment rules to update connections, like changing the lakehouse when moving from Test to Production.
To set up deployment rules:
Find the workspace and lakehouse IDs for each environment.
Make rules to update notebook links to the right data sources.
Apply the rules and deploy your work again.
Check that notebooks and pipelines use the correct connections.
Deployment pipelines help you control how notebooks move through each stage. You keep your work safe, the same, and ready to use.
Troubleshooting
Common Issues
You might run into some problems with Fabric Notebooks and version control. Here are a few common ones: Workspace ownership is sometimes not clear. This makes it tough to know who can change things. Moving notebooks from development to production can cause versions to not match. Security settings might not always move when you move notebooks. It can be hard to decide how many versions of each file to keep. Old versions can build up and take too much space. If you do not manage versions well, you might run out of storage or computer power. Pipelines can fail if notebook dependencies or error handling are not set up right.
To fix these problems, try using a hub-and-spoke setup. This means you keep development, testing, and production workspaces apart. You can also use PySpark notebooks in your pipelines. These can help clean up old versions by themselves.
Tip: Put different file versions in folders with dates. This makes it easy to find and manage your files.
Limitations
Fabric Notebooks have some things they cannot do:
Think about these limits when you plan your work. Always look at the newest documentation for changes.
Security
It is important to keep your notebooks safe. Here are some ways to do that: Do not put passwords or secrets in your notebooks. Use GitHub Secrets or Azure Key Vault for private data. Set clear rules for who can use each workspace. Check often to see who can open and change notebooks. Use managed identities to connect to data sources.
Note: Security settings might not move with your notebooks. Always check permissions after you move notebooks.
If you follow these steps, you can keep your work safe. Your team will be ready for any changes.
Version control lets you and your team work together. It helps keep your Fabric Notebooks safe. Teams use deployment pipelines and change reviews to work better. These tools help make deployments safer. You can keep improving by doing these things:
Sort workspaces by what they are for.
Use deployment pipelines to release things safely.
1. Gather information about how you work. 2. Look for ways to do better. 3. Try new ideas and see if they help.
Keep checking your process so your projects get stronger.
FAQ
How do you recover an older version of a Fabric Notebook?
You can open the notebook’s version history. Pick the version you want. Click “Restore” to bring it back. This helps you undo mistakes or see past work.
Tip: Always check the version details before restoring.
Can you use GitHub and Azure DevOps at the same time?
No, you can only connect one Git provider per workspace. Choose either GitHub or Azure DevOps for each workspace. Switch providers in workspace settings if you need to change.
What should you do if you see a merge conflict?
Open the notebook file. Look for conflict markers like <<<<<<<. Decide which changes to keep. Remove the markers. Save the file. Use git add to stage it. Commit your changes.
How do you keep secrets safe in Fabric Notebooks?
Never write secrets in your notebook code. Use Azure Key Vault or GitHub Secrets to store sensitive data. Connect your notebook to these services for secure access.
Why does Fabric only allow one branch per workspace?
Fabric links each workspace to one branch to keep things simple and safe. This setup helps you avoid confusion and makes it easier to track changes.