/deployment-pipelines-authoring-cli

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](../../common/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](../../common/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](../../common/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](../../common/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](../../common/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](../../common/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](../../common/COMMON-CORE.md#environment-urls) | Sovereign/gov clouds use different hosts | | 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 | | 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) |

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](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 t