[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699NQQ98F6KHCE25BD5P6M5":3,"skill-same:01M699NQQ98F6KHCE25BD5P6M5":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":23,"linkOnly":24,"markdownContent":25,"markdownBody":26,"frontMatter":27,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":31,"repositoryHtmlUrl":32,"repositoryHomepageUrl":6,"ownerHtmlUrl":33,"ownerBlogUrl":34,"ownerDescription":35,"updatedAt":36,"install":37,"resources":50},"01M699NQQ98F6KHCE25BD5P6M5","deployment-pipelines-authoring-cli",null,"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.","microsoft\u002Fskills-for-fabric","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699NAPJKS2WBHHDN86Q5MM6",1353,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fplugins\u002Ffabric-skills\u002Fskills\u002Fdeployment-pipelines-authoring-cli\u002FSKILL.md",[],[19,20,21,22],"deployment pipelines authoring cli","cli","test","sync","2026-11-10 10:12:30",false,"---\nname: deployment-pipelines-authoring-cli\ndescription: \"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.\"\n---\n\n> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry\n> `x-ms-fabric-skill: deployment-pipelines-authoring-cli` (`az rest`: `--headers \"x-ms-fabric-skill=deployment-pipelines-authoring-cli\"`),\n> including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.\n\n> **CRITICAL NOTES**\n> 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering\n> 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\n> 3. To find a deployment pipeline or stage ID: list deployment pipelines (then stages) and filter by `displayName` with JMESPath — never guess IDs.\n\n# Fabric Deployment Pipelines Authoring — CLI Skill\n\nAutomates Fabric Application Lifecycle Management (ALM) with **deployment pipelines**: promote Fabric\ncontent between stages (typically Development → Test → Production) using the Fabric core control-plane\nREST API. This skill covers pipeline\u002Fstage lifecycle, workspace assignment, and stage-to-stage deployment\n(a long-running operation).\n\n## Prerequisite Knowledge\n\nRead these companion documents first — this skill assumes their patterns and does **not** repeat them:\n\n| Task | Reference | Notes |\n|---|---|---|\n| Finding Workspaces and Items in Fabric | [COMMON-CLI.md § Finding Workspaces and Items in Fabric](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#finding-workspaces-and-items-in-fabric) | **Mandatory** — resolve workspace\u002Fitem IDs by name via list + JMESPath |\n| Authentication & Token Acquisition | [COMMON-CORE.md § Authentication & Token Acquisition](..\u002F..\u002Fcommon\u002FCOMMON-CORE.md#authentication--token-acquisition) | Token audience must be `https:\u002F\u002Fapi.fabric.microsoft.com`; wrong audience = 401 |\n| Authentication Recipes | [COMMON-CLI.md § Authentication Recipes](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#authentication-recipes) | `az login` flows and token acquisition |\n| Fabric Control-Plane API via `az rest` | [COMMON-CLI.md § Fabric Control-Plane API via az rest](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#fabric-control-plane-api-via-az-rest) | **Always pass `--resource https:\u002F\u002Fapi.fabric.microsoft.com`** |\n| Core Control-Plane REST APIs | [COMMON-CORE.md § Core Control-Plane REST APIs](..\u002F..\u002Fcommon\u002FCOMMON-CORE.md#core-control-plane-rest-apis) | Pagination, LRO polling, rate-limiting patterns |\n| Long-Running Operations (LRO) | [COMMON-CLI.md § Long-Running Operations (LRO) Pattern](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#long-running-operations-lro-pattern) | **Deploy is an LRO** — poll `\u002Fv1\u002Foperations\u002F{id}` until terminal |\n| Environment URLs | [COMMON-CORE.md § Environment URLs](..\u002F..\u002Fcommon\u002FCOMMON-CORE.md#environment-urls) | Sovereign\u002Fgov clouds use different hosts |\n| Supported item types | [references\u002Fsupported-item-types.md](references\u002Fsupported-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 |\n| Diff two item definitions (token-efficient) | [references\u002Fscripts\u002Fdiff_item_definitions.py](references\u002Fscripts\u002Fdiff_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\u002Fscripts\u002Fdiff_item_definitions.py source.json target.json` (exit `0`=same, `1`=changed) |\n\nThis skill adds: **how to drive the deployment-pipelines REST surface** from an agentic terminal.\n\n## Concepts\n\n- A **deployment pipeline** contains **2–10 ordered stages** (`order` starts at 0). Each stage may have at\n  most **one assigned workspace**, and a workspace can be assigned to at most one stage.\n- **Deployment** copies supported item content from a **source stage** to an **adjacent target stage**.\n  Forward deploys (dev→test→prod) work between any adjacent stages. **Backward** deploys (e.g. prod→test)\n  are currently supported **only when the target stage is empty** (no assigned workspace) — you cannot\n  backward-deploy over a stage that already has a workspace.\n- **Item pairing (autobinding).** During deployment Fabric records a **connection between a source item and\n  its clone** in the target stage; this pairing is how later deploys know which target item to overwrite,\n  and how related items (e.g. a report and its semantic model) stay bound. There is **no REST API to _set_\n  pairing** — it is maintained automatically — but you can **observe** the current pairing via the\n  `sourceItemId` \u002F `targetItemId` fields returned by `List stage items`. See the *Fix a broken item pairing*\n  workflow below for the only supported repair.\n- Deploy is an **asynchronous long-running operation (LRO)**: the API returns `202 Accepted` with an\n  operation ID; you poll for completion.\n- **Deployment rules** and **parameter rules** (e.g. repoint a data source per stage) are configured in the\n  Fabric **portal UI** — there is **no REST API to create rules**. Do not claim otherwise.\n- Only **supported item types** are copied by a deploy; unsupported items are skipped (not an error). The\n  supported set changes over time — see [references\u002Fsupported-item-types.md](references\u002Fsupported-item-types.md).\n- There is **no \"what changed\" \u002F compare REST API**. `List stage items` returns item **identity + pairing**\n  (`itemId`, `itemDisplayName`, `itemType`, `sourceItemId`, `targetItemId`, `lastDeploymentTime`) — but **no\n  change status**, and `lastDeploymentTime` is the last **deployment** time, **not** the last edit time, so\n  it is not a reliable change signal. To deploy only changed items you must **diff the two stages yourself**\n  and build the `items` list (see the *Deploy only changed items* workflow below). The portal's \"Compare\"\n  view is server-side and not exposed via API.\n\n## Must\u002FPrefer\u002FAvoid\n\n### MUST DO\n- Resolve pipeline, stage, and workspace **IDs by name** via list + JMESPath before any mutating call. Never fabricate GUIDs.\n- Target the correct base URL: `https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines` and acquire a token for the `https:\u002F\u002Fapi.fabric.microsoft.com` audience.\n- Treat **Deploy Stage Content** as an LRO: on `202`, capture the operation ID and poll `\u002Fv1\u002Foperations\u002F{operationId}` until the state is `Succeeded`\u002F`Failed`, then surface the result.\n- When the **target stage has no assigned workspace**, include `createdWorkspaceDetails` (name, and `capacityId` when needed) in the deploy body, or the deploy fails.\n- Confirm destructive intent (delete pipeline, unassign workspace, backward deploy over prod) with the user before executing.\n- 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\u002Fdeploy. Surface a clear, actionable message on `401`\u002F`403` rather than retrying blindly.\n\n### PREFER\n- Selective deploys via the `items` array (`{ sourceItemId, itemType }`) when the user names specific items; omit `items` to deploy **all** supported items.\n- A human-readable `note` on every deploy — but know it is **write-only**: the API accepts it and never\n  returns it (it appears only in the portal UI). For a programmatic audit trail, also record the deploy\n  externally (CI\u002FCD logs or a Git commit message).\n- `List Deployment Pipeline Stage Items` to preview what will move before deploying.\n- Idempotent scripting: check whether a pipeline\u002Fstage\u002Fassignment already exists before creating it.\n\n### AVOID\n- Inventing a \"create deployment rule\" or \"parameter rule\" REST call — those are UI-only today.\n- Assigning a workspace during an **active deployment** (the assign call fails) or to a stage\u002Fworkspace that is already paired.\n- Hardcoding `api.fabric.microsoft.com` in sovereign clouds — resolve the host from environment config.\n- Using a service principal without first confirming the Fabric admin enabled SP creation of deployment pipelines.\n- **Hashing raw `getDefinition` output to detect changes without normalizing.** Deployment **auto-rebinds**\n  embedded references in the target (pipeline `notebookId`\u002F`workspaceId`, report→model id, Direct Lake\n  server\u002Fdb), so a paired target's definition legitimately differs from the source even when nothing was\n  edited — naive hashing reports **false \"changed\"**. Strip\u002Fnormalize those binding fields before comparing.\n- **Diffing by dumping every item definition into the agent's context.** A full two-stage content diff can be\n  dozens of `getDefinition` calls and >100 KB — do the compare in a script\n  ([references\u002Fscripts\u002Fdiff_item_definitions.py](references\u002Fscripts\u002Fdiff_item_definitions.py)) and surface only\n  the resulting change list, and for a changed item forward **only the emitted diff**, never the two full\n  definitions, to the model.\n- Unassigning a workspace to repair a broken pairing **without first warning the user** that unassign\n  **permanently deletes that stage's deployment history and its configured deployment\u002Fparameter rules** —\n  always ask whether the stage has rules before unassigning (see *Fix a broken item pairing*).\n\n## REST API Reference\n\nBase: `https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1`. Delegated scopes are **per operation** — provision a service\nprincipal with least privilege:\n\n| Operation | Required delegated scope |\n|---|---|\n| List \u002F Get (pipelines, stages, stage items, operations) | `Pipeline.Read.All` **or** `Pipeline.ReadWrite.All` |\n| Create \u002F Update \u002F Delete pipeline, Update stage | `Pipeline.ReadWrite.All` |\n| Assign \u002F Unassign workspace | `Pipeline.ReadWrite.All` **and** `Workspace.ReadWrite.All` |\n| **Deploy stage content** | **`Pipeline.Deploy`** |\n\nDeploy uses its own `Pipeline.Deploy` scope — an app scoped only to `Pipeline.ReadWrite.All` gets a **403**\non `POST ...\u002Fdeploy`.\n\n| Operation | Method + Path |\n|---|---|\n| List pipelines | `GET \u002FdeploymentPipelines` |\n| Create pipeline | `POST \u002FdeploymentPipelines` |\n| Get \u002F Update \u002F Delete pipeline | `GET|PATCH|DELETE \u002FdeploymentPipelines\u002F{id}` |\n| List \u002F Get stages | `GET \u002FdeploymentPipelines\u002F{id}\u002Fstages[\u002F{stageId}]` |\n| Update stage | `PATCH \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}` |\n| List stage items | `GET \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}\u002Fitems` |\n| Assign workspace to stage | `POST \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}\u002FassignWorkspace` |\n| Unassign workspace from stage | `POST \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}\u002FunassignWorkspace` |\n| **Deploy stage content (LRO)** | `POST \u002FdeploymentPipelines\u002F{id}\u002Fdeploy` |\n| List operations (≤20 recent) | `GET \u002FdeploymentPipelines\u002F{id}\u002Foperations` |\n| Get operation (with execution plan) | `GET \u002FdeploymentPipelines\u002F{id}\u002Foperations\u002F{operationId}` |\n| Role assignments | `GET|POST|DELETE \u002FdeploymentPipelines\u002F{id}\u002FroleAssignments[\u002F{principalId}]` |\n\n### Request-body shapes (guidance)\n\n- **Create**: `{ \"displayName\", \"description\"?, \"stages\": [ { \"displayName\", \"description\"?, \"isPublic\" } ] }` — 2–10 stages.\n- **Assign workspace**: `{ \"workspaceId\" }`.\n- **Deploy**: `{ \"sourceStageId\", \"targetStageId\", \"items\"?: [ { \"sourceItemId\", \"itemType\" } ], \"note\"?, \"options\"?: { \"allowCrossRegionDeployment\": false }, \"createdWorkspaceDetails\"?: { \"name\", \"capacityId\"? } }`.\n\n## Required permissions\n\nDeployment pipeline operations are governed by **two** independent permission systems: your role on the\n**pipeline** (its own `roleAssignments`) and your role on each **workspace** involved. You generally need\n**both**. Deployment pipelines require a Fabric capacity\u002Fsubscription, and the pipeline creator becomes the\npipeline **Admin**.\n\n| Operation | Pipeline role | Workspace role(s) |\n|---|---|---|\n| Create a pipeline | — (becomes **Admin** on create) | **Admin** of a Fabric workspace (feature access prerequisite) |\n| Get \u002F list pipeline, stages, items, operations | **Admin** (shared access) | — |\n| Update \u002F delete pipeline; manage `roleAssignments` | **Admin** | — |\n| **Assign \u002F unassign** a workspace to a stage | **Admin** | **Admin** of the workspace being (un)assigned |\n| **Deploy** stage content | **Admin** | at least **Contributor\u002FMember** on **both** the source and target stage workspaces (higher role if the target items require it) |\n| 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 |\n\nNotes:\n- Sharing a pipeline grants the pipeline **Admin** role — there is no lower \"viewer-only\" pipeline write role for these operations.\n- 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).\n- On `403`, distinguish *missing pipeline role* from *missing workspace role* in the message so the user knows which access to request.\n\n\n\n**Create a pipeline** → POST the display name + ordered stages; capture the returned stage IDs (they are\nwhat you deploy between).\n\n**Assign a workspace to a stage** → resolve stage ID and workspace ID by name, verify both are unassigned,\nthen POST `assignWorkspace`. Requires admin on both the pipeline and the workspace.\n\n**Deploy content** → resolve source\u002Ftarget stage IDs, optionally preview stage items, POST `deploy` (all\nitems or a selected `items` list) with a `note`, then poll the returned operation to completion and report\nwhich items moved.\n\n**Deploy only changed items** → there is no diff\u002Fcompare API, so compute the delta yourself. `List stage\nitems` gives identity + pairing only (no timestamps, no change status), so change detection means comparing\n**item definitions**:\n1. Resolve the source and target **stage** IDs and the workspace assigned to each.\n2. List items in **both** stages (`GET ...\u002Fstages\u002F{stageId}\u002Fitems`) — each source row carries `sourceItemId`\n   (as `itemId`) and its paired `targetItemId` (absent = **new\u002Funpaired**). Also list the target stage to find\n   **deleted** items (present in target, not paired from any source). Pair by `targetItemId`; fall back to\n   `(itemType, displayName)` only when no pipeline pairing exists (name-matching can't detect renames).\n3. **Filter out system-managed children** — a `SQLEndpoint` is auto-created per Lakehouse\u002FWarehouse and should\n   not be diffed or deployed on its own; it follows its parent.\n4. Classify each paired item:\n   - **New** (no `targetItemId`) → deploy.\n   - **Changed** → detect via `POST ...\u002Fitems\u002F{id}\u002FgetDefinition` on **both** stages, then diff. Run\n     [references\u002Fscripts\u002Fdiff_item_definitions.py](references\u002Fscripts\u002Fdiff_item_definitions.py) on the two\n     responses: it decodes each part, **normalizes** the auto-rebound fields (pipeline `notebookId`\u002F\n     `workspaceId`, report model id, Direct Lake server\u002Fdb) for you, and prints only the differing parts\n     (exit `1` = changed, `0` = identical) — so you don't hand-roll hashing or false-positive on unedited\n     items. Note the `getDefinition` contract differs by type:\n     `Notebook`\u002F`SemanticModel`\u002F`Report` are **LRO** (`202` → poll → `GET ...\u002Fresult`);\n     `DataPipeline` returns **`200` synchronously**.\n   - **Warehouse** does have a definition API:\n     [Get Warehouse Definition](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Frest\u002Fapi\u002Ffabric\u002Fwarehouse\u002Fitems\u002Fget-warehouse-definition)\n     is `POST ...\u002Fworkspaces\u002F{workspaceId}\u002Fwarehouses\u002F{warehouseId}\u002FgetDefinition`, with `format=sqlproj`\n     (default) or `format=dacpac`. Accept `200`; for `202`, follow the documented LRO to its result,\n     carrying the skill telemetry header on every request. The API requires Warehouse read\u002Fwrite\n     permissions even though it retrieves a definition. Compare SQL-project\u002Fschema content with\n     appropriate tooling; the generic JSON diff helper is **not** a schema-aware binary DACPAC comparer.\n     Definitions do not include table data. If schema equality is unproven, report that limitation\n     rather than claiming the API does not exist or declaring the item unchanged.\n   - `Lakehouse` \u002F `Environment` expose `getDefinition` but capture structure\u002Fmetadata only\n     (not table data or most content edits); diff by **presence**, flag user-reported content changes,\n     and state the limits of any equality claim.\n   - When you cannot prove equality, treat the item as **changed** (safe default).\n5. Do the comparison **in a script** (parallelize the independent `getDefinition` calls; they dominate\n   latency) and surface only the computed change list. To let the model reason about *what* changed in an\n   item, forward **only the emitted diff** (`diff_item_definitions.py` output), not the two full definitions —\n   a normalized diff is typically a few lines versus the >100 KB of raw payloads.\n6. Filter to **supported item types** (see references), show the user the change list, confirm, then POST a\n   **selective** `deploy` with the `{ sourceItemId, itemType }` array and a `note`, and poll to completion.\n\n> Deletions do **not** propagate via a selective `items` deploy — an item removed from the source stage is not\n> removed from the target by a selective deploy. Use a **full** deploy (omit `items`) to propagate deletions,\n> or delete the target item manually, and warn the user of this before promoting.\n\n**Fix a broken item pairing** → pairing (the source↔target connection Fabric maintains, a.k.a. autobinding)\nis **not settable via any REST API**. When two items that should be paired across stages are not — surfaced\nby a deploy that duplicates an item instead of overwriting it, an autobind\u002Fdependency failure, or the user\nreporting it — the **only supported repair is to unassign the affected stage's workspace and re-assign it**,\nwhich forces Fabric to rebuild the pairing on the next deploy. This is destructive:\n1. **Warn the user first.** Unassigning a workspace **permanently deletes that stage's deployment history and\n   all its configured deployment\u002Fparameter rules** — they cannot be recovered by re-assigning.\n2. **Ask whether the stage has rules.** Because rules are UI-only (no REST API to read or recreate them),\n   explicitly ask the user whether the stage has deployment\u002Fparameter rules configured **before** unassigning.\n   If it does, have them record the rules (or recreate them in the portal afterward) and get explicit\n   confirmation to proceed.\n3. Only after confirmation, `POST ...\u002Fstages\u002F{stageId}\u002FunassignWorkspace`, then\n   `POST ...\u002Fstages\u002F{stageId}\u002FassignWorkspace` with the same `workspaceId`, and re-run the deploy so the\n   pairing is re-established.\n\n**Track \u002F audit** → `List operations` for recent history; `Get operation` to inspect the execution plan and\nper-item status of a specific deployment.\n\n### Deploy operational caveats & common errors\n\n- **One deploy per pipeline at a time.** A pipeline runs a single operation at a time; starting another while\n  one is in flight fails with **`WorkspaceMigrationOperationInProgress` (HTTP 400)**. Always poll the current\n  operation to a terminal state before starting the next stage promotion (this is also why the *assign*\n  workspace call fails during an active deployment).\n- **First deploy after assigning a workspace can fail with `Alm_InvalidRequest_WorkloadUnavailable`.** Newly\n  assigned workspaces need **~60–120 s** for workload services (Lakehouse, Notebook, etc.) to initialize.\n  Mitigate by waiting before the first deploy, or deploy Power BI items (`SemanticModel`, `Report`) first and\n  Fabric-native items (`Lakehouse`, `Notebook`) after a short delay; retry on this error. Subsequent deploys\n  are reliable once workloads are warm.\n- **The operation ID is returned in the `x-ms-operation-id` response header** (alongside `Location`), not the\n  `202` body. `az rest` does not surface response headers cleanly — for reliable header capture in automation,\n  issue the deploy with `curl -i` (or Python `requests`) and parse the header, then poll\n  `\u002Fv1\u002Foperations\u002F{operationId}` with `az rest`.\n- **Deploy copies definitions, not data.** Only item metadata\u002Fdefinitions are promoted; table data, query\n  results, and caches are not. Trigger refreshes\u002Floads in the target stage after a deploy.\n- **Maximum 300 items per deploy request.** A selective (or full) deploy is capped at **300 deployed items**;\n  batch larger promotions across multiple deploy calls.\n\n## Examples\n\n### Create a three-stage pipeline\nDeployment-pipeline `displayName` is **unique tenant-wide** — a create for a name\nalready in use fails with `Alm_InvalidRequest_DuplicateAlmPipelineName` (HTTP 400,\n\"pipeline name ... is already in use\"). To make a create re-runnable, drop any\nexisting pipeline of that name first, then create. Write the JSON body to a file\nand pass it with `--body @file.json` — an inline multi-line `--body '{...}'` is\nmangled into an empty body on Windows\u002FPowerShell (`az` is `az.cmd`), which the API\nrejects with `InvalidInput: Unexpected end when reading JSON`.\n```bash\n# Idempotent: delete an existing \"Sales Analytics ALM\" if present, then create.\nEXISTING=$(az rest --method GET --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\" \\\n  --query \"value[?displayName=='Sales Analytics ALM'].id | [0]\" --output tsv)\nif [ -n \"$EXISTING\" ]; then\n  az rest --method DELETE --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n    --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$EXISTING\"\nfi\n\ncat > \u002Ftmp\u002Fcreate-pipeline.json \u003C\u003C 'EOF'\n{\n  \"displayName\": \"Sales Analytics ALM\",\n  \"description\": \"Dev\u002FTest\u002FProd promotion for Sales Analytics\",\n  \"stages\": [\n    { \"displayName\": \"Development\", \"isPublic\": false },\n    { \"displayName\": \"Test\",        \"isPublic\": false },\n    { \"displayName\": \"Production\",  \"isPublic\": true }\n  ]\n}\nEOF\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body @\u002Ftmp\u002Fcreate-pipeline.json\n```\n\n### Assign a workspace to the Development stage\n```bash\n# $PIPELINE_ID and $DEV_STAGE_ID resolved via list + JMESPath; $WS_ID resolved from workspace name.\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fstages\u002F$DEV_STAGE_ID\u002FassignWorkspace\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body \"{ \\\"workspaceId\\\": \\\"$WS_ID\\\" }\"\n```\n\n### Deploy all items dev → test and wait for the LRO\n```bash\n# Kick off the deployment (returns 202 + an operation id header).\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fdeploy\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body \"{ \\\"sourceStageId\\\": \\\"$DEV_STAGE_ID\\\", \\\"targetStageId\\\": \\\"$TEST_STAGE_ID\\\", \\\"note\\\": \\\"Promote validated dev build\\\" }\" \\\n  --verbose\n# Then poll \u002Fv1\u002Foperations\u002F{operationId} until state is Succeeded or Failed\n# (see COMMON-CLI § Long-Running Operations pattern).\n```\n\n### Deploy only selected items\n```bash\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fdeploy\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body '{\n    \"sourceStageId\": \"'\"$TEST_STAGE_ID\"'\",\n    \"targetStageId\": \"'\"$PROD_STAGE_ID\"'\",\n    \"items\": [\n      { \"sourceItemId\": \"'\"$MODEL_ID\"'\", \"itemType\": \"SemanticModel\" },\n      { \"sourceItemId\": \"'\"$REPORT_ID\"'\", \"itemType\": \"Report\" }\n    ],\n    \"note\": \"Promote reviewed model + report to production\"\n  }'\n```\n\n### Deploy only the items that changed (compute the diff first)\n```bash\n# 1. List paired items for BOTH stages. Each source row carries itemId (= sourceItemId)\n#    and its paired targetItemId (absent = new\u002Funpaired). There is NO timestamp or\n#    change-status field, so \"changed\" must be detected from item definitions.\naz rest --method GET --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fstages\u002F$SOURCE_STAGE_ID\u002Fitems\" \\\n  > source-items.json\n\n# 2. NEW items = unpaired (no targetItemId). Exclude system-managed SQLEndpoint children.\nNEW=$(jq '[.value[]\n  | select(.itemType != \"SQLEndpoint\")\n  | select(has(\"targetItemId\") | not)\n  | { sourceItemId: .itemId, itemType: .itemType }]' source-items.json)\n\n# 3. CHANGED items (paired): fetch getDefinition from BOTH stages, then diff with\n#    references\u002Fscripts\u002Fdiff_item_definitions.py. It decodes each part, NORMALIZES the\n#    auto-rebound fields (notebookId\u002FworkspaceId in pipelines, model id in reports,\n#    server\u002Fdb in Direct Lake models) and prints ONLY the differing parts. Notebook\u002F\n#    SemanticModel\u002FReport are LRO (202 -> poll -> \u002Fresult); DataPipeline returns 200 sync.\n#    Parallelize the independent getDefinition calls. Per paired definition-backed item:\n#      getDefinition SOURCE_WS id            > src.json\n#      getDefinition TARGET_WS targetItemId  > tgt.json\n#      python references\u002Fscripts\u002Fdiff_item_definitions.py src.json tgt.json > diff.json\n#      # exit 1 = changed -> add { sourceItemId, itemType } to $ITEMS; exit 0 = unchanged.\n#      # Forward diff.json (NOT src.json\u002Ftgt.json) to the model to explain the change.\n#    Merge NEW + CHANGED into $ITEMS. When equality can't be proven, include the item.\n\n# 4. Selective deploy of just the changed set.\naz rest --method POST --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fdeploy\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body \"$(jq -n --arg s \"$SOURCE_STAGE_ID\" --arg t \"$TARGET_STAGE_ID\" --argjson items \"$ITEMS\" \\\n    '{ sourceStageId: $s, targetStageId: $t, items: $items, note: \"Deploy only changed items\" }')\"\n# Then poll \u002Fv1\u002Foperations\u002F{operationId} until terminal.\n# NOTE: a selective deploy does NOT propagate deletions — use a full deploy (omit items) for those.\n```\n\n### Prompt\u002Fresponse\n\n**User:** \"Promote my Sales dev workspace to the Test stage and tell me when it's done.\"\n\n**Assistant (behavior):**\n1. Lists deployment pipelines → filters to the one whose Development stage holds the Sales dev workspace; captures `sourceStageId` (Development) and `targetStageId` (Test).\n2. Confirms the Test stage has an assigned workspace (or asks for a name + capacity to create one).\n3. POSTs `deploy` with a `note`, receives `202`, extracts the operation ID.\n4. Polls `\u002Fv1\u002Foperations\u002F{operationId}` until terminal, then reports success and the list of deployed items (or the failure reason).\n","> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry\n> `x-ms-fabric-skill: deployment-pipelines-authoring-cli` (`az rest`: `--headers \"x-ms-fabric-skill=deployment-pipelines-authoring-cli\"`),\n> including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.\n\n> **CRITICAL NOTES**\n> 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering\n> 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\n> 3. To find a deployment pipeline or stage ID: list deployment pipelines (then stages) and filter by `displayName` with JMESPath — never guess IDs.\n\n# Fabric Deployment Pipelines Authoring — CLI Skill\n\nAutomates Fabric Application Lifecycle Management (ALM) with **deployment pipelines**: promote Fabric\ncontent between stages (typically Development → Test → Production) using the Fabric core control-plane\nREST API. This skill covers pipeline\u002Fstage lifecycle, workspace assignment, and stage-to-stage deployment\n(a long-running operation).\n\n## Prerequisite Knowledge\n\nRead these companion documents first — this skill assumes their patterns and does **not** repeat them:\n\n| Task | Reference | Notes |\n|---|---|---|\n| Finding Workspaces and Items in Fabric | [COMMON-CLI.md § Finding Workspaces and Items in Fabric](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#finding-workspaces-and-items-in-fabric) | **Mandatory** — resolve workspace\u002Fitem IDs by name via list + JMESPath |\n| Authentication & Token Acquisition | [COMMON-CORE.md § Authentication & Token Acquisition](..\u002F..\u002Fcommon\u002FCOMMON-CORE.md#authentication--token-acquisition) | Token audience must be `https:\u002F\u002Fapi.fabric.microsoft.com`; wrong audience = 401 |\n| Authentication Recipes | [COMMON-CLI.md § Authentication Recipes](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#authentication-recipes) | `az login` flows and token acquisition |\n| Fabric Control-Plane API via `az rest` | [COMMON-CLI.md § Fabric Control-Plane API via az rest](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#fabric-control-plane-api-via-az-rest) | **Always pass `--resource https:\u002F\u002Fapi.fabric.microsoft.com`** |\n| Core Control-Plane REST APIs | [COMMON-CORE.md § Core Control-Plane REST APIs](..\u002F..\u002Fcommon\u002FCOMMON-CORE.md#core-control-plane-rest-apis) | Pagination, LRO polling, rate-limiting patterns |\n| Long-Running Operations (LRO) | [COMMON-CLI.md § Long-Running Operations (LRO) Pattern](..\u002F..\u002Fcommon\u002FCOMMON-CLI.md#long-running-operations-lro-pattern) | **Deploy is an LRO** — poll `\u002Fv1\u002Foperations\u002F{id}` until terminal |\n| Environment URLs | [COMMON-CORE.md § Environment URLs](..\u002F..\u002Fcommon\u002FCOMMON-CORE.md#environment-urls) | Sovereign\u002Fgov clouds use different hosts |\n| Supported item types | [references\u002Fsupported-item-types.md](references\u002Fsupported-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 |\n| Diff two item definitions (token-efficient) | [references\u002Fscripts\u002Fdiff_item_definitions.py](references\u002Fscripts\u002Fdiff_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\u002Fscripts\u002Fdiff_item_definitions.py source.json target.json` (exit `0`=same, `1`=changed) |\n\nThis skill adds: **how to drive the deployment-pipelines REST surface** from an agentic terminal.\n\n## Concepts\n\n- A **deployment pipeline** contains **2–10 ordered stages** (`order` starts at 0). Each stage may have at\n  most **one assigned workspace**, and a workspace can be assigned to at most one stage.\n- **Deployment** copies supported item content from a **source stage** to an **adjacent target stage**.\n  Forward deploys (dev→test→prod) work between any adjacent stages. **Backward** deploys (e.g. prod→test)\n  are currently supported **only when the target stage is empty** (no assigned workspace) — you cannot\n  backward-deploy over a stage that already has a workspace.\n- **Item pairing (autobinding).** During deployment Fabric records a **connection between a source item and\n  its clone** in the target stage; this pairing is how later deploys know which target item to overwrite,\n  and how related items (e.g. a report and its semantic model) stay bound. There is **no REST API to _set_\n  pairing** — it is maintained automatically — but you can **observe** the current pairing via the\n  `sourceItemId` \u002F `targetItemId` fields returned by `List stage items`. See the *Fix a broken item pairing*\n  workflow below for the only supported repair.\n- Deploy is an **asynchronous long-running operation (LRO)**: the API returns `202 Accepted` with an\n  operation ID; you poll for completion.\n- **Deployment rules** and **parameter rules** (e.g. repoint a data source per stage) are configured in the\n  Fabric **portal UI** — there is **no REST API to create rules**. Do not claim otherwise.\n- Only **supported item types** are copied by a deploy; unsupported items are skipped (not an error). The\n  supported set changes over time — see [references\u002Fsupported-item-types.md](references\u002Fsupported-item-types.md).\n- There is **no \"what changed\" \u002F compare REST API**. `List stage items` returns item **identity + pairing**\n  (`itemId`, `itemDisplayName`, `itemType`, `sourceItemId`, `targetItemId`, `lastDeploymentTime`) — but **no\n  change status**, and `lastDeploymentTime` is the last **deployment** time, **not** the last edit time, so\n  it is not a reliable change signal. To deploy only changed items you must **diff the two stages yourself**\n  and build the `items` list (see the *Deploy only changed items* workflow below). The portal's \"Compare\"\n  view is server-side and not exposed via API.\n\n## Must\u002FPrefer\u002FAvoid\n\n### MUST DO\n- Resolve pipeline, stage, and workspace **IDs by name** via list + JMESPath before any mutating call. Never fabricate GUIDs.\n- Target the correct base URL: `https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines` and acquire a token for the `https:\u002F\u002Fapi.fabric.microsoft.com` audience.\n- Treat **Deploy Stage Content** as an LRO: on `202`, capture the operation ID and poll `\u002Fv1\u002Foperations\u002F{operationId}` until the state is `Succeeded`\u002F`Failed`, then surface the result.\n- When the **target stage has no assigned workspace**, include `createdWorkspaceDetails` (name, and `capacityId` when needed) in the deploy body, or the deploy fails.\n- Confirm destructive intent (delete pipeline, unassign workspace, backward deploy over prod) with the user before executing.\n- 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\u002Fdeploy. Surface a clear, actionable message on `401`\u002F`403` rather than retrying blindly.\n\n### PREFER\n- Selective deploys via the `items` array (`{ sourceItemId, itemType }`) when the user names specific items; omit `items` to deploy **all** supported items.\n- A human-readable `note` on every deploy — but know it is **write-only**: the API accepts it and never\n  returns it (it appears only in the portal UI). For a programmatic audit trail, also record the deploy\n  externally (CI\u002FCD logs or a Git commit message).\n- `List Deployment Pipeline Stage Items` to preview what will move before deploying.\n- Idempotent scripting: check whether a pipeline\u002Fstage\u002Fassignment already exists before creating it.\n\n### AVOID\n- Inventing a \"create deployment rule\" or \"parameter rule\" REST call — those are UI-only today.\n- Assigning a workspace during an **active deployment** (the assign call fails) or to a stage\u002Fworkspace that is already paired.\n- Hardcoding `api.fabric.microsoft.com` in sovereign clouds — resolve the host from environment config.\n- Using a service principal without first confirming the Fabric admin enabled SP creation of deployment pipelines.\n- **Hashing raw `getDefinition` output to detect changes without normalizing.** Deployment **auto-rebinds**\n  embedded references in the target (pipeline `notebookId`\u002F`workspaceId`, report→model id, Direct Lake\n  server\u002Fdb), so a paired target's definition legitimately differs from the source even when nothing was\n  edited — naive hashing reports **false \"changed\"**. Strip\u002Fnormalize those binding fields before comparing.\n- **Diffing by dumping every item definition into the agent's context.** A full two-stage content diff can be\n  dozens of `getDefinition` calls and >100 KB — do the compare in a script\n  ([references\u002Fscripts\u002Fdiff_item_definitions.py](references\u002Fscripts\u002Fdiff_item_definitions.py)) and surface only\n  the resulting change list, and for a changed item forward **only the emitted diff**, never the two full\n  definitions, to the model.\n- Unassigning a workspace to repair a broken pairing **without first warning the user** that unassign\n  **permanently deletes that stage's deployment history and its configured deployment\u002Fparameter rules** —\n  always ask whether the stage has rules before unassigning (see *Fix a broken item pairing*).\n\n## REST API Reference\n\nBase: `https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1`. Delegated scopes are **per operation** — provision a service\nprincipal with least privilege:\n\n| Operation | Required delegated scope |\n|---|---|\n| List \u002F Get (pipelines, stages, stage items, operations) | `Pipeline.Read.All` **or** `Pipeline.ReadWrite.All` |\n| Create \u002F Update \u002F Delete pipeline, Update stage | `Pipeline.ReadWrite.All` |\n| Assign \u002F Unassign workspace | `Pipeline.ReadWrite.All` **and** `Workspace.ReadWrite.All` |\n| **Deploy stage content** | **`Pipeline.Deploy`** |\n\nDeploy uses its own `Pipeline.Deploy` scope — an app scoped only to `Pipeline.ReadWrite.All` gets a **403**\non `POST ...\u002Fdeploy`.\n\n| Operation | Method + Path |\n|---|---|\n| List pipelines | `GET \u002FdeploymentPipelines` |\n| Create pipeline | `POST \u002FdeploymentPipelines` |\n| Get \u002F Update \u002F Delete pipeline | `GET|PATCH|DELETE \u002FdeploymentPipelines\u002F{id}` |\n| List \u002F Get stages | `GET \u002FdeploymentPipelines\u002F{id}\u002Fstages[\u002F{stageId}]` |\n| Update stage | `PATCH \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}` |\n| List stage items | `GET \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}\u002Fitems` |\n| Assign workspace to stage | `POST \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}\u002FassignWorkspace` |\n| Unassign workspace from stage | `POST \u002FdeploymentPipelines\u002F{id}\u002Fstages\u002F{stageId}\u002FunassignWorkspace` |\n| **Deploy stage content (LRO)** | `POST \u002FdeploymentPipelines\u002F{id}\u002Fdeploy` |\n| List operations (≤20 recent) | `GET \u002FdeploymentPipelines\u002F{id}\u002Foperations` |\n| Get operation (with execution plan) | `GET \u002FdeploymentPipelines\u002F{id}\u002Foperations\u002F{operationId}` |\n| Role assignments | `GET|POST|DELETE \u002FdeploymentPipelines\u002F{id}\u002FroleAssignments[\u002F{principalId}]` |\n\n### Request-body shapes (guidance)\n\n- **Create**: `{ \"displayName\", \"description\"?, \"stages\": [ { \"displayName\", \"description\"?, \"isPublic\" } ] }` — 2–10 stages.\n- **Assign workspace**: `{ \"workspaceId\" }`.\n- **Deploy**: `{ \"sourceStageId\", \"targetStageId\", \"items\"?: [ { \"sourceItemId\", \"itemType\" } ], \"note\"?, \"options\"?: { \"allowCrossRegionDeployment\": false }, \"createdWorkspaceDetails\"?: { \"name\", \"capacityId\"? } }`.\n\n## Required permissions\n\nDeployment pipeline operations are governed by **two** independent permission systems: your role on the\n**pipeline** (its own `roleAssignments`) and your role on each **workspace** involved. You generally need\n**both**. Deployment pipelines require a Fabric capacity\u002Fsubscription, and the pipeline creator becomes the\npipeline **Admin**.\n\n| Operation | Pipeline role | Workspace role(s) |\n|---|---|---|\n| Create a pipeline | — (becomes **Admin** on create) | **Admin** of a Fabric workspace (feature access prerequisite) |\n| Get \u002F list pipeline, stages, items, operations | **Admin** (shared access) | — |\n| Update \u002F delete pipeline; manage `roleAssignments` | **Admin** | — |\n| **Assign \u002F unassign** a workspace to a stage | **Admin** | **Admin** of the workspace being (un)assigned |\n| **Deploy** stage content | **Admin** | at least **Contributor\u002FMember** on **both** the source and target stage workspaces (higher role if the target items require it) |\n| 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 |\n\nNotes:\n- Sharing a pipeline grants the pipeline **Admin** role — there is no lower \"viewer-only\" pipeline write role for these operations.\n- 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).\n- On `403`, distinguish *missing pipeline role* from *missing workspace role* in the message so the user knows which access to request.\n\n\n\n**Create a pipeline** → POST the display name + ordered stages; capture the returned stage IDs (they are\nwhat you deploy between).\n\n**Assign a workspace to a stage** → resolve stage ID and workspace ID by name, verify both are unassigned,\nthen POST `assignWorkspace`. Requires admin on both the pipeline and the workspace.\n\n**Deploy content** → resolve source\u002Ftarget stage IDs, optionally preview stage items, POST `deploy` (all\nitems or a selected `items` list) with a `note`, then poll the returned operation to completion and report\nwhich items moved.\n\n**Deploy only changed items** → there is no diff\u002Fcompare API, so compute the delta yourself. `List stage\nitems` gives identity + pairing only (no timestamps, no change status), so change detection means comparing\n**item definitions**:\n1. Resolve the source and target **stage** IDs and the workspace assigned to each.\n2. List items in **both** stages (`GET ...\u002Fstages\u002F{stageId}\u002Fitems`) — each source row carries `sourceItemId`\n   (as `itemId`) and its paired `targetItemId` (absent = **new\u002Funpaired**). Also list the target stage to find\n   **deleted** items (present in target, not paired from any source). Pair by `targetItemId`; fall back to\n   `(itemType, displayName)` only when no pipeline pairing exists (name-matching can't detect renames).\n3. **Filter out system-managed children** — a `SQLEndpoint` is auto-created per Lakehouse\u002FWarehouse and should\n   not be diffed or deployed on its own; it follows its parent.\n4. Classify each paired item:\n   - **New** (no `targetItemId`) → deploy.\n   - **Changed** → detect via `POST ...\u002Fitems\u002F{id}\u002FgetDefinition` on **both** stages, then diff. Run\n     [references\u002Fscripts\u002Fdiff_item_definitions.py](references\u002Fscripts\u002Fdiff_item_definitions.py) on the two\n     responses: it decodes each part, **normalizes** the auto-rebound fields (pipeline `notebookId`\u002F\n     `workspaceId`, report model id, Direct Lake server\u002Fdb) for you, and prints only the differing parts\n     (exit `1` = changed, `0` = identical) — so you don't hand-roll hashing or false-positive on unedited\n     items. Note the `getDefinition` contract differs by type:\n     `Notebook`\u002F`SemanticModel`\u002F`Report` are **LRO** (`202` → poll → `GET ...\u002Fresult`);\n     `DataPipeline` returns **`200` synchronously**.\n   - **Warehouse** does have a definition API:\n     [Get Warehouse Definition](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Frest\u002Fapi\u002Ffabric\u002Fwarehouse\u002Fitems\u002Fget-warehouse-definition)\n     is `POST ...\u002Fworkspaces\u002F{workspaceId}\u002Fwarehouses\u002F{warehouseId}\u002FgetDefinition`, with `format=sqlproj`\n     (default) or `format=dacpac`. Accept `200`; for `202`, follow the documented LRO to its result,\n     carrying the skill telemetry header on every request. The API requires Warehouse read\u002Fwrite\n     permissions even though it retrieves a definition. Compare SQL-project\u002Fschema content with\n     appropriate tooling; the generic JSON diff helper is **not** a schema-aware binary DACPAC comparer.\n     Definitions do not include table data. If schema equality is unproven, report that limitation\n     rather than claiming the API does not exist or declaring the item unchanged.\n   - `Lakehouse` \u002F `Environment` expose `getDefinition` but capture structure\u002Fmetadata only\n     (not table data or most content edits); diff by **presence**, flag user-reported content changes,\n     and state the limits of any equality claim.\n   - When you cannot prove equality, treat the item as **changed** (safe default).\n5. Do the comparison **in a script** (parallelize the independent `getDefinition` calls; they dominate\n   latency) and surface only the computed change list. To let the model reason about *what* changed in an\n   item, forward **only the emitted diff** (`diff_item_definitions.py` output), not the two full definitions —\n   a normalized diff is typically a few lines versus the >100 KB of raw payloads.\n6. Filter to **supported item types** (see references), show the user the change list, confirm, then POST a\n   **selective** `deploy` with the `{ sourceItemId, itemType }` array and a `note`, and poll to completion.\n\n> Deletions do **not** propagate via a selective `items` deploy — an item removed from the source stage is not\n> removed from the target by a selective deploy. Use a **full** deploy (omit `items`) to propagate deletions,\n> or delete the target item manually, and warn the user of this before promoting.\n\n**Fix a broken item pairing** → pairing (the source↔target connection Fabric maintains, a.k.a. autobinding)\nis **not settable via any REST API**. When two items that should be paired across stages are not — surfaced\nby a deploy that duplicates an item instead of overwriting it, an autobind\u002Fdependency failure, or the user\nreporting it — the **only supported repair is to unassign the affected stage's workspace and re-assign it**,\nwhich forces Fabric to rebuild the pairing on the next deploy. This is destructive:\n1. **Warn the user first.** Unassigning a workspace **permanently deletes that stage's deployment history and\n   all its configured deployment\u002Fparameter rules** — they cannot be recovered by re-assigning.\n2. **Ask whether the stage has rules.** Because rules are UI-only (no REST API to read or recreate them),\n   explicitly ask the user whether the stage has deployment\u002Fparameter rules configured **before** unassigning.\n   If it does, have them record the rules (or recreate them in the portal afterward) and get explicit\n   confirmation to proceed.\n3. Only after confirmation, `POST ...\u002Fstages\u002F{stageId}\u002FunassignWorkspace`, then\n   `POST ...\u002Fstages\u002F{stageId}\u002FassignWorkspace` with the same `workspaceId`, and re-run the deploy so the\n   pairing is re-established.\n\n**Track \u002F audit** → `List operations` for recent history; `Get operation` to inspect the execution plan and\nper-item status of a specific deployment.\n\n### Deploy operational caveats & common errors\n\n- **One deploy per pipeline at a time.** A pipeline runs a single operation at a time; starting another while\n  one is in flight fails with **`WorkspaceMigrationOperationInProgress` (HTTP 400)**. Always poll the current\n  operation to a terminal state before starting the next stage promotion (this is also why the *assign*\n  workspace call fails during an active deployment).\n- **First deploy after assigning a workspace can fail with `Alm_InvalidRequest_WorkloadUnavailable`.** Newly\n  assigned workspaces need **~60–120 s** for workload services (Lakehouse, Notebook, etc.) to initialize.\n  Mitigate by waiting before the first deploy, or deploy Power BI items (`SemanticModel`, `Report`) first and\n  Fabric-native items (`Lakehouse`, `Notebook`) after a short delay; retry on this error. Subsequent deploys\n  are reliable once workloads are warm.\n- **The operation ID is returned in the `x-ms-operation-id` response header** (alongside `Location`), not the\n  `202` body. `az rest` does not surface response headers cleanly — for reliable header capture in automation,\n  issue the deploy with `curl -i` (or Python `requests`) and parse the header, then poll\n  `\u002Fv1\u002Foperations\u002F{operationId}` with `az rest`.\n- **Deploy copies definitions, not data.** Only item metadata\u002Fdefinitions are promoted; table data, query\n  results, and caches are not. Trigger refreshes\u002Floads in the target stage after a deploy.\n- **Maximum 300 items per deploy request.** A selective (or full) deploy is capped at **300 deployed items**;\n  batch larger promotions across multiple deploy calls.\n\n## Examples\n\n### Create a three-stage pipeline\nDeployment-pipeline `displayName` is **unique tenant-wide** — a create for a name\nalready in use fails with `Alm_InvalidRequest_DuplicateAlmPipelineName` (HTTP 400,\n\"pipeline name ... is already in use\"). To make a create re-runnable, drop any\nexisting pipeline of that name first, then create. Write the JSON body to a file\nand pass it with `--body @file.json` — an inline multi-line `--body '{...}'` is\nmangled into an empty body on Windows\u002FPowerShell (`az` is `az.cmd`), which the API\nrejects with `InvalidInput: Unexpected end when reading JSON`.\n```bash\n# Idempotent: delete an existing \"Sales Analytics ALM\" if present, then create.\nEXISTING=$(az rest --method GET --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\" \\\n  --query \"value[?displayName=='Sales Analytics ALM'].id | [0]\" --output tsv)\nif [ -n \"$EXISTING\" ]; then\n  az rest --method DELETE --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n    --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$EXISTING\"\nfi\n\ncat > \u002Ftmp\u002Fcreate-pipeline.json \u003C\u003C 'EOF'\n{\n  \"displayName\": \"Sales Analytics ALM\",\n  \"description\": \"Dev\u002FTest\u002FProd promotion for Sales Analytics\",\n  \"stages\": [\n    { \"displayName\": \"Development\", \"isPublic\": false },\n    { \"displayName\": \"Test\",        \"isPublic\": false },\n    { \"displayName\": \"Production\",  \"isPublic\": true }\n  ]\n}\nEOF\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body @\u002Ftmp\u002Fcreate-pipeline.json\n```\n\n### Assign a workspace to the Development stage\n```bash\n# $PIPELINE_ID and $DEV_STAGE_ID resolved via list + JMESPath; $WS_ID resolved from workspace name.\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fstages\u002F$DEV_STAGE_ID\u002FassignWorkspace\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body \"{ \\\"workspaceId\\\": \\\"$WS_ID\\\" }\"\n```\n\n### Deploy all items dev → test and wait for the LRO\n```bash\n# Kick off the deployment (returns 202 + an operation id header).\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fdeploy\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body \"{ \\\"sourceStageId\\\": \\\"$DEV_STAGE_ID\\\", \\\"targetStageId\\\": \\\"$TEST_STAGE_ID\\\", \\\"note\\\": \\\"Promote validated dev build\\\" }\" \\\n  --verbose\n# Then poll \u002Fv1\u002Foperations\u002F{operationId} until state is Succeeded or Failed\n# (see COMMON-CLI § Long-Running Operations pattern).\n```\n\n### Deploy only selected items\n```bash\naz rest --method POST \\\n  --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fdeploy\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body '{\n    \"sourceStageId\": \"'\"$TEST_STAGE_ID\"'\",\n    \"targetStageId\": \"'\"$PROD_STAGE_ID\"'\",\n    \"items\": [\n      { \"sourceItemId\": \"'\"$MODEL_ID\"'\", \"itemType\": \"SemanticModel\" },\n      { \"sourceItemId\": \"'\"$REPORT_ID\"'\", \"itemType\": \"Report\" }\n    ],\n    \"note\": \"Promote reviewed model + report to production\"\n  }'\n```\n\n### Deploy only the items that changed (compute the diff first)\n```bash\n# 1. List paired items for BOTH stages. Each source row carries itemId (= sourceItemId)\n#    and its paired targetItemId (absent = new\u002Funpaired). There is NO timestamp or\n#    change-status field, so \"changed\" must be detected from item definitions.\naz rest --method GET --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fstages\u002F$SOURCE_STAGE_ID\u002Fitems\" \\\n  > source-items.json\n\n# 2. NEW items = unpaired (no targetItemId). Exclude system-managed SQLEndpoint children.\nNEW=$(jq '[.value[]\n  | select(.itemType != \"SQLEndpoint\")\n  | select(has(\"targetItemId\") | not)\n  | { sourceItemId: .itemId, itemType: .itemType }]' source-items.json)\n\n# 3. CHANGED items (paired): fetch getDefinition from BOTH stages, then diff with\n#    references\u002Fscripts\u002Fdiff_item_definitions.py. It decodes each part, NORMALIZES the\n#    auto-rebound fields (notebookId\u002FworkspaceId in pipelines, model id in reports,\n#    server\u002Fdb in Direct Lake models) and prints ONLY the differing parts. Notebook\u002F\n#    SemanticModel\u002FReport are LRO (202 -> poll -> \u002Fresult); DataPipeline returns 200 sync.\n#    Parallelize the independent getDefinition calls. Per paired definition-backed item:\n#      getDefinition SOURCE_WS id            > src.json\n#      getDefinition TARGET_WS targetItemId  > tgt.json\n#      python references\u002Fscripts\u002Fdiff_item_definitions.py src.json tgt.json > diff.json\n#      # exit 1 = changed -> add { sourceItemId, itemType } to $ITEMS; exit 0 = unchanged.\n#      # Forward diff.json (NOT src.json\u002Ftgt.json) to the model to explain the change.\n#    Merge NEW + CHANGED into $ITEMS. When equality can't be proven, include the item.\n\n# 4. Selective deploy of just the changed set.\naz rest --method POST --resource https:\u002F\u002Fapi.fabric.microsoft.com \\\n  --url \"https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002FdeploymentPipelines\u002F$PIPELINE_ID\u002Fdeploy\" \\\n  --headers \"Content-Type=application\u002Fjson\" \\\n  --body \"$(jq -n --arg s \"$SOURCE_STAGE_ID\" --arg t \"$TARGET_STAGE_ID\" --argjson items \"$ITEMS\" \\\n    '{ sourceStageId: $s, targetStageId: $t, items: $items, note: \"Deploy only changed items\" }')\"\n# Then poll \u002Fv1\u002Foperations\u002F{operationId} until terminal.\n# NOTE: a selective deploy does NOT propagate deletions — use a full deploy (omit items) for those.\n```\n\n### Prompt\u002Fresponse\n\n**User:** \"Promote my Sales dev workspace to the Test stage and tell me when it's done.\"\n\n**Assistant (behavior):**\n1. Lists deployment pipelines → filters to the one whose Development stage holds the Sales dev workspace; captures `sourceStageId` (Development) and `targetStageId` (Test).\n2. Confirms the Test stage has an assigned workspace (or asks for a name + capacity to create one).\n3. POSTs `deploy` with a `note`, receives `202`, extracts the operation ID.\n4. Polls `\u002Fv1\u002Foperations\u002F{operationId}` until terminal, then reports success and the list of deployed items (or the failure reason).\n",{"name":5,"description":7},"main","e31422e7d1045ef3a0906df9ff5991f2338af010","plugins\u002Ffabric-skills\u002Fskills\u002Fdeployment-pipelines-authoring-cli",395,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-12 20:10:24",{"source":8,"skillName":5,"commands":38,"prompt":48,"zipAvailable":49},[39,42,45],{"tool":40,"command":41},"npx","npx skills add microsoft\u002Fskills-for-fabric --skill deployment-pipelines-authoring-cli",{"tool":43,"command":44},"bunx","bunx skills add microsoft\u002Fskills-for-fabric --skill deployment-pipelines-authoring-cli",{"tool":46,"command":47},"pnpm","pnpm dlx skills add microsoft\u002Fskills-for-fabric --skill deployment-pipelines-authoring-cli","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fplugins\u002Ffabric-skills\u002Fskills\u002Fdeployment-pipelines-authoring-cli\u002FSKILL.md",true,[51,57],{"path":52,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":55,"sourceHtmlUrl":56},"references\u002Fscripts\u002Fdiff_item_definitions.py","SCRIPT","脚本",14477,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fplugins\u002Ffabric-skills\u002Fskills\u002Fdeployment-pipelines-authoring-cli\u002Freferences\u002Fscripts\u002Fdiff_item_definitions.py",{"path":58,"resourceType":59,"resourceTypeDesc":60,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Fsupported-item-types.md","REFERENCE","参考文档",5048,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fplugins\u002Ffabric-skills\u002Fskills\u002Fdeployment-pipelines-authoring-cli\u002Freferences\u002Fsupported-item-types.md",[64,72,77,102,131,136],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":71},"01M78JNNY5VN2MZ7TSV040K3FJ","fabric-policies-cli","Author, review and manage Microsoft Fabric governance policies and PolicySet items. Invoke before clarifying underspecified lockdown requests or missing intent, identities or scope. Discover current contracts and roles, map scenarios to rules, and execute one approved API lifecycle. Not catalog audits or KQL policies. Triggers: Fabric policy, PolicySet, governance rule, latest Fabric policies, policy contract review.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fskills\u002Ffabric-policies-cli\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":73,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":71},"01M78JNBFP3GAR4MSKEMHY2HDE","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fplugins\u002Ffabric-skills\u002Fskills\u002Ffabric-policies-cli\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":23},"01M6PHZNVB6K7DCCJH4YZHKC4F","ontology-cli","Manages Microsoft Fabric Ontology items: authors legacy V1 entity\u002Frelationship definitions and answers questions for new-experience (V2) Ontologies through ask_ontology. Use for Ontology item operations or grounded questions; V2 authoring\u002Fupgrades and V1 queries are unsupported. Power BI data questions use fabriciq, report authoring powerbi-report-cli, and model\u002FDAX changes semantic-model-authoring.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fskills\u002Fontology-cli\u002FSKILL.md",[],[20,84,85,86,9,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101],"ontology","ontology cli","ask","operations","bi","microsoft fabric","changes","queries","power bi","relationship","fabriciq","v1","Legacy","use","upgrades","for","model","power",{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":113,"publishedAt":23},"01M6PHZ91CSTP67DM6JN8TYEFV","databasehub-cli","Analyzes Database Hub inventory, health, and security posture through Entra-authenticated Fabric APIs. Use for estate counts; SQL\u002FPostgreSQL CPU, storage, and memory; Cosmos DB availability\u002FRU; authentication\u002Fauditing\u002FCMK warnings; and Fabric SQL inventory. Fabric SQL tuning routes to sqldb-cli; Warehouse\u002FLakehouse\u002FMirrored Database SQL to sqldw-cli. Triggers: data estate performance, database estate health, database security posture.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fskills\u002Fdatabasehub-cli\u002FSKILL.md",[108],{"categoryNo":109,"categoryName":110,"taxonomyType":111,"taxonomyTypeDesc":112},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",[20,114,115,116,117,118,119,120,121,99,97,122,123,124,125,126,127,128,129,130],"databasehub cli","database","CPU","database sql","security posture","postgresql","health","database security","triggers","cosmos","authentication","inventory","performance","db","memory","availability","warehouse",{"skillNo":132,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":23},"01M6PHYVDVBD0VQN4FFAMN428Z","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fplugins\u002Ffabric-skills\u002Fskills\u002Fontology-cli\u002FSKILL.md",[],[20,84,85,99,100,101,94,98,90,9,87,88,89,91,92,93,86,95,96,97],{"skillNo":137,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":138,"categories":139,"keywords":141,"publishedAt":23},"01M6PHYDZ17VY69E3GS71KFW09","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fskills-for-fabric\u002Fblob\u002Fmain\u002Fplugins\u002Ffabric-skills\u002Fskills\u002Fdatabasehub-cli\u002FSKILL.md",[140],{"categoryNo":109,"categoryName":110,"taxonomyType":111,"taxonomyTypeDesc":112},[20,114,130,129,117,127,126,125,116,118,119,120,121,115,97,122,123,128,99,124]]