Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry
x-ms-fabric-skill: deployment-pipelines-authoring-cli (az rest: --headers "x-ms-fabric-skill=deployment-pipelines-authoring-cli"),
including every LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.
CRITICAL NOTES
- To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
- To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering
- To find a deployment pipeline or stage ID: list deployment pipelines (then stages) and filter by
displayName with JMESPath — never guess IDs.
Fabric Deployment Pipelines Authoring — CLI Skill
Automates Fabric Application Lifecycle Management (ALM) with deployment pipelines: promote Fabric
content between stages (typically Development → Test → Production) using the Fabric core control-plane
REST API. This skill covers pipeline/stage lifecycle, workspace assignment, and stage-to-stage deployment
(a long-running operation).
Prerequisite Knowledge
Read these companion documents first — this skill assumes their patterns and does not repeat them:
This skill adds: how to drive the deployment-pipelines REST surface from an agentic terminal.
Concepts
- A deployment pipeline contains 2–10 ordered stages (
order starts at 0). Each stage may have at
most one assigned workspace, and a workspace can be assigned to at most one stage.
- Deployment copies supported item content from a source stage to an adjacent target stage.
Forward deploys (dev→test→prod) work between any adjacent stages. Backward deploys (e.g. prod→test)
are currently supported only when the target stage is empty (no assigned workspace) — you cannot
backward-deploy over a stage that already has a workspace.
- Item pairing (autobinding). During deployment Fabric records a connection between a source item and
its clone in the target stage; this pairing is how later deploys know which target item to overwrite,
and how related items (e.g. a report and its semantic model) stay bound. There is no REST API to set
pairing — it is maintained automatically — but you can observe the current pairing via the
sourceItemId / targetItemId fields returned by List stage items. See the Fix a broken item pairing
workflow below for the only supported repair.
- Deploy is an asynchronous long-running operation (LRO): the API returns
202 Accepted with an
operation ID; you poll for completion.
- Deployment rules and parameter rules (e.g. repoint a data source per stage) are configured in the
Fabric portal UI — there is no REST API to create rules. Do not claim otherwise.
- Only supported item types are copied by a deploy; unsupported items are skipped (not an error). The
supported set changes over time — see references/supported-item-types.md.
- There is no "what changed" / compare REST API.
List stage items returns item identity + pairing
(itemId, itemDisplayName, itemType, sourceItemId, targetItemId, lastDeploymentTime) — but no
change status, and lastDeploymentTime is the last deployment time, not the last edit time, so
it is not a reliable change signal. To deploy only changed items you must diff the two stages yourself
and build the items list (see the Deploy only changed items workflow below). The portal's "Compare"
view is server-side and not exposed via API.
Must/Prefer/Avoid
MUST DO
- Resolve pipeline, stage, and workspace IDs by name via list + JMESPath before any mutating call. Never fabricate GUIDs.
- Target the correct base URL:
https://api.fabric.microsoft.com/v1/deploymentPipelines and acquire a token for the https://api.fabric.microsoft.com audience.
- Treat Deploy Stage Content as an LRO: on
202, capture the operation ID and poll /v1/operations/{operationId} until the state is Succeeded/Failed, then surface the result.
- When the target stage has no assigned workspace, include
createdWorkspaceDetails (name, and capacityId when needed) in the deploy body, or the deploy fails.
- Confirm destructive intent (delete pipeline, unassign workspace, backward deploy over prod) with the user before executing.
- Verify the caller has the required permissions before a mutating call (see Required permissions below): pipeline Admin for every pipeline operation, plus the appropriate workspace role for assign/deploy. Surface a clear, actionable message on
401/403 rather than retrying blindly.
PREFER
- Selective deploys via the
items array ({ sourceItemId, itemType }) when the user names specific items; omit items to deploy all supported items.
- A human-readable
note on every deploy — but know it is write-only: the API accepts it and never
returns it (it appears only in the portal UI). For a programmatic audit trail, also record the deploy
externally (CI/CD logs or a Git commit message).
List Deployment Pipeline Stage Items to preview what will move before deploying.
- Idempotent scripting: check whether a pipeline/stage/assignment already exists before creating it.
AVOID
- Inventing a "create deployment rule" or "parameter rule" REST call — those are UI-only today.
- Assigning a workspace during an active deployment (the assign call fails) or to a stage/workspace that is already paired.
- Hardcoding
api.fabric.microsoft.com in sovereign clouds — resolve the host from environment config.
- Using a service principal without first confirming the Fabric admin enabled SP creation of deployment pipelines.
- Hashing raw
getDefinition output to detect changes without normalizing. Deployment auto-rebinds
embedded references in the target (pipeline notebookId/workspaceId, report→model id, Direct Lake
server/db), so a paired target's definition legitimately differs from the source even when nothing was
edited — naive hashing reports false "changed". Strip/normalize those binding fields before comparing.
- Diffing by dumping every item definition into the agent's context. A full two-stage content diff can be
dozens of
getDefinition calls and >100 KB — do the compare in a script
(references/scripts/diff_item_definitions.py) and surface only
the resulting change list, and for a changed item forward only the emitted diff, never the two full
definitions, to the model.
- Unassigning a workspace to repair a broken pairing without first warning the user that unassign
permanently deletes that stage's deployment history and its configured deployment/parameter rules —
always ask whether the stage has rules before unassigning (see Fix a broken item pairing).
REST API Reference
Base: https://api.fabric.microsoft.com/v1. Delegated scopes are per operation — provision a service
principal with least privilege:
| Operation |
Required delegated scope |
| List / Get (pipelines, stages, stage items, operations) |
Pipeline.Read.All or Pipeline.ReadWrite.All |
| Create / Update / Delete pipeline, Update stage |
Pipeline.ReadWrite.All |
| Assign / Unassign workspace |
Pipeline.ReadWrite.All and Workspace.ReadWrite.All |
| Deploy stage content |
Pipeline.Deploy |
Deploy uses its own Pipeline.Deploy scope — an app scoped only to Pipeline.ReadWrite.All gets a 403
on POST .../deploy.
| Operation |
Method + Path |
| List pipelines |
GET /deploymentPipelines |
| Create pipeline |
POST /deploymentPipelines |
| Get / Update / Delete pipeline |
`GET |
| List / Get stages |
GET /deploymentPipelines/{id}/stages[/{stageId}] |
| Update stage |
PATCH /deploymentPipelines/{id}/stages/{stageId} |
| List stage items |
GET /deploymentPipelines/{id}/stages/{stageId}/items |
| Assign workspace to stage |
POST /deploymentPipelines/{id}/stages/{stageId}/assignWorkspace |
| Unassign workspace from stage |
POST /deploymentPipelines/{id}/stages/{stageId}/unassignWorkspace |
| Deploy stage content (LRO) |
POST /deploymentPipelines/{id}/deploy |
| List operations (≤20 recent) |
GET /deploymentPipelines/{id}/operations |
| Get operation (with execution plan) |
GET /deploymentPipelines/{id}/operations/{operationId} |
| Role assignments |
`GET |
Request-body shapes (guidance)
- Create:
{ "displayName", "description"?, "stages": [ { "displayName", "description"?, "isPublic" } ] } — 2–10 stages.
- Assign workspace:
{ "workspaceId" }.
- Deploy:
{ "sourceStageId", "targetStageId", "items"?: [ { "sourceItemId", "itemType" } ], "note"?, "options"?: { "allowCrossRegionDeployment": false }, "createdWorkspaceDetails"?: { "name", "capacityId"? } }.
Required permissions
Deployment pipeline operations are governed by two independent permission systems: your role on the
pipeline (its own roleAssignments) and your role on each workspace involved. You generally need
both. Deployment pipelines require a Fabric capacity/subscription, and the pipeline creator becomes the
pipeline Admin.
| Operation |
Pipeline role |
Workspace role(s) |
| Create a pipeline |
— (becomes Admin on create) |
Admin of a Fabric workspace (feature access prerequisite) |
| Get / list pipeline, stages, items, operations |
Admin (shared access) |
— |
Update / delete pipeline; manage roleAssignments |
Admin |
— |
| Assign / unassign a workspace to a stage |
Admin |
Admin of the workspace being (un)assigned |
| Deploy stage content |
Admin |
at least Contributor/Member on both the source and target stage workspaces (higher role if the target items require it) |
| Deploy to an empty target stage (creates a workspace) |
Admin |
capacity-assignment permission to place the new workspace on a capacity; the deploying user becomes the only Admin of the newly created workspace and owner of cloned semantic models |
Notes:
- Sharing a pipeline grants the pipeline Admin role — there is no lower "viewer-only" pipeline write role for these operations.
- A service principal can drive these APIs only if the Fabric admin enabled service principals can create deployment pipelines (and the SP holds the same pipeline + workspace roles above).
- On
403, distinguish missing pipeline role from missing workspace role in the message so the user knows which access to request.
Create a pipeline → POST the display name + ordered stages; capture the returned stage IDs (they are
what you deploy between).
Assign a workspace to a stage → resolve stage ID and workspace ID by name, verify both are unassigned,
then POST assignWorkspace. Requires admin on both the pipeline and the workspace.
Deploy content → resolve source/target stage IDs, optionally preview stage items, POST deploy (all
items or a selected items list) with a note, then poll the returned operation to completion and report
which items moved.
Deploy only changed items → there is no diff/compare API, so compute the delta yourself. List stage items gives identity + pairing only (no timestamps, no change status), so change detection means comparing
item definitions:
- Resolve the source and target stage IDs and the workspace assigned to each.
- List items in both stages (
GET .../stages/{stageId}/items) — each source row carries sourceItemId
(as itemId) and its paired targetItemId (absent = new/unpaired). Also list the target stage to find
deleted items (present in target, not paired from any source). Pair by targetItemId; fall back to
(itemType, displayName) only when no pipeline pairing exists (name-matching can't detect renames).
- Filter out system-managed children — a
SQLEndpoint is auto-created per Lakehouse/Warehouse and should
not be diffed or deployed on its own; it follows its parent.
- Classify each paired item:
- New (no
targetItemId) → deploy.
- Changed → detect via
POST .../items/{id}/getDefinition on both stages, then diff. Run
references/scripts/diff_item_definitions.py on the two
responses: it decodes each part, normalizes the auto-rebound fields (pipeline notebookId/
workspaceId, report model id, Direct Lake server/db) for you, and prints only the differing parts
(exit 1 = changed, 0 = identical) — so you don't hand-roll hashing or false-positive on unedited
items. Note the getDefinition contract differs by type:
Notebook/SemanticModel/Report are LRO (202 → poll → GET .../result);
DataPipeline returns 200 synchronously.
- Types without a usable
getDefinition diff: Warehouse has no item-definition API, and
Lakehouse / Environment do expose getDefinition but their definitions capture structure/metadata
only (not table data or most content edits) — so for all three, diff by presence and treat as changed
only when new or when the user indicates content changed.
- When you cannot prove equality, treat the item as changed (safe default).
- Do the comparison in a script (parallelize the independent
getDefinition calls; they dominate
latency) and surface only the computed change list. To let the model reason about what changed in an
item, forward only the emitted diff (diff_item_definitions.py output), not the two full definitions —
a normalized diff is typically a few lines versus the >100 KB of raw payloads.
- Filter to supported item types (see references), show the user the change list, confirm, then POST a
selective
deploy with the { sourceItemId, itemType } array and a note, and poll to completion.
Deletions do not propagate via a selective items deploy — an item removed from the source stage is not
removed from the target by a selective deploy. Use a full deploy (omit items) to propagate deletions,
or delete the target item manually, and warn the user of this before promoting.
Fix a broken item pairing → pairing (the source↔target connection Fabric maintains, a.k.a. autobinding)
is not settable via any REST API. When two items that should be paired across stages are not — surfaced
by a deploy that duplicates an item instead of overwriting it, an autobind/dependency failure, or the user
reporting it — the only supported repair is to unassign the affected stage's workspace and re-assign it,
which forces Fabric to rebuild the pairing on the next deploy. This is destructive:
- Warn the user first. Unassigning a workspace permanently deletes that stage's deployment history and
all its configured deployment/parameter rules — they cannot be recovered by re-assigning.
- Ask whether the stage has rules. Because rules are UI-only (no REST API to read or recreate them),
explicitly ask the user whether the stage has deployment/parameter rules configured before unassigning.
If it does, have them record the rules (or recreate them in the portal afterward) and get explicit
confirmation to proceed.
- Only after confirmation,
POST .../stages/{stageId}/unassignWorkspace, then
POST .../stages/{stageId}/assignWorkspace with the same workspaceId, and re-run the deploy so the
pairing is re-established.
Track / audit → List operations for recent history; Get operation to inspect the execution plan and
per-item status of a specific deployment.
Deploy operational caveats & common errors
- One deploy per pipeline at a time. A pipeline runs a single operation at a time; starting another while
one is in flight fails with
WorkspaceMigrationOperationInProgress (HTTP 400). Always poll the current
operation to a terminal state before starting the next stage promotion (this is also why the assign
workspace call fails during an active deployment).
- First deploy after assigning a workspace can fail with
Alm_InvalidRequest_WorkloadUnavailable. Newly
assigned workspaces need ~60–120 s for workload services (Lakehouse, Notebook, etc.) to initialize.
Mitigate by waiting before the first deploy, or deploy Power BI items (SemanticModel, Report) first and
Fabric-native items (Lakehouse, Notebook) after a short delay; retry on this error. Subsequent deploys
are reliable once workloads are warm.
- The operation ID is returned in the
x-ms-operation-id response header (alongside Location), not the
202 body. az rest does not surface response headers cleanly — for reliable header capture in automation,
issue the deploy with curl -i (or Python requests) and parse the header, then poll
/v1/operations/{operationId} with az rest.
- Deploy copies definitions, not data. Only item metadata/definitions are promoted; table data, query
results, and caches are not. Trigger refreshes/loads in the target stage after a deploy.
- Maximum 300 items per deploy request. A selective (or full) deploy is capped at 300 deployed items;
batch larger promotions across multiple deploy calls.
Examples
Create a three-stage pipeline
Deployment-pipeline displayName is unique tenant-wide — a create for a name
already in use fails with Alm_InvalidRequest_DuplicateAlmPipelineName (HTTP 400,
"pipeline name ... is already in use"). To make a create re-runnable, drop any
existing pipeline of that name first, then create. Write the JSON body to a file
and pass it with --body @file.json — an inline multi-line --body '{...}' is
mangled into an empty body on Windows/PowerShell (az is az.cmd), which the API
rejects with InvalidInput: Unexpected end when reading JSON.
# Idempotent: delete an existing "Sales Analytics ALM" if present, then create.
EXISTING=$(az rest --method GET --resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines" \
--query "value[?displayName=='Sales Analytics ALM'].id | [0]" --output tsv)
if [ -n "$EXISTING" ]; then
az rest --method DELETE --resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$EXISTING"
fi
cat > /tmp/create-pipeline.json << 'EOF'
{
"displayName": "Sales Analytics ALM",
"description": "Dev/Test/Prod promotion for Sales Analytics",
"stages": [
{ "displayName": "Development", "isPublic": false },
{ "displayName": "Test", "isPublic": false },
{ "displayName": "Production", "isPublic": true }
]
}
EOF
az rest --method POST \
--resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines" \
--headers "Content-Type=application/json" \
--body @/tmp/create-pipeline.json
Assign a workspace to the Development stage
# $PIPELINE_ID and $DEV_STAGE_ID resolved via list + JMESPath; $WS_ID resolved from workspace name.
az rest --method POST \
--resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/stages/$DEV_STAGE_ID/assignWorkspace" \
--headers "Content-Type=application/json" \
--body "{ \"workspaceId\": \"$WS_ID\" }"
Deploy all items dev → test and wait for the LRO
# Kick off the deployment (returns 202 + an operation id header).
az rest --method POST \
--resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
--headers "Content-Type=application/json" \
--body "{ \"sourceStageId\": \"$DEV_STAGE_ID\", \"targetStageId\": \"$TEST_STAGE_ID\", \"note\": \"Promote validated dev build\" }" \
--verbose
# Then poll /v1/operations/{operationId} until state is Succeeded or Failed
# (see COMMON-CLI § Long-Running Operations pattern).
Deploy only selected items
az rest --method POST \
--resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
--headers "Content-Type=application/json" \
--body '{
"sourceStageId": "'"$TEST_STAGE_ID"'",
"targetStageId": "'"$PROD_STAGE_ID"'",
"items": [
{ "sourceItemId": "'"$MODEL_ID"'", "itemType": "SemanticModel" },
{ "sourceItemId": "'"$REPORT_ID"'", "itemType": "Report" }
],
"note": "Promote reviewed model + report to production"
}'
Deploy only the items that changed (compute the diff first)
# 1. List paired items for BOTH stages. Each source row carries itemId (= sourceItemId)
# and its paired targetItemId (absent = new/unpaired). There is NO timestamp or
# change-status field, so "changed" must be detected from item definitions.
az rest --method GET --resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/stages/$SOURCE_STAGE_ID/items" \
> source-items.json
# 2. NEW items = unpaired (no targetItemId). Exclude system-managed SQLEndpoint children.
NEW=$(jq '[.value[]
| select(.itemType != "SQLEndpoint")
| select(has("targetItemId") | not)
| { sourceItemId: .itemId, itemType: .itemType }]' source-items.json)
# 3. CHANGED items (paired): fetch getDefinition from BOTH stages, then diff with
# references/scripts/diff_item_definitions.py. It decodes each part, NORMALIZES the
# auto-rebound fields (notebookId/workspaceId in pipelines, model id in reports,
# server/db in Direct Lake models) and prints ONLY the differing parts. Notebook/
# SemanticModel/Report are LRO (202 -> poll -> /result); DataPipeline returns 200 sync.
# Parallelize the independent getDefinition calls. Per paired definition-backed item:
# getDefinition SOURCE_WS id > src.json
# getDefinition TARGET_WS targetItemId > tgt.json
# python references/scripts/diff_item_definitions.py src.json tgt.json > diff.json
# # exit 1 = changed -> add { sourceItemId, itemType } to $ITEMS; exit 0 = unchanged.
# # Forward diff.json (NOT src.json/tgt.json) to the model to explain the change.
# Merge NEW + CHANGED into $ITEMS. When equality can't be proven, include the item.
# 4. Selective deploy of just the changed set.
az rest --method POST --resource https://api.fabric.microsoft.com \
--url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
--headers "Content-Type=application/json" \
--body "$(jq -n --arg s "$SOURCE_STAGE_ID" --arg t "$TARGET_STAGE_ID" --argjson items "$ITEMS" \
'{ sourceStageId: $s, targetStageId: $t, items: $items, note: "Deploy only changed items" }')"
# Then poll /v1/operations/{operationId} until terminal.
# NOTE: a selective deploy does NOT propagate deletions — use a full deploy (omit items) for those.
Prompt/response
User: "Promote my Sales dev workspace to the Test stage and tell me when it's done."
Assistant (behavior):
- Lists deployment pipelines → filters to the one whose Development stage holds the Sales dev workspace; captures
sourceStageId (Development) and targetStageId (Test).
- Confirms the Test stage has an assigned workspace (or asks for a name + capacity to create one).
- POSTs
deploy with a note, receives 202, extracts the operation ID.
- Polls
/v1/operations/{operationId} until terminal, then reports success and the list of deployed items (or the failure reason).
1---
2name: deployment-pipelines-authoring-cli
3description: "Manages Fabric deployment pipelines for ALM promotion across dev, test, and prod stages, including stage creation, workspace assignment, selective forward or backward deploys, operation polling, stage role assignments, and the pipeline and workspace permissions each action requires. For Git sync use git-integration-operations-cli."
4metadata:
5 source: https://skillmd.com/skills/microsoft/deployment-pipelines-authoring-cli
6---
7
8> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry
9> `x-ms-fabric-skill: deployment-pipelines-authoring-cli` (`az rest`: `--headers "x-ms-fabric-skill=deployment-pipelines-authoring-cli"`),
10> including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.
11
12> **CRITICAL NOTES**
13> 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
14> 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering
15> 3. To find a deployment pipeline or stage ID: list deployment pipelines (then stages) and filter by `displayName` with JMESPath — never guess IDs.
16
17# Fabric Deployment Pipelines Authoring — CLI Skill
18
19Automates Fabric Application Lifecycle Management (ALM) with **deployment pipelines**: promote Fabric
20content between stages (typically Development → Test → Production) using the Fabric core control-plane
21REST API. This skill covers pipeline/stage lifecycle, workspace assignment, and stage-to-stage deployment
22(a long-running operation).
23
24## Prerequisite Knowledge
25
26Read these companion documents first — this skill assumes their patterns and does **not** repeat them:
27
28| Task | Reference | Notes |
29|---|---|---|
30| Finding Workspaces and Items in Fabric | [COMMON-CLI.md § Finding Workspaces and Items in Fabric](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) | **Mandatory** — resolve workspace/item IDs by name via list + JMESPath |
31| Authentication & Token Acquisition | [COMMON-CORE.md § Authentication & Token Acquisition](../../common/COMMON-CORE.md#authentication--token-acquisition) | Token audience must be `https://api.fabric.microsoft.com`; wrong audience = 401 |
32| Authentication Recipes | [COMMON-CLI.md § Authentication Recipes](../../common/COMMON-CLI.md#authentication-recipes) | `az login` flows and token acquisition |
33| Fabric Control-Plane API via `az rest` | [COMMON-CLI.md § Fabric Control-Plane API via az rest](../../common/COMMON-CLI.md#fabric-control-plane-api-via-az-rest) | **Always pass `--resource https://api.fabric.microsoft.com`** |
34| Core Control-Plane REST APIs | [COMMON-CORE.md § Core Control-Plane REST APIs](../../common/COMMON-CORE.md#core-control-plane-rest-apis) | Pagination, LRO polling, rate-limiting patterns |
35| Long-Running Operations (LRO) | [COMMON-CLI.md § Long-Running Operations (LRO) Pattern](../../common/COMMON-CLI.md#long-running-operations-lro-pattern) | **Deploy is an LRO** — poll `/v1/operations/{id}` until terminal |
36| Environment URLs | [COMMON-CORE.md § Environment URLs](../../common/COMMON-CORE.md#environment-urls) | Sovereign/gov clouds use different hosts |
37| Supported item types | [references/supported-item-types.md](references/supported-item-types.md) | Living list of item types a deploy can copy (per category, with preview flags) — reconcile from the **official Microsoft docs** (source of truth); don't guess |
38| Diff two item definitions (token-efficient) | [references/scripts/diff_item_definitions.py](references/scripts/diff_item_definitions.py) | Local tool that decodes both `getDefinition` payloads, normalizes auto-rebound fields, and prints **only the diffs** — feed the diff (not the full definitions) to the model. `python references/scripts/diff_item_definitions.py source.json target.json` (exit `0`=same, `1`=changed) |
39
40This skill adds: **how to drive the deployment-pipelines REST surface** from an agentic terminal.
41
42## Concepts
43
44- A **deployment pipeline** contains **2–10 ordered stages** (`order` starts at 0). Each stage may have at
45 most **one assigned workspace**, and a workspace can be assigned to at most one stage.
46- **Deployment** copies supported item content from a **source stage** to an **adjacent target stage**.
47 Forward deploys (dev→test→prod) work between any adjacent stages. **Backward** deploys (e.g. prod→test)
48 are currently supported **only when the target stage is empty** (no assigned workspace) — you cannot
49 backward-deploy over a stage that already has a workspace.
50- **Item pairing (autobinding).** During deployment Fabric records a **connection between a source item and
51 its clone** in the target stage; this pairing is how later deploys know which target item to overwrite,
52 and how related items (e.g. a report and its semantic model) stay bound. There is **no REST API to _set_
53 pairing** — it is maintained automatically — but you can **observe** the current pairing via the
54 `sourceItemId` / `targetItemId` fields returned by `List stage items`. See the *Fix a broken item pairing*
55 workflow below for the only supported repair.
56- Deploy is an **asynchronous long-running operation (LRO)**: the API returns `202 Accepted` with an
57 operation ID; you poll for completion.
58- **Deployment rules** and **parameter rules** (e.g. repoint a data source per stage) are configured in the
59 Fabric **portal UI** — there is **no REST API to create rules**. Do not claim otherwise.
60- Only **supported item types** are copied by a deploy; unsupported items are skipped (not an error). The
61 supported set changes over time — see [references/supported-item-types.md](references/supported-item-types.md).
62- There is **no "what changed" / compare REST API**. `List stage items` returns item **identity + pairing**
63 (`itemId`, `itemDisplayName`, `itemType`, `sourceItemId`, `targetItemId`, `lastDeploymentTime`) — but **no
64 change status**, and `lastDeploymentTime` is the last **deployment** time, **not** the last edit time, so
65 it is not a reliable change signal. To deploy only changed items you must **diff the two stages yourself**
66 and build the `items` list (see the *Deploy only changed items* workflow below). The portal's "Compare"
67 view is server-side and not exposed via API.
68
69## Must/Prefer/Avoid
70
71### MUST DO
72- Resolve pipeline, stage, and workspace **IDs by name** via list + JMESPath before any mutating call. Never fabricate GUIDs.
73- Target the correct base URL: `https://api.fabric.microsoft.com/v1/deploymentPipelines` and acquire a token for the `https://api.fabric.microsoft.com` audience.
74- Treat **Deploy Stage Content** as an LRO: on `202`, capture the operation ID and poll `/v1/operations/{operationId}` until the state is `Succeeded`/`Failed`, then surface the result.
75- When the **target stage has no assigned workspace**, include `createdWorkspaceDetails` (name, and `capacityId` when needed) in the deploy body, or the deploy fails.
76- Confirm destructive intent (delete pipeline, unassign workspace, backward deploy over prod) with the user before executing.
77- Verify the caller has the **required permissions** before a mutating call (see *Required permissions* below): pipeline **Admin** for every pipeline operation, plus the appropriate **workspace** role for assign/deploy. Surface a clear, actionable message on `401`/`403` rather than retrying blindly.
78
79### PREFER
80- Selective deploys via the `items` array (`{ sourceItemId, itemType }`) when the user names specific items; omit `items` to deploy **all** supported items.
81- A human-readable `note` on every deploy — but know it is **write-only**: the API accepts it and never
82 returns it (it appears only in the portal UI). For a programmatic audit trail, also record the deploy
83 externally (CI/CD logs or a Git commit message).
84- `List Deployment Pipeline Stage Items` to preview what will move before deploying.
85- Idempotent scripting: check whether a pipeline/stage/assignment already exists before creating it.
86
87### AVOID
88- Inventing a "create deployment rule" or "parameter rule" REST call — those are UI-only today.
89- Assigning a workspace during an **active deployment** (the assign call fails) or to a stage/workspace that is already paired.
90- Hardcoding `api.fabric.microsoft.com` in sovereign clouds — resolve the host from environment config.
91- Using a service principal without first confirming the Fabric admin enabled SP creation of deployment pipelines.
92- **Hashing raw `getDefinition` output to detect changes without normalizing.** Deployment **auto-rebinds**
93 embedded references in the target (pipeline `notebookId`/`workspaceId`, report→model id, Direct Lake
94 server/db), so a paired target's definition legitimately differs from the source even when nothing was
95 edited — naive hashing reports **false "changed"**. Strip/normalize those binding fields before comparing.
96- **Diffing by dumping every item definition into the agent's context.** A full two-stage content diff can be
97 dozens of `getDefinition` calls and >100 KB — do the compare in a script
98 ([references/scripts/diff_item_definitions.py](references/scripts/diff_item_definitions.py)) and surface only
99 the resulting change list, and for a changed item forward **only the emitted diff**, never the two full
100 definitions, to the model.
101- Unassigning a workspace to repair a broken pairing **without first warning the user** that unassign
102 **permanently deletes that stage's deployment history and its configured deployment/parameter rules** —
103 always ask whether the stage has rules before unassigning (see *Fix a broken item pairing*).
104
105## REST API Reference
106
107Base: `https://api.fabric.microsoft.com/v1`. Delegated scopes are **per operation** — provision a service
108principal with least privilege:
109
110| Operation | Required delegated scope |
111|---|---|
112| List / Get (pipelines, stages, stage items, operations) | `Pipeline.Read.All` **or** `Pipeline.ReadWrite.All` |
113| Create / Update / Delete pipeline, Update stage | `Pipeline.ReadWrite.All` |
114| Assign / Unassign workspace | `Pipeline.ReadWrite.All` **and** `Workspace.ReadWrite.All` |
115| **Deploy stage content** | **`Pipeline.Deploy`** |
116
117Deploy uses its own `Pipeline.Deploy` scope — an app scoped only to `Pipeline.ReadWrite.All` gets a **403**
118on `POST .../deploy`.
119
120| Operation | Method + Path |
121|---|---|
122| List pipelines | `GET /deploymentPipelines` |
123| Create pipeline | `POST /deploymentPipelines` |
124| Get / Update / Delete pipeline | `GET|PATCH|DELETE /deploymentPipelines/{id}` |
125| List / Get stages | `GET /deploymentPipelines/{id}/stages[/{stageId}]` |
126| Update stage | `PATCH /deploymentPipelines/{id}/stages/{stageId}` |
127| List stage items | `GET /deploymentPipelines/{id}/stages/{stageId}/items` |
128| Assign workspace to stage | `POST /deploymentPipelines/{id}/stages/{stageId}/assignWorkspace` |
129| Unassign workspace from stage | `POST /deploymentPipelines/{id}/stages/{stageId}/unassignWorkspace` |
130| **Deploy stage content (LRO)** | `POST /deploymentPipelines/{id}/deploy` |
131| List operations (≤20 recent) | `GET /deploymentPipelines/{id}/operations` |
132| Get operation (with execution plan) | `GET /deploymentPipelines/{id}/operations/{operationId}` |
133| Role assignments | `GET|POST|DELETE /deploymentPipelines/{id}/roleAssignments[/{principalId}]` |
134
135### Request-body shapes (guidance)
136
137- **Create**: `{ "displayName", "description"?, "stages": [ { "displayName", "description"?, "isPublic" } ] }` — 2–10 stages.
138- **Assign workspace**: `{ "workspaceId" }`.
139- **Deploy**: `{ "sourceStageId", "targetStageId", "items"?: [ { "sourceItemId", "itemType" } ], "note"?, "options"?: { "allowCrossRegionDeployment": false }, "createdWorkspaceDetails"?: { "name", "capacityId"? } }`.
140
141## Required permissions
142
143Deployment pipeline operations are governed by **two** independent permission systems: your role on the
144**pipeline** (its own `roleAssignments`) and your role on each **workspace** involved. You generally need
145**both**. Deployment pipelines require a Fabric capacity/subscription, and the pipeline creator becomes the
146pipeline **Admin**.
147
148| Operation | Pipeline role | Workspace role(s) |
149|---|---|---|
150| Create a pipeline | — (becomes **Admin** on create) | **Admin** of a Fabric workspace (feature access prerequisite) |
151| Get / list pipeline, stages, items, operations | **Admin** (shared access) | — |
152| Update / delete pipeline; manage `roleAssignments` | **Admin** | — |
153| **Assign / unassign** a workspace to a stage | **Admin** | **Admin** of the workspace being (un)assigned |
154| **Deploy** stage content | **Admin** | at least **Contributor/Member** on **both** the source and target stage workspaces (higher role if the target items require it) |
155| Deploy to an **empty** target stage (creates a workspace) | **Admin** | capacity-assignment permission to place the new workspace on a capacity; the deploying user becomes the **only Admin** of the newly created workspace and owner of cloned semantic models |
156
157Notes:
158- Sharing a pipeline grants the pipeline **Admin** role — there is no lower "viewer-only" pipeline write role for these operations.
159- A **service principal** can drive these APIs only if the Fabric admin enabled *service principals can create deployment pipelines* (and the SP holds the same pipeline + workspace roles above).
160- On `403`, distinguish *missing pipeline role* from *missing workspace role* in the message so the user knows which access to request.
161
162
163
164**Create a pipeline** → POST the display name + ordered stages; capture the returned stage IDs (they are
165what you deploy between).
166
167**Assign a workspace to a stage** → resolve stage ID and workspace ID by name, verify both are unassigned,
168then POST `assignWorkspace`. Requires admin on both the pipeline and the workspace.
169
170**Deploy content** → resolve source/target stage IDs, optionally preview stage items, POST `deploy` (all
171items or a selected `items` list) with a `note`, then poll the returned operation to completion and report
172which items moved.
173
174**Deploy only changed items** → there is no diff/compare API, so compute the delta yourself. `List stage
175items` gives identity + pairing only (no timestamps, no change status), so change detection means comparing
176**item definitions**:
1771. Resolve the source and target **stage** IDs and the workspace assigned to each.
1782. List items in **both** stages (`GET .../stages/{stageId}/items`) — each source row carries `sourceItemId`
179 (as `itemId`) and its paired `targetItemId` (absent = **new/unpaired**). Also list the target stage to find
180 **deleted** items (present in target, not paired from any source). Pair by `targetItemId`; fall back to
181 `(itemType, displayName)` only when no pipeline pairing exists (name-matching can't detect renames).
1823. **Filter out system-managed children** — a `SQLEndpoint` is auto-created per Lakehouse/Warehouse and should
183 not be diffed or deployed on its own; it follows its parent.
1844. Classify each paired item:
185 - **New** (no `targetItemId`) → deploy.
186 - **Changed** → detect via `POST .../items/{id}/getDefinition` on **both** stages, then diff. Run
187 [references/scripts/diff_item_definitions.py](references/scripts/diff_item_definitions.py) on the two
188 responses: it decodes each part, **normalizes** the auto-rebound fields (pipeline `notebookId`/
189 `workspaceId`, report model id, Direct Lake server/db) for you, and prints only the differing parts
190 (exit `1` = changed, `0` = identical) — so you don't hand-roll hashing or false-positive on unedited
191 items. Note the `getDefinition` contract differs by type:
192 `Notebook`/`SemanticModel`/`Report` are **LRO** (`202` → poll → `GET .../result`);
193 `DataPipeline` returns **`200` synchronously**.
194 - Types **without a usable `getDefinition` diff**: `Warehouse` has **no** item-definition API, and
195 `Lakehouse` / `Environment` *do* expose `getDefinition` but their definitions capture structure/metadata
196 only (not table data or most content edits) — so for all three, diff by **presence** and treat as changed
197 only when new or when the user indicates content changed.
198 - When you cannot prove equality, treat the item as **changed** (safe default).
1995. Do the comparison **in a script** (parallelize the independent `getDefinition` calls; they dominate
200 latency) and surface only the computed change list. To let the model reason about *what* changed in an
201 item, forward **only the emitted diff** (`diff_item_definitions.py` output), not the two full definitions —
202 a normalized diff is typically a few lines versus the >100 KB of raw payloads.
2036. Filter to **supported item types** (see references), show the user the change list, confirm, then POST a
204 **selective** `deploy` with the `{ sourceItemId, itemType }` array and a `note`, and poll to completion.
205
206> Deletions do **not** propagate via a selective `items` deploy — an item removed from the source stage is not
207> removed from the target by a selective deploy. Use a **full** deploy (omit `items`) to propagate deletions,
208> or delete the target item manually, and warn the user of this before promoting.
209
210**Fix a broken item pairing** → pairing (the source↔target connection Fabric maintains, a.k.a. autobinding)
211is **not settable via any REST API**. When two items that should be paired across stages are not — surfaced
212by a deploy that duplicates an item instead of overwriting it, an autobind/dependency failure, or the user
213reporting it — the **only supported repair is to unassign the affected stage's workspace and re-assign it**,
214which forces Fabric to rebuild the pairing on the next deploy. This is destructive:
2151. **Warn the user first.** Unassigning a workspace **permanently deletes that stage's deployment history and
216 all its configured deployment/parameter rules** — they cannot be recovered by re-assigning.
2172. **Ask whether the stage has rules.** Because rules are UI-only (no REST API to read or recreate them),
218 explicitly ask the user whether the stage has deployment/parameter rules configured **before** unassigning.
219 If it does, have them record the rules (or recreate them in the portal afterward) and get explicit
220 confirmation to proceed.
2213. Only after confirmation, `POST .../stages/{stageId}/unassignWorkspace`, then
222 `POST .../stages/{stageId}/assignWorkspace` with the same `workspaceId`, and re-run the deploy so the
223 pairing is re-established.
224
225**Track / audit** → `List operations` for recent history; `Get operation` to inspect the execution plan and
226per-item status of a specific deployment.
227
228### Deploy operational caveats & common errors
229
230- **One deploy per pipeline at a time.** A pipeline runs a single operation at a time; starting another while
231 one is in flight fails with **`WorkspaceMigrationOperationInProgress` (HTTP 400)**. Always poll the current
232 operation to a terminal state before starting the next stage promotion (this is also why the *assign*
233 workspace call fails during an active deployment).
234- **First deploy after assigning a workspace can fail with `Alm_InvalidRequest_WorkloadUnavailable`.** Newly
235 assigned workspaces need **~60–120 s** for workload services (Lakehouse, Notebook, etc.) to initialize.
236 Mitigate by waiting before the first deploy, or deploy Power BI items (`SemanticModel`, `Report`) first and
237 Fabric-native items (`Lakehouse`, `Notebook`) after a short delay; retry on this error. Subsequent deploys
238 are reliable once workloads are warm.
239- **The operation ID is returned in the `x-ms-operation-id` response header** (alongside `Location`), not the
240 `202` body. `az rest` does not surface response headers cleanly — for reliable header capture in automation,
241 issue the deploy with `curl -i` (or Python `requests`) and parse the header, then poll
242 `/v1/operations/{operationId}` with `az rest`.
243- **Deploy copies definitions, not data.** Only item metadata/definitions are promoted; table data, query
244 results, and caches are not. Trigger refreshes/loads in the target stage after a deploy.
245- **Maximum 300 items per deploy request.** A selective (or full) deploy is capped at **300 deployed items**;
246 batch larger promotions across multiple deploy calls.
247
248## Examples
249
250### Create a three-stage pipeline
251Deployment-pipeline `displayName` is **unique tenant-wide** — a create for a name
252already in use fails with `Alm_InvalidRequest_DuplicateAlmPipelineName` (HTTP 400,
253"pipeline name ... is already in use"). To make a create re-runnable, drop any
254existing pipeline of that name first, then create. Write the JSON body to a file
255and pass it with `--body @file.json` — an inline multi-line `--body '{...}'` is
256mangled into an empty body on Windows/PowerShell (`az` is `az.cmd`), which the API
257rejects with `InvalidInput: Unexpected end when reading JSON`.
258```bash
259# Idempotent: delete an existing "Sales Analytics ALM" if present, then create.
260EXISTING=$(az rest --method GET --resource https://api.fabric.microsoft.com \
261 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines" \
262 --query "value[?displayName=='Sales Analytics ALM'].id | [0]" --output tsv)
263if [ -n "$EXISTING" ]; then
264 az rest --method DELETE --resource https://api.fabric.microsoft.com \
265 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$EXISTING"
266fi
267
268cat > /tmp/create-pipeline.json << 'EOF'
269{
270 "displayName": "Sales Analytics ALM",
271 "description": "Dev/Test/Prod promotion for Sales Analytics",
272 "stages": [
273 { "displayName": "Development", "isPublic": false },
274 { "displayName": "Test", "isPublic": false },
275 { "displayName": "Production", "isPublic": true }
276 ]
277}
278EOF
279az rest --method POST \
280 --resource https://api.fabric.microsoft.com \
281 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines" \
282 --headers "Content-Type=application/json" \
283 --body @/tmp/create-pipeline.json
284```
285
286### Assign a workspace to the Development stage
287```bash
288# $PIPELINE_ID and $DEV_STAGE_ID resolved via list + JMESPath; $WS_ID resolved from workspace name.
289az rest --method POST \
290 --resource https://api.fabric.microsoft.com \
291 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/stages/$DEV_STAGE_ID/assignWorkspace" \
292 --headers "Content-Type=application/json" \
293 --body "{ \"workspaceId\": \"$WS_ID\" }"
294```
295
296### Deploy all items dev → test and wait for the LRO
297```bash
298# Kick off the deployment (returns 202 + an operation id header).
299az rest --method POST \
300 --resource https://api.fabric.microsoft.com \
301 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
302 --headers "Content-Type=application/json" \
303 --body "{ \"sourceStageId\": \"$DEV_STAGE_ID\", \"targetStageId\": \"$TEST_STAGE_ID\", \"note\": \"Promote validated dev build\" }" \
304 --verbose
305# Then poll /v1/operations/{operationId} until state is Succeeded or Failed
306# (see COMMON-CLI § Long-Running Operations pattern).
307```
308
309### Deploy only selected items
310```bash
311az rest --method POST \
312 --resource https://api.fabric.microsoft.com \
313 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
314 --headers "Content-Type=application/json" \
315 --body '{
316 "sourceStageId": "'"$TEST_STAGE_ID"'",
317 "targetStageId": "'"$PROD_STAGE_ID"'",
318 "items": [
319 { "sourceItemId": "'"$MODEL_ID"'", "itemType": "SemanticModel" },
320 { "sourceItemId": "'"$REPORT_ID"'", "itemType": "Report" }
321 ],
322 "note": "Promote reviewed model + report to production"
323 }'
324```
325
326### Deploy only the items that changed (compute the diff first)
327```bash
328# 1. List paired items for BOTH stages. Each source row carries itemId (= sourceItemId)
329# and its paired targetItemId (absent = new/unpaired). There is NO timestamp or
330# change-status field, so "changed" must be detected from item definitions.
331az rest --method GET --resource https://api.fabric.microsoft.com \
332 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/stages/$SOURCE_STAGE_ID/items" \
333 > source-items.json
334
335# 2. NEW items = unpaired (no targetItemId). Exclude system-managed SQLEndpoint children.
336NEW=$(jq '[.value[]
337 | select(.itemType != "SQLEndpoint")
338 | select(has("targetItemId") | not)
339 | { sourceItemId: .itemId, itemType: .itemType }]' source-items.json)
340
341# 3. CHANGED items (paired): fetch getDefinition from BOTH stages, then diff with
342# references/scripts/diff_item_definitions.py. It decodes each part, NORMALIZES the
343# auto-rebound fields (notebookId/workspaceId in pipelines, model id in reports,
344# server/db in Direct Lake models) and prints ONLY the differing parts. Notebook/
345# SemanticModel/Report are LRO (202 -> poll -> /result); DataPipeline returns 200 sync.
346# Parallelize the independent getDefinition calls. Per paired definition-backed item:
347# getDefinition SOURCE_WS id > src.json
348# getDefinition TARGET_WS targetItemId > tgt.json
349# python references/scripts/diff_item_definitions.py src.json tgt.json > diff.json
350# # exit 1 = changed -> add { sourceItemId, itemType } to $ITEMS; exit 0 = unchanged.
351# # Forward diff.json (NOT src.json/tgt.json) to the model to explain the change.
352# Merge NEW + CHANGED into $ITEMS. When equality can't be proven, include the item.
353
354# 4. Selective deploy of just the changed set.
355az rest --method POST --resource https://api.fabric.microsoft.com \
356 --url "https://api.fabric.microsoft.com/v1/deploymentPipelines/$PIPELINE_ID/deploy" \
357 --headers "Content-Type=application/json" \
358 --body "$(jq -n --arg s "$SOURCE_STAGE_ID" --arg t "$TARGET_STAGE_ID" --argjson items "$ITEMS" \
359 '{ sourceStageId: $s, targetStageId: $t, items: $items, note: "Deploy only changed items" }')"
360# Then poll /v1/operations/{operationId} until terminal.
361# NOTE: a selective deploy does NOT propagate deletions — use a full deploy (omit items) for those.
362```
363
364### Prompt/response
365
366**User:** "Promote my Sales dev workspace to the Test stage and tell me when it's done."
367
368**Assistant (behavior):**
3691. Lists deployment pipelines → filters to the one whose Development stage holds the Sales dev workspace; captures `sourceStageId` (Development) and `targetStageId` (Test).
3702. Confirms the Test stage has an assigned workspace (or asks for a name + capacity to create one).
3713. POSTs `deploy` with a `note`, receives `202`, extracts the operation ID.
3724. Polls `/v1/operations/{operationId}` until terminal, then reports success and the list of deployed items (or the failure reason).