Key takeaways
- Fabric Variable Library is the environment map for workspace and identifiers across stages.
- Rebind and deploy automation reads the library; hard-coded stage GUIDs are forbidden in new code.
- Platform versus domain workspaces are explicit rows with owners.
- Git schema validation is required for library changes.
- Secrets never live in Variable Library; topology does.
- Promotion regressions get playbooks paired to the library, not replacements for it.
Hard-coded workspace IDs in notebooks are how Test accidentally rebinds Prod. Spreadsheet "environment maps" in chat are how two teams maintain different truths. Fabric already ships a better home: a Git-tracked Variable Library with per-stage value sets.
Put Test, Preprod, and Prod values in the item. Teach rebind notebooks to read via supported APIs. Split platform versus domain workspaces explicitly. Respect Git schema so restores work. Pair the library with a promotion story when portal parameters regress.
Named model: environment map in Variable Library
- One library, stage value sets: workspaces, lakehouses, warehouses, and major connection names with Test, Preprod, and Prod values.
- Automation reads the map: rebind notebooks and deploy helpers resolve IDs through supported Variable Library mechanisms, not pasted GUIDs.
- Labeled ownership: platform shared rows and domain project rows stay explicit so operators stop guessing.
- Contract: if the map is not in Git and read by automation, it is folklore. Schema-breaking hand edits are an outage class.
Figure 1. One Git-tracked Variable Library holds stage value sets. Automation resolves targets from the map. Sticky notes and chat spreadsheets do not scale to Prod.
Context and constraint
A common failure: rebind notebooks accumulate GUID constants "just for now." Now lasts through three stages and one scary near-miss. The Variable Library is available. Teams still act like sticky notes scale.
Stage value sets belong in Variable Library. Rebind and deploy automation should resolve workspace IDs, lakehouse IDs, and connection names from that map. Platform workspaces and domain workspaces need explicit rows so people stop guessing. Hand-edited JSON that violates the item schema fails restores and wastes a day. When portal parameters regress, keep a documented promotion workaround beside the library, not instead of it.
Figure 2 is the Learn surface for defining values in a Variable Library. The portal is where you curate sets; Git is where the truth must stay honest.
Figure 2. Promotion is safer when workspace targets come from a Variable Library map, not pasted GUIDs. Source: Microsoft Learn: Variable Library overview.
Design
1. One library, stage value sets
Maintain variables for the identifiers automation needs: workspaces, lakehouses, warehouses, major connection names. Fill Test, Preprod, and Prod value sets. Resist a fourth informal "dev on my laptop" set that never gets curated. Local overrides can exist; they should not fork the map.
2. Rebind via supported reads, not pasted GUIDs
Notebooks and pipelines that rebind should fetch values through the supported Variable Library mechanisms or approved platform helpers. Pasting GUIDs into cells recreates the sticky note with better syntax highlighting. Code review should reject new hard-coded workspace IDs the way it rejects secrets. Figure 3 is that fork in the road.
Figure 3. Pasted GUIDs recreate archaeology. Supported library reads keep Test from accidentally rebinding Prod.
3. Split platform versus domain workspaces in the map
Platform shared capacities and domain project workspaces both appear, labeled. Operators should see which targets are shared infrastructure versus team-owned. Ambiguous names cause rebinds that "succeed" on the wrong workspace. Figure 4 also draws the secrets line.
Figure 4. Label platform and domain rows with owners. Topology lives in Variable Library. Secrets stay in Key Vault.
4. Treat Git schema as law
Variable Library in Git has a shape. Hand-editing without validating against that shape breaks sync and restore. Prefer portal or supported tooling for structural changes; if you must edit, validate. Broken Git history here is an outage class, not a style issue.
5. Pair with promotion playbooks
When portal parameters or bindings regress across stages, document the temporary controls next to the library. Do not abandon the map because one promotion path is buggy. Workarounds without a map become permanent tribal knowledge.
6. Make the map discoverable
Link the library from the platform README and from rebind runbooks. New engineers should find the map in minutes. If only two people know the item name, you still have a sticky note with permissions.
What belongs in the library versus Key Vault
Variable Library is for non-secret environment topology: ids, names, endpoints that are not credentials. Secrets stay in Key Vault or equivalent. Mixing secrets into the library teaches the wrong pattern and complicates Git. If a value is sensitive, it is not a Variable Library value. If a value is a workspace GUID, it is exactly a Variable Library value. Draw that line in the ADR so helpful engineers stop "securing" topology by burying it in personal notes.
Operating the map across teams
Give platform engineers ownership of shared rows. Give domain teams ownership of their workspace rows under review. Changes to Prod value sets should require the same scrutiny as pipeline changes. A casual Prod ID edit is a production incident with better manners. Review diffs of value sets in PRs when Git-connected. When portal edits happen, export or sync promptly so Git does not lie.
Smoke-test rebinds in Test every time the map changes
When someone edits a workspace id, run the rebind notebook (or a dry-run check) in Test against the new map before touching Preprod. Map edits without a smoke test are how typos become outages. Automate a "resolve all required keys" check in CI if you can; otherwise make it a required checklist item on the PR.
Failure modes
GUID archaeology in notebooks. Copy-paste environments. Test rebinds Prod.
Chat spreadsheets as source of truth. Drift by message. Two teams, two maps.
One blob of variables with unclear stage sets. Wrong stage, confident deploy.
Hand-broken Git JSON. Restore fails when you need it.
Abandoning the library after a portal bug. Folklore returns. Workarounds become the system.
Unlabeled platform versus domain targets. Successful rebind to the wrong place.
What to copy / what not to copy
Copy
- Fabric Variable Library as the environment map for workspace and lakehouse identifiers across stages.
- Rebind and deploy automation that reads the library; hard-coded stage GUIDs forbidden in new code.
- Platform versus domain workspaces as explicit rows with owners.
- Git schema validation for library changes.
- Secrets never in Variable Library; topology does belong there.
- Promotion regressions get playbooks paired to the library, not replacements for it.
Do not copy blindly
Central maps create a coordination point. Scattered GUIDs create silent cross-environment writes. Strict Git hygiene slows casual edits; casual edits break restores. Reading variables in automation adds a few lines of code and removes an entire class of mistakes. Promotion workarounds add docs; undocumented workarounds add outages.
Primary references: Fabric Variable Library and deployment pipeline docs on Microsoft Learn. Pair them with your rebind runbook so the map is used, not merely admired.
Put the map in Variable Library. Read it from automation. Keep Git honest. Split platform from domain. When promotion misbehaves, document the workaround beside the map. Sticky notes do not scale to Prod.