deployment-pipelines-authoring-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 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](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/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**: 1. Resolve the source and target **stage** IDs and the workspace assigned to each. 2. 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). 3. **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. 4. 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](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). 5. 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