---

name: deployment-pipelines-authoring-cli description: "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."

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

1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
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
3. 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:

| Task | Reference | Notes | |---|---|---| | Finding Workspaces and Items in Fabric | COMMON-CLI.md § Finding Workspaces and Items in Fabric | Mandatory — resolve workspace/item IDs by name via list + JMESPath | | Authentication & Token Acquisition | COMMON-CORE.md § Authentication & Token Acquisition | Token audience must be https://api.fabric.microsoft.com; wrong audience = 401 | | Authentication Recipes | COMMON-CLI.md § Authentication Recipes | az login flows and token acquisition | | Fabric Control-Plane API via az rest | COMMON-CLI.md § Fabric Control-Plane API via az rest | Always pass --resource https://api.fabric.microsoft.com | | Core Control-Plane REST APIs | COMMON-CORE.md § Core Control-Plane REST APIs | Pagination, LRO polling, rate-limiting patterns | | Long-Running Operations (LRO) | COMMON-CLI.md § Long-Running Operations (LRO) Pattern | Deploy is an LRO — poll /v1/operations/{id} until terminal | | Environment URLs | COMMON-CORE.md § Environment URLs | Sovereign/gov clouds use different hosts | | Supported item types | 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 | | Diff two item definitions (token-efficient) | 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) |

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|PATCH|DELETE /deploymentPipelines/{id} | | 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|POST|DELETE /deploymentPipelines/{id}/roleAssignments[/{principalId}] |

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