DEV Community: Mintu Ghosh

The empty folder that would have emptied a production workspace

Mintu Ghosh — Fri, 21 Aug 2026 09:08:18 +0000

Deployment tools that support cleanup usually work out what to remove by
comparison: anything present in the target but absent from the source is an
orphan, so delete it.

That rule is fine. It has one input state where it becomes destructive, and that
state is completely normal.

The state

An empty source folder.

If the source has no items, then everything in the target is absent from the
source. Every item in the target workspace is an orphan. Cleanup removes all of
it, reports success, and the deployment then publishes nothing over the top.

Why you will hit it

Not through carelessness. Through sequence.

Onboarding a new solution goes: create the folder, wire up the pipeline, connect
the source workspace, commit the items. Between step one and step four the
folder exists and is empty.

We were sitting in exactly that state across two of three solutions when I
noticed. The folders existed. Each contained one auto-generated placeholder file
and no actual items.

If anything had promoted to those environments in that window, cleanup would
have run against a populated target with an empty source.

The guard

def assert_source_not_empty(directory, solution, environment):
    item_count = count_fabric_items(directory)
    if item_count > 0:
        return item_count

    if read_bool("ALLOW_EMPTY_SOURCE"):
        print("WARNING: {} contains no items, but ALLOW_EMPTY_SOURCE is set."
              .format(directory))
        return 0

    fail(
        "Solution '{}' has no items under {}.\n"
        "Refusing to deploy to {} because orphan removal would treat every "
        "item in the target workspace as an orphan and delete it.\n"
        "Connect the source workspace and commit its items first."
        .format(solution.key, directory, environment)
    )

Three things I would keep if I wrote it again:

It runs before any API call. Not before cleanup — before the SDK is even
loaded. Nothing has authenticated, nothing has been resolved, nothing can
partially happen.

The error says what would have happened, not just what is missing. "No items
found" invites someone to force it through. "Would delete everything in the
target" does not.

There is an override, because emptying a workspace is occasionally what you
want. It is explicit, it is not the default, and it logs loudly.

Testing the dangerous thing on a laptop

This is the one piece of logic whose failure mode is destructive, so I wanted it
provable without touching a real workspace.

The cloud SDK imports were moved behind a function:

def _load_fabric_sdk():
    from azure.identity import ClientSecretCredential
    from fabric_cicd import FabricWorkspace, publish_all_items, ...
    return {...}

Everything up to and including the guard is plain path handling. So the tests
run with neither fabric-cicd nor azure-identity installed:

def test_empty_solution_folder_aborts(self):
    with tempfile.TemporaryDirectory() as tmp:
        empty = Path(tmp) / "Fin"
        empty.mkdir()
        (empty / "Readme.md").write_text("placeholder\n")
        with self.assertRaises(SystemExit) as caught:
            deploy.assert_source_not_empty(empty, self.fin, "UAT")
    self.assertEqual(caught.exception.code, 1)

Note the placeholder file in that test. An empty-looking folder is rarely
literally empty — it usually has a README or a .gitkeep. The count has to be
of real items, not of files, or the guard passes when it should not.

The general question

For any tool that deletes by comparison: what happens when one side of the
comparison is empty?

If the answer is "delete everything", decide whether that state is reachable in
normal use. In our case it was not just reachable, it was a required step in
onboarding.

Full context: [https://www.linkedin.com/pulse/enterprise-microsoft-fabric-cicd-selective-one-azure-devops-ghosh-uxzsf/]
Code: [https://github.com/VEDAFORGE/fabric-cicd-reference/tree/v2.0.0]

A green pipeline that deployed nothing

Mintu Ghosh — Thu, 20 Aug 2026 05:55:52 +0000

The worst CI outcome is not a failing build. It is a passing build that did
nothing and looked correct.

Here is one way to get there, and it takes a single missing line of YAML.

The setup

A pipeline that deploys only what changed. It diffs against the parent commit,
maps changed paths onto folders, and conditions each deployment stage on the
result.

files = run_git(["diff", "--name-only", base, head], repo_root)

The failure

Azure DevOps can check out with shallow fetch. A shallow clone has no parent
commit.

So git diff HEAD~1 HEAD does not error. It returns nothing.

Nothing changed, therefore nothing needs deploying, therefore every stage skips,
therefore the pipeline is green. Nobody is alerted, because from the outside
this is exactly what a run looks like when someone edits a README.

You find out later, when something that was supposed to be in production is not.

The fix is two parts

Make the pipeline correct:

- checkout: self
  fetchDepth: 0

And make the script refuse to guess:

if run_git(["rev-parse", "--is-shallow-repository"], repo_root) == "true":
    raise GitError(
        "This is a shallow clone, so there is no history to diff against.\n"
        "Set 'fetchDepth: 0' on the checkout step, or disable shallow fetch "
        "in the pipeline settings."
    )

The second part matters more than the first. fetchDepth: 0 is one line in a
YAML file that someone will eventually remove while tidying up, or that will be
absent when a colleague copies the pipeline into a new project. The check turns
that into a red build with an instruction attached.

And a test, because the line is deletable

def test_detection_stage_checks_out_full_history(self):
    checkout = detect_stage["jobs"][0]["steps"][0]
    self.assertEqual(checkout.get("checkout"), "self")
    self.assertEqual(
        checkout.get("fetchDepth"), 0,
        "change detection needs full history; fetchDepth must be 0",
    )

It parses the pipeline YAML and asserts the line is still there. Slightly
unusual to test your own CI config, but this is a config value with a silent
failure mode, which is exactly the kind worth pinning.

The general shape

Ask of any conditional deployment: what does this do when its input is
missing rather than wrong?

Wrong input usually errors. Missing input often produces an empty result that
looks like a legitimate negative. Empty and "nothing to do" are the same value,
and only one of them is safe.

Anywhere those two are indistinguishable, make the code refuse rather than
assume.

Full context: [https://www.linkedin.com/pulse/enterprise-microsoft-fabric-cicd-selective-one-azure-devops-ghosh-uxzsf]
Code: [https://github.com/VEDAFORGE/fabric-cicd-reference/tree/v2.0.0]

Azure DevOps stage output variables - three things that silently do not work

Mintu Ghosh — Thu, 20 Aug 2026 05:53:32 +0000

I needed one stage to compute something and later stages to condition on it.
Azure DevOps supports this. It also fails silently in three specific ways, and
none of them produce an error message that points at the cause.

Nothing Fabric-specific here. This applies to any multi-stage pipeline.

Setting the variable

- stage: DetectChanges
  jobs:
    - job: Detect
      steps:
        - script: python scripts/detect_changes.py
          name: detect          # <- required

The script writes:

##vso[task.setvariable variable=ved;isOutput=true]true

Reading it

- stage: Deploy_ved
  dependsOn: DetectChanges
  condition: >-
    eq(dependencies.DetectChanges.outputs['Detect.detect.ved'], 'true')

Gotcha 1: the values are strings

eq(dependencies.DetectChanges.outputs['Detect.detect.ved'], true)    # never matches
eq(dependencies.DetectChanges.outputs['Detect.detect.ved'], 'true')  # correct

The first one is valid YAML, valid expression syntax, and always false. Your
stage skips every time and the pipeline goes green because a skipped stage is
not a failed stage.

Quote the value.

Gotcha 2: the reference has three parts, not one

dependencies.<Stage>.outputs['<Job>.<StepName>.<Variable>']
                              ^^^^^ ^^^^^^^^^^ ^^^^^^^^^^

The job name and the step name both appear in the string. Miss either and you
get an empty value rather than an error.

The step name is not displayName. If your step only has a displayName, it
has no addressable name and the variable is unreachable.

Gotcha 3: the consuming stage must declare the dependency

- stage: Deploy_ved
  dependsOn: DetectChanges      # without this the variable cannot resolve

dependencies.X only sees stages this stage actually depends on. Without
dependsOn, the expression resolves to nothing. No error, no warning, and the
condition evaluates false.

Why all three fail the same way

Every one of these produces an empty string, which compares false, which skips
the stage, which is a legitimate outcome that Azure DevOps reports as success.

You get a green pipeline that did nothing. That is worse than a red one, because
nothing prompts you to look.

Debugging it

Print what you set, in the producing job:

- script: echo "ved=$(detect.ved)"

And publish the decision as a build artifact. I write a JSON file from the
detection script and publish it, so every run has a durable record of what it
decided rather than a log line that ages out.

- publish: $(Build.ArtifactStagingDirectory)/change-detection.json
  artifact: change-detection

The one that bit hardest

Not in the list above. A stage skipping is indistinguishable, in the UI, from a
stage that was correctly filtered out.

So when you are looking at a run and thinking "good, the unrelated stages were
skipped", check why they skipped. Branch condition and output-variable
condition look identical in the stage view and mean completely different things.

I nearly used a screenshot as evidence for the wrong claim on exactly that
basis.

Full context: [https://www.linkedin.com/pulse/enterprise-microsoft-fabric-cicd-selective-one-azure-devops-ghosh-uxzsf]
Code: [https://github.com/VEDAFORGE/fabric-cicd-reference/tree/v2.0.0]

Why I left Warehouse out of our Fabric deployment scope

Mintu Ghosh — Mon, 17 Aug 2026 15:01:05 +0000

title: Why I left Warehouse out of our Fabric deployment scope
published: true
tags: microsoftfabric, datawarehouse, cicd, devops

Our Fabric deployment pipeline handles sixteen item types. Warehouse is not one
of them, and that was deliberate.

DEFAULT_ITEM_TYPES = [
    "DataPipeline",
    "Lakehouse",
    "Notebook",
    "SemanticModel",
    # "Warehouse" is intentionally excluded. Warehouse schema deployment must
    # be handled separately to avoid schema reset risk during publish.
    "Environment",
    "Eventhouse",
    ...
]

The reason

Publishing a warehouse through this path can reset its schema.

Not "might behave unexpectedly". The failure mode is that a deployment intended
to be additive removes structure, and the thing that removes it is the same
routine that successfully deploys the other sixteen types.

The choice that follows

Two options once you know that.

Include it and hope nobody deploys a warehouse without reading the docs. The
pipeline supports everything, and one day someone promotes a change on a Friday
and finds out.

Or exclude it, document why, and handle warehouse deployment as its own problem
with its own tooling.

I took the second. An automation that covers most cases and silently corrupts
the rest is worse than one that covers most cases and refuses the rest. The
refusal is visible. The corruption is not.

Making the exclusion loud

An exclusion is only useful if someone notices it. Three things help:

The comment sits inside the list, not in a doc nobody opens. Anyone reading
the item types sees the gap and the reason in the same glance.

It is in the README under known limitations, next to the other things the
framework does not do.

There is a test. It asserts Warehouse is absent from the default scope:

def test_warehouse_stays_excluded(self):
    """Warehouse publish can reset schema, so it is handled separately."""
    self.assertNotIn("Warehouse", deploy.DEFAULT_ITEM_TYPES)

That test looks silly. It is asserting that a string is missing from a list.

It exists because the natural instinct, when someone hits "my warehouse did not
deploy", is to add the string to the list. The test turns that into a failing
build with an explanation attached, instead of a merged one-line change that
nobody reviews closely.

What I would want next

The honest gap: excluding it does not solve warehouse deployment, it defers it.
Teams that need warehouse promotion still need an answer, and mine is currently
"do it separately, carefully".

That is a real limitation rather than a design choice, and worth saying so.

Full context: [https://www.linkedin.com/pulse/building-enterprise-microsoft-fabric-cicd-practical-guide-mintu-ghosh-f3dbf/]
Code: [https://github.com/vedaforge-team/fabric-cicd-reference/tree/v1.0.0]

The refactor that made every validation build pass without validating anything

Mintu Ghosh — Sat, 15 Aug 2026 10:45:19 +0000

Short one. A bug I introduced, caught by reading the diff rather than by any
test, and the reason no test could have caught it.

The setup

A deployment script with a validation mode. On the develop branch it runs with
VALIDATE_ONLY=true and is supposed to check everything without writing
anything.

Original order:

workspace = build_workspace()      # authenticate, resolve, parse

if read_bool("VALIDATE_ONLY"):
    print("Validation-only mode. No workspace changes applied.")
    return

publish_all_items(workspace)

What I did

I was restructuring the function and moved things around for readability. The
result:

if read_bool("VALIDATE_ONLY"):
    print("Validation-only mode. No workspace changes applied.")
    return

workspace = build_workspace()      # now unreachable in validation mode
publish_all_items(workspace)

Looks tidier. Nothing writes to a workspace in either version. Every test passed.

Why it is broken

build_workspace() is not setup code. It is the validation.

Constructing that object authenticates the service principal, resolves the
target workspace over the API, and parses every item in the repository. Most of
what can be wrong is discovered right there.

Return before it and the validation stage prints a reassuring message, exits
zero, and has checked nothing. Every build on the validation branch goes green.
Broken items reach the release branch unnoticed.

Why the tests did not catch it

Every test asserted what the code did: it did not publish, it did not remove
orphans, it exited cleanly. All still true.

Nothing asserted that validation actually validates. There was no test for
"the workspace object gets built before the early return", because that reads
like testing an implementation detail right up until the moment it is the entire
safety property.

What I changed

Restored the order, and left a comment explaining why the line is where it is:

# Built before the validate-only check on purpose. Constructing the
# FabricWorkspace authenticates, resolves the target workspace and parses
# every item, so it is the part that actually validates. Returning before
# this would make develop builds green without checking anything.
workspace = build_workspace()

A comment is a weak guard. But the alternative — a test that asserts an
authentication call happens in a mode defined by not doing anything — is awkward
enough that I would rather the next person read one sentence.

The general version

A refactor can hollow out a safety check while the whole suite stays green, when
the tests assert absence of effects rather than presence of the check.

If you have a validate-only or dry-run mode, ask what in it is actually doing
the validating, and whether anything would notice if that stopped happening.

Full context: [https://www.linkedin.com/pulse/building-enterprise-microsoft-fabric-cicd-practical-guide-mintu-ghosh-f3dbf/]

Code: [https://github.com/vedaforge-team/fabric-cicd-reference/tree/v1.0.0]

Your Fabric deployment failed and it is probably not your code

Mintu Ghosh — Sat, 15 Aug 2026 10:42:09 +0000

I wrote a deployment script for Microsoft Fabric. It is a thin wrapper around
the fabric-cicd library. Maybe 150 lines with the comments.

Then I wrote down everything that has to be true before it works. That list came
to 43 items.

That ratio is the thing worth knowing before you start.

The breakdown

Category	Checks
Fabric environment	6
Identity and security	10
Azure DevOps configuration	10
Deployment configuration	7
Deployment validation	4
Post-deployment verification	6

Identity is the largest, and three of those ten are the same check repeated once
per environment: is the service principal actually a member of this
workspace.

DEV, UAT and PROD, separately. Adding it to one does nothing for the others.

Why this is annoying specifically

Nothing in your repository indicates a permission is missing. The code is
byte-identical whether the service principal has access to all three workspaces
or none of them.

So the failure surfaces at the deployment step, which is the last thing in the
chain and the first thing you look at. The error is real. The deployment did
fail. Your code is fine.

You start debugging in the wrong place by default, and the stack trace does not
help because there is nothing wrong with the stack.

Two of them are not settings

Two items on the list are architectural decisions wearing checkbox clothing:

Only the Development workspace is connected to Git
UAT and PROD are deployment targets only

Connect UAT to Git as well and that environment now has two sources of truth:
the repository, and whoever last edited the workspace in the browser. Both look
current. Nothing errors. You find out during an incident, when the thing you
deployed is not the thing running.

A checkbox is a strange home for a decision that consequential. It belongs there
anyway, because it has to hold before anything downstream means anything.

The practical takeaway

Check before you run, not after it fails. Diagnosing a missing prerequisite from
a deployment error is slower than confirming it up front, every time.

The full checklist is published here:
docs/checklists/DEPLOYMENT_READINESS_CHECKLIST.md in [https://github.com/vedaforge-team/fabric-cicd-reference/tree/v1.0.0].

Of everything that implementation produced, it is the part I still use.

Full walkthrough: [https://www.linkedin.com/pulse/building-enterprise-microsoft-fabric-cicd-practical-guide-mintu-ghosh-f3dbf/].

Deploy only what changed - selective deployment in an Azure DevOps monorepo

Mintu Ghosh — Fri, 14 Aug 2026 09:47:36 +0000

Three teams share one repository. A commit touching one team's folder must not
redeploy the other two.

The obvious answer is trigger path filters. They do not work for this, and the
reason is worth understanding before you build anything.

This is Microsoft Fabric, but the mechanism is generic. If you have a monorepo
and an Azure DevOps pipeline, it applies.

Why path filters do not solve it

trigger:
  branches:
    include: [develop, release, main]
  paths:
    include: [teams/alpha]   # <- decides IF the pipeline runs

A trigger path filter answers one question: should this pipeline run at all. It
cannot tell a later stage which folder changed, because it produces no
variable anything downstream can read.

You could make one pipeline per team. Then every fix is made three times and
they drift.

The actual constraint

Azure DevOps builds its stage graph at compile time. Change detection can
only answer at run time. Stages cannot be created dynamically.

So generate every stage for every team, always, and let run-time detection
decide which execute. Unaffected ones render as Skipped.

That turns out to be better than dynamic generation. A skipped stage is visible
evidence the pipeline considered that team and chose not to deploy it. A graph
that never mentions the team proves nothing.

Choosing the diff baseline

There is no single "previous commit" that is right everywhere. Derive it from
the shape of HEAD:

parts = run_git(["rev-list", "--parents", "-n", "1", head], repo_root).split()
parent_count = len(parts) - 1

if parent_count >= 2:
    return head + "^1", head, "merge commit (first parent)"
if parent_count == 1:
    return head + "~1", head, "single parent"
return None, head, "root commit (no parent)"

The pleasing part: Azure DevOps PR builds check out a merge of source into
target, so the first parent is the target branch before the merge. The
first-parent rule covers PR builds, merge-commit promotions and squash merges
without special-casing any of them. I never needed the System.PullRequest
variables.

Known gap, documented rather than engineered around: a multi-commit push is
evaluated from HEAD~1, so only the last commit is inspected. Promotion goes
through PRs where the full change set is visible, so this only affects direct
pushes to the validate-only branch.

The failure mode that looks like success

A shallow clone has no parent to diff against. Git returns an empty diff,
not an error. Every deployment skips and the run stays green.

That is a false negative that looks like a pass. Fail loudly instead:

if run_git(["rev-parse", "--is-shallow-repository"], repo_root) == "true":
    raise GitError(
        "This is a shallow clone, so there is no history to diff against.\n"
        "Set 'fetchDepth: 0' on the checkout step, or disable shallow fetch."
    )

And on the detection job:

- checkout: self
  fetchDepth: 0

I have a test asserting the pipeline still sets fetchDepth: 0, because it is
the kind of line someone removes while tidying.

Publishing the result

for solution in registry.solutions:
    value = "true" if result["solutions"][solution.key] else "false"
    print("##vso[task.setvariable variable={};isOutput=true]{}".format(
        solution.key, value))

Consuming it:

- stage: Deploy_UAT_ved
  dependsOn: DetectChanges
  condition: >-
    and(
      succeeded(),
      eq(dependencies.DetectChanges.outputs['Detect.detect.ved'], 'true'),
      eq(variables['Build.SourceBranch'], 'refs/heads/release')
    )

Three things people get wrong here:

Values are strings. eq(..., true) never matches. It must be 'true'.
The reference has three parts — job name, step name, variable name: dependencies.<Stage>.outputs['<Job>.<step>.<var>'].
The consuming stage must dependsOn the producing stage, or the variable cannot be resolved at all.

Two conditions, not one

Every stage carries both:

detection decides which solutions changed
branch decides where they may deploy

Both must hold. Detection never widens the branch rule and the branch rule never
widens detection.

This matters when reading results. A stage shows "Skipped" for either reason,
and they prove different things. On the production branch, every validate and UAT
stage skips for branch reasons while solutions still deploy. That is promotion
control, not isolation. Isolation is a stage skipping while a sibling at the same
tier succeeds.

I nearly captioned a screenshot wrong on exactly this point.

Resolving config without duplication

Solution plus environment becomes a variable name at compile time:

TARGET_WORKSPACE_ID: ${{ format('$({0}_{1}_WORKSPACE_ID)',
                        upper(parameters.solution),
                        upper(parameters.environment)) }}

ved + UAT expands to $(VED_UAT_WORKSPACE_ID), resolved from the stage's
variable group at run time. The identifier never enters the repository.

Scope the deployment, and refuse an empty source

Two guards worth having, both learned the hard way.

Reject the repository root. A root-scoped deployment sweeps every team's
artifacts into one target, and the cleanup that follows is evaluated against the
wrong set.

Refuse an empty source folder. Orphan removal treats "present in target,
absent from source" as delete. An empty folder therefore means everything in
the target is an orphan. A folder created but not yet populated is a normal
intermediate state, so it has to fail safely rather than proceed.

if item_count == 0 and not read_bool("ALLOW_EMPTY_SOURCE"):
    fail("Solution has no items. Refusing to deploy: orphan removal would "
         "treat every item in the target as an orphan and delete it.")

Test it without touching the cloud

The classifier is a pure function: changed paths in, decision out. That makes
the whole matrix testable offline.

def test_d_ved_and_hr(self):
    self.assertAffected(
        ["fabric-workspaces/Ved/Notebook.Notebook/notebook-content.py",
         "fabric-workspaces/HR/Notebook.Notebook/notebook-content.py"],
        ["ved", "hr"],
    )

70 tests, stdlib unittest, no pytest, no cloud access, under a tenth of a
second. The six scenarios that matter — one team, each other team, two teams,
all three, docs-only — are verified before any pipeline runs.

One test I had to rewrite: it asserted a folder held exactly four items. True
when written, false the moment someone authored a fifth. Do not couple tests to
live content; use fixtures for exact counts.

Verified end to end

Branch	Detected	Result
develop	one solution, 2 files	that one validated, other two skipped
release	one solution, 4 files	that one deployed to UAT, other two skipped
main	all three, 39 files	all three to PROD, all validate and UAT stages skipped

Edge case that works: item names containing spaces.

What it still does not do

No approval gates
Multi-commit pushes inspect only the last commit
A shared framework change deploys nothing by design; there is a manual override parameter for rolling one out deliberately

Full walkthrough: [https://www.linkedin.com/pulse/enterprise-microsoft-fabric-cicd-selective-one-azure-devops-ghosh-uxzsf/].
Code, including the test suite:
[https://github.com/vedaforge-team/fabric-cicd-reference/tree/v2.0.0].

Deploying Microsoft Fabric items from Azure DevOps with a service principal

Mintu Ghosh — Thu, 13 Aug 2026 17:55:00 +0000

Microsoft Fabric workspaces are edited in a browser. That works until you have
more than one environment and need changes to move between them with a review
step and a way back.

This is the smallest thing that does that: one Python script, one Azure DevOps
pipeline, three branches, three workspaces. Runs as a service principal, so no
human session is involved.

Full code: [https://github.com/vedaforge-team/fabric-cicd-reference/tree/v1.0.0].
This post covers the parts worth understanding
before you copy it.

The shape

Development workspace  --(Fabric Git integration)-->  Azure DevOps repo
                                                            |
                                        develop  ->  validate against DEV
                                        release  ->  deploy to UAT
                                        main     ->  deploy to PROD

Only the Development workspace is Git-connected. UAT and PROD are reached over
the Fabric REST API by the pipeline.

Connect UAT to Git as well and that environment has two sources of truth: the
repository, and whoever last edited the workspace directly. Both will look
current. Nothing errors.

The script is a thin wrapper

Everything environment-specific arrives as an environment variable. The pipeline
supplies them from variable groups.

def build_workspace() -> FabricWorkspace:
    credential = ClientSecretCredential(
        tenant_id=read_env("TENANT_ID"),
        client_id=read_env("CLIENT_ID"),
        client_secret=read_env("CLIENT_SECRET"),
    )
    return FabricWorkspace(
        workspace_id=read_env("TARGET_WORKSPACE_ID"),
        environment=read_env("TARGET_ENVIRONMENT_NAME"),
        repository_directory=repository_directory,
        item_type_in_scope=read_csv("ITEM_TYPES_IN_SCOPE", DEFAULT_ITEM_TYPES),
        token_credential=credential,
        exclude_paths=read_csv("EXCLUDE_FOLDERS"),
    )

Twelve variables in total, covering authentication, the target workspace, the
source directory, and switches for validation and cleanup.

Validate-only is not a no-op

The develop branch runs the same script with VALIDATE_ONLY=true. Ordering
matters more than it looks:

workspace = build_workspace()          # authenticates, resolves, parses

if read_bool("VALIDATE_ONLY"):
    print("Validation-only mode. No workspace changes applied.")
    return

if read_bool("REMOVE_ORPHANS", True):
    unpublish_all_orphan_items(workspace)
publish_all_items(workspace)

Constructing FabricWorkspace is what authenticates the service principal,
resolves the target workspace and parses every item in the repository. It is the
validation. Return before it and every develop build goes green having checked
nothing.

Worth a test that asserts validation actually validates, because a refactor that
moves that line will not otherwise fail anything.

Branch gating

Three stages, each gated only by the branch. No dependsOn between them.

- stage: Deploy_UAT
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/release'))
  variables:
    - group: VG-Fabric-UAT

There is no automatic DEV to UAT to PROD chain. Promotion happens when someone
merges a pull request, which is where review happens. A commit never walks itself
into production.

Warehouse is excluded on purpose

Sixteen item types are in scope. Warehouse is not:

DEFAULT_ITEM_TYPES = [
    "DataPipeline", "Lakehouse", "Notebook", "SemanticModel",
    # "Warehouse" is intentionally excluded. Warehouse schema deployment must
    # be handled separately to avoid schema reset risk during publish.
    "Environment", "Eventhouse", "Eventstream", "KQLDatabase",
    ...
]

Publishing a warehouse through this path can reset its schema. An automation
that handles most cases and silently corrupts the rest is worse than one that
refuses the rest.

The part that actually breaks

The code above is not where deployments fail. They fail on prerequisites.

I ended up writing them down and there are 43, across six categories: Fabric
environment (6), identity and security (10), Azure DevOps configuration (10),
deployment configuration (7), validation (4), post-deployment verification (6).

Identity is the largest, and three of those ten are the same check repeated per
environment: is the service principal actually a member of this workspace. It
needs to be added to DEV, UAT and PROD separately. Nothing in the repository
indicates when it is missing.

That produces a misleading failure mode. A missing permission surfaces as an
error thrown by the deployment step, which is the last thing in the chain and
the first thing you look at. The error is real, the deployment did fail, and the
code is fine.

The checklist is in the repo at docs/checklists/DEPLOYMENT_READINESS_CHECKLIST.md.
Of everything this produced, it is the part I would copy first.

Environment template

TENANT_ID=
CLIENT_ID=
CLIENT_SECRET=
TARGET_WORKSPACE_ID=
TARGET_ENVIRONMENT_NAME=DEV
REPOSITORY_DIRECTORY=./.
VALIDATE_ONLY=true
REMOVE_ORPHANS=true
ENABLE_SHORTCUT_PUBLISH=true
LOG_LEVEL=INFO

Keep VALIDATE_ONLY=true until you are sure the target is right.

Known limitations

No approval gates. A merge to main deploys production unattended.
No parameter.yml, so items referencing a workspace-specific resource by GUID still point at the source environment after deployment.
One solution per repository. The layout and variable naming assume it.

Stack: fabric-cicd 1.2.0, Python 3.12, ubuntu-latest.

Full walkthrough: [https://www.linkedin.com/pulse/building-enterprise-microsoft-fabric-cicd-practical-guide-mintu-ghosh-f3dbf/]

Code: [https://github.com/vedaforge-team/fabric-cicd-reference/tree/v1.0.0].

Next post covers what happens when a second team needs the same repository, and
why "just add path filters" does not work.