Variable Library is your environment map, not a sticky note

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.

Figure 1. Promotion is safer when workspace targets come from a Variable Library map, not pasted GUIDs. Source: Microsoft Learn: Variable Library overview.

I learned this after watching rebind notebooks accumulate GUID constants "just for now." Now lasted through three stages and one scary near-miss. The Variable Library was available. We were still acting like sticky notes scaled.

The core idea

The environment map is a platform artifact. If it is not in Git and read by automation, it is folklore.

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.

A model that stays explainable

1. One library, stage value sets

Maintain variables for the identifiers automation needs: workspaces, lakehouses, warehouses, major connection names. Fill Test/Preprod/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.

3. Split platform vs 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.

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 Direct Lake 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.

Failure modes I design against

GUID archaeology in notebooks. Copy-paste environments.

Chat spreadsheets as source of truth. Drift by message.

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.

Unlabeled platform vs domain targets. Successful rebind to the wrong place.

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/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.

Trade-offs

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.

What I would put on an ADR

1. Fabric Variable Library is the environment map for workspace and lakehouse identifiers across stages.
2. Rebind/deploy automation reads the library; hard-coded stage GUIDs are forbidden in new code.
3. Platform vs domain workspaces are explicit rows with owners.
4. Git schema validation is required for library changes.
5. Secrets never live in Variable Library; topology does.
6. Promotion regressions get playbooks paired to the library, not replacements for it.

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.

Closing

Environments are not folders of pasted GUIDs. They are a map you can review.

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.