Deploying Fabric content
A deploy moves item definitions from a source, a Git branch or a
workspace, into a target workspace. Four routes do it, each with its own
reference; this file picks one and wraps it in the steps every route
shares. Take them in order: a wrong route invalidates every step after
it.
Past a route's reference, its tool's own docs as markdown source,
curl -s https://raw.githubusercontent.com/microsoft/<repo>/main/docs/<path>.md
with <repo> fabric-cicd or fabric-cli, then Learn, by
microsoft-learn-mcp (microsoft_docs_search, then
microsoft_docs_fetch), or with no server, curl -sL -H 'Accept: text/markdown' <page URL> (undocumented, read 2026-11-07). A live page that contradicts a line here wins:
say so, act on the page, and route the fix by capture-learning, bar
a dated measured line that names the page it overrules and the call that
measured it, which a page changed since its date sends back to re-measure.
An observed claim is cited or marked pending a doc check, and stands, marked
observed, only where no page covers it.
1. Pick the route
| Source of truth |
Route |
Learn's option |
Read |
| Git, one branch pushed to each stage by a script or CI |
the fabric-cicd Python library |
2 |
fabric-cicd.md |
| Git, the same in one command |
fab deploy --config, which wraps the library and reads its config.yml and parameter.yml |
2 |
fab-deploy.md, then fabric-cicd.md |
| Git, a branch per stage, each stage's workspace connected |
Git integration's Update From Git |
1 |
rest-api § Git Integration APIs |
| The workspace: dev promoted to test and prod in the service |
deployment pipelines |
3 |
deployment-pipelines.md |
Learn's option 2 also names the Bulk Import Item Definitions API, which
the library calls under enable_bulk_publish; Learn's
tutorial
calls it directly.
Never deploy into one workspace by both routes. The library makes
its target match the repository, overwriting whatever a pipeline
promoted, and an item a Git route adds to a pipeline stage is not paired
with its source
(deployment-pipelines.md § Item
pairing and autobinding). Git on the first stage with pipelines onward is
not a mix: it is option 3, whose source of truth Learn gives as "Fabric
workspace (Git only through dev)" (read 2026-10-09). Decision guide:
Choose the best Fabric CI/CD workflow.
2. Preflight, every route
Identity. Name the identity the deploy will run as, and check:
- a workspace role on the target: Contributor or above for the library
and
fab deploy, Admin for enable_hard_delete;
- for a service principal, on any route, the tenant setting Service
principals can call Fabric public APIs (older Learn pages: can use
Fabric APIs);
- for Update From Git, the caller's own Git credentials, and more than
the REST page's Contributor: write permission on every item, item
ownership where a tenant switch blocks non-owners, and Build on
external dependencies, by Learn's
Git permissions table;
from 2026-12-01, no Git integration at all without read-write
permission on the workspace's items (read 2026-10-13);
- for a deployment pipeline, a second permission system on top of the
workspace roles, pipeline Admin, and on an app registration's
delegated token the deploy-only scope,
Pipeline.Deploy or
DeploymentPipeline.Deploy.All, which an az token deployed without
(deployment-pipelines.md §
Permissions, § Delegated scopes).
What can move. Each route carries its own set of item types: the
library's caveats are in fabric-cicd.md §
Item-type caveats, and a pipeline skips whatever is missing from
deployment-pipelines-tables.md
§ Supported item types. Four caveats cross routes, and each lives here:
Deployment plans (preview): the fabric-cicd library doesn't support
them; attach one through Update From Git, Deploy Stage Content or Bulk
Import instead (Learn, 2026-10-06). The pipeline call's shape is in
deployment-pipelines.md §
Deploying.
OneLake image URLs: deployment pipelines don't rewrite them. A
report whose visuals source images from OneLake carries the workspace
GUID in each URL, so a promoted copy keeps loading them from the source
workspace, and nothing fails or warns until access to that workspace is
revoked or it is deleted:
https://onelake.dfs.fabric.microsoft.com/<workspace-guid>/<item-guid>/Files/<path>/<file-name>
Upstream's remedies are deployment-pipeline parameters or a rewrite
after deployment. Whether parameter.yml's find_replace reaches a
report definition for this is unverified, and whether Git integration,
fab deploy or the library rewrite these URLs is undocumented, which is
not "no"
(Learn).
PBIR reports: item 9 of Learn's general limitations lists them as
unsupported in deployment pipelines, yet a PBIR-stored report has
deployed to Test and Prod and redeployed in production use, per the
pipeline's own records (2026-08-25/26). Treat item 9 as a claim to test,
not a blocker, and don't stop the pbir-* workflow on it; the evidence
is in
deployment-pipelines-tables.md
§ Supported item types.
Direct Lake semantic models are the one model type a pipeline
doesn't autobind: deployed with its lakehouse, the target model still
points at the source stage's lakehouse until a rule rebinds it, and
which rule depends on the flavour
(deployment-pipelines.md § Item
pairing and autobinding).
3. Plan, then stop
Before this session itself runs any of these, show what will change and
wait for the user's yes, as land-branch stops before main:
- a write to any stage past the first, test and prod above all;
- an orphan delete:
unpublish_all_orphan_items, a config.yml whose
missing unpublish block unpublishes orphans by default, or
enable_hard_delete, which bypasses the recycle bin;
- a backward deploy, or an unassign, which destroys the stage's
deployment history and its rules for good.
"Deploy it to prod" names a target, not what changes there, so it is not
the yes. Writing a CI pipeline file, or a script for the user to run,
deploys nothing and needs no stop.
What to show, by route:
- Library or
fab deploy: every run is a full deploy, so list the
item types and folders in scope, whether orphans go, and any
enable_*_unpublish flag that lets a data-bearing item be deleted.
- Update From Git: the
changes[] from Get Status: the incoming
items it will add, replace or delete, and any conflictType of
Conflict, which stops it unless the plan adds a conflictResolution.
Say so if it does, since that keeps one side's version of each
conflicting item. The body is rest-api's, § Git Integration
APIs.
- Deployment pipelines: no API compares stages before a deploy, so
list the stage items with their pairing. An unpaired item lands as a
new copy, a selective deploy deletes nothing in the target, and an
empty target stage gets a new workspace whose only admin is the
deploying identity.
4. Run
Read the route's reference, from the table in step 1, before its first
call: request shapes, flags and limits are not repeated here. On a
pipeline,
deployment-pipelines-tables.md
adds the supported items, the full permission tables and the rule
limitations.
5. Verify
A deploy moves metadata, not data, on every route. After one:
- Read the operation's result. A pipeline deploy that failed keeps its
error on one step of
executionPlan.steps[], and the steps after it
stay NotStarted, not deployed
(deployment-pipelines.md §
Deploying).
- Refresh in the target, each dataflow before the semantic models that
read it.
- Check pairing and bindings: on a pipeline, each item's pairing through
List stage items; on any route, each report bound to the target's
semantic model and each Direct Lake model reading the target's
lakehouse.
- Name what the deploy did not carry. On a pipeline that includes a
semantic model's refresh schedule, credentials and role assignments
(deployment-pipelines-tables.md
§ What a deploy copies).
6. When it fails
| Symptom |
Cause, and where the fix is |
| 403 from a pipeline call |
Say which system is missing: pipeline Admin, a workspace role on both stages, or Pipeline.Deploy on an app registration's delegated token. deployment-pipelines.md § Permissions, § Delegated scopes |
| 401 or "credential required" from the library |
Since v1.0 it needs an explicit token_credential. fabric-cicd.md § Troubleshooting |
| An item duplicated instead of overwritten |
Pairing. deployment-pipelines.md § Item pairing and autobinding |
| A report that lost its semantic model |
Autobinding, in the same section |
| Rules that didn't apply |
Rules apply on the next deploy. deployment-pipelines.md § Deployment rules |
A parameter.yml value not substituted |
fabric-cicd.md § Troubleshooting |
| An orphan lakehouse or warehouse not deleted |
On purpose, behind a flag. fabric-cicd.md § Feature flags |
| Deploy to the previous stage greyed out |
deployment-pipelines.md § Limits and gotchas |
A 404 from fab api on a pipeline path |
The audience. deployment-pipelines.md § Through fab |
| Update From Git refuses to start |
rest-api § Git Integration APIs |
| Anything else on a pipeline |
deployment-pipelines-tables.md § Troubleshooting |
See also
rest-api — long-running operations, Git integration, and the
definition APIs every route sits on; fab api mechanics in its
references/cli.md; token audiences and service principal setup in
its references/auth.md
variable-library — value sets, the other way to vary config
per stage
- A Data Factory pipeline's activities are
data-items', a
different thing from a deployment pipeline despite the name
1---2name: deploy3description: "Use when deploying, promoting or releasing Microsoft Fabric or Power BI items between workspaces — dev → test → prod, CI/CD — by any route: the fabric-cicd Python library (`FabricWorkspace`, `publish_all_items`, `parameter.yml`, `config.yml`), `fab deploy`, Git integration's Update From Git, or a deployment pipeline, scripted or run from Azure DevOps or GitHub Actions. Picks the route, checks the identity, shows the plan and stops before writing to a later stage, then verifies the deploy."4when_to_use: "Use when asked to deploy, promote or release a workspace or its items, set up a release pipeline for one, create a deployment pipeline or assign a workspace to a stage, or debug a deploy: a 403 that is a missing pipeline role rather than a workspace role, an item duplicated instead of overwritten, a report that lost its semantic model, rules that didn't apply, a parameter.yml value not substituted, or a greyed-out deploy-to-previous-stage button."5# model: inherit # any model: value blocks Copilot slash invocation6# effort: medium # unset = inherit session effort; there is no 'effort: inherit'7disable-model-invocation: false8metadata:9 source: https://skillmd.com/skills/wardawgmalvicious/deploy10---1112# Deploying Fabric content1314A deploy moves item definitions from a source, a Git branch or a15workspace, into a target workspace. Four routes do it, each with its own16reference; this file picks one and wraps it in the steps every route17shares. Take them in order: a wrong route invalidates every step after18it.1920Past a route's reference, its tool's own docs as markdown source,21`curl -s https://raw.githubusercontent.com/microsoft/<repo>/main/docs/<path>.md`22with `<repo>` `fabric-cicd` or `fabric-cli`, then Learn, by23`microsoft-learn-mcp` (`microsoft_docs_search`, then24`microsoft_docs_fetch`), or with no server, `curl -sL -H 'Accept: text/markdown' <page URL>` (undocumented, read 2026-11-07). A live page that contradicts a line here wins:25say so, act on the page, and route the fix by `capture-learning`, bar26a dated measured line that names the page it overrules and the call that27measured it, which a page changed since its date sends back to re-measure.28An observed claim is cited or marked pending a doc check, and stands, marked29observed, only where no page covers it.3031## 1. Pick the route3233| Source of truth | Route | Learn's option | Read |34| --- | --- | --- | --- |35| Git, one branch pushed to each stage by a script or CI | the fabric-cicd Python library | 2 | [fabric-cicd.md](references/fabric-cicd.md) |36| Git, the same in one command | `fab deploy --config`, which wraps the library and reads its `config.yml` and `parameter.yml` | 2 | [fab-deploy.md](references/fab-deploy.md), then [fabric-cicd.md](references/fabric-cicd.md) |37| Git, a branch per stage, each stage's workspace connected | Git integration's Update From Git | 1 | `rest-api` § Git Integration APIs |38| The workspace: dev promoted to test and prod in the service | deployment pipelines | 3 | [deployment-pipelines.md](references/deployment-pipelines.md) |3940Learn's option 2 also names the Bulk Import Item Definitions API, which41the library calls under `enable_bulk_publish`; Learn's42[tutorial](https://learn.microsoft.com/fabric/cicd/tutorial-bulkapi-cicd)43calls it directly.4445**Never deploy into one workspace by both routes.** The library makes46its target match the repository, overwriting whatever a pipeline47promoted, and an item a Git route adds to a pipeline stage is not paired48with its source49([deployment-pipelines.md](references/deployment-pipelines.md) § Item50pairing and autobinding). Git on the first stage with pipelines onward is51not a mix: it is option 3, whose source of truth Learn gives as "Fabric52workspace (Git only through dev)" (read 2026-10-09). Decision guide:53[Choose the best Fabric CI/CD workflow](https://learn.microsoft.com/fabric/cicd/manage-deployment).5455## 2. Preflight, every route5657**Identity.** Name the identity the deploy will run as, and check:5859- a workspace role on the target: Contributor or above for the library60 and `fab deploy`, Admin for `enable_hard_delete`;61- for a service principal, on any route, the tenant setting *Service62 principals can call Fabric public APIs* (older Learn pages: *can use63 Fabric APIs*);64- for Update From Git, the caller's own Git credentials, and more than65 the REST page's Contributor: write permission on every item, item66 ownership where a tenant switch blocks non-owners, and Build on67 external dependencies, by Learn's68 [Git permissions table](https://learn.microsoft.com/fabric/cicd/git-integration/git-integration-process#permissions);69 from 2026-12-01, no Git integration at all without read-write70 permission on the workspace's items (read 2026-10-13);71- for a deployment pipeline, a second permission system on top of the72 workspace roles, pipeline Admin, and on an app registration's73 delegated token the deploy-only scope, `Pipeline.Deploy` or74 `DeploymentPipeline.Deploy.All`, which an `az` token deployed without75 ([deployment-pipelines.md](references/deployment-pipelines.md) §76 Permissions, § Delegated scopes).7778**What can move.** Each route carries its own set of item types: the79library's caveats are in [fabric-cicd.md](references/fabric-cicd.md) §80Item-type caveats, and a pipeline skips whatever is missing from81[deployment-pipelines-tables.md](references/deployment-pipelines-tables.md)82§ Supported item types. Four caveats cross routes, and each lives here:8384- **Deployment plans** (preview): the fabric-cicd library doesn't support85 them; attach one through Update From Git, Deploy Stage Content or Bulk86 Import instead (Learn, 2026-10-06). The pipeline call's shape is in87 [deployment-pipelines.md](references/deployment-pipelines.md) §88 Deploying.89- **OneLake image URLs**: deployment pipelines don't rewrite them. A90 report whose visuals source images from OneLake carries the workspace91 GUID in each URL, so a promoted copy keeps loading them from the source92 workspace, and nothing fails or warns until access to that workspace is93 revoked or it is deleted:9495 ```http96 https://onelake.dfs.fabric.microsoft.com/<workspace-guid>/<item-guid>/Files/<path>/<file-name>97 ```9899 Upstream's remedies are deployment-pipeline parameters or a rewrite100 after deployment. Whether `parameter.yml`'s `find_replace` reaches a101 report definition for this is unverified, and whether Git integration,102 `fab deploy` or the library rewrite these URLs is undocumented, which is103 not "no"104 ([Learn](https://learn.microsoft.com/power-bi/visuals/power-bi-onelake-files)).105- **PBIR reports**: item 9 of Learn's general limitations lists them as106 unsupported in deployment pipelines, yet a PBIR-stored report has107 deployed to Test and Prod and redeployed in production use, per the108 pipeline's own records (2026-08-25/26). Treat item 9 as a claim to test,109 not a blocker, and don't stop the `pbir-*` workflow on it; the evidence110 is in111 [deployment-pipelines-tables.md](references/deployment-pipelines-tables.md)112 § Supported item types.113- **Direct Lake semantic models** are the one model type a pipeline114 doesn't autobind: deployed with its lakehouse, the target model still115 points at the source stage's lakehouse until a rule rebinds it, and116 which rule depends on the flavour117 ([deployment-pipelines.md](references/deployment-pipelines.md) § Item118 pairing and autobinding).119120## 3. Plan, then stop121122Before this session itself runs any of these, show what will change and123wait for the user's yes, as `land-branch` stops before `main`:124125- a write to any stage past the first, test and prod above all;126- an orphan delete: `unpublish_all_orphan_items`, a `config.yml` whose127 missing `unpublish` block unpublishes orphans by default, or128 `enable_hard_delete`, which bypasses the recycle bin;129- a backward deploy, or an unassign, which destroys the stage's130 deployment history and its rules for good.131132"Deploy it to prod" names a target, not what changes there, so it is not133the yes. Writing a CI pipeline file, or a script for the user to run,134deploys nothing and needs no stop.135136What to show, by route:137138- **Library or `fab deploy`**: every run is a full deploy, so list the139 item types and folders in scope, whether orphans go, and any140 `enable_*_unpublish` flag that lets a data-bearing item be deleted.141- **Update From Git**: the `changes[]` from Get Status: the incoming142 items it will add, replace or delete, and any `conflictType` of143 `Conflict`, which stops it unless the plan adds a `conflictResolution`.144 Say so if it does, since that keeps one side's version of each145 conflicting item. The body is `rest-api`'s, § Git Integration146 APIs.147- **Deployment pipelines**: no API compares stages before a deploy, so148 list the stage items with their pairing. An unpaired item lands as a149 new copy, a selective deploy deletes nothing in the target, and an150 empty target stage gets a new workspace whose only admin is the151 deploying identity.152153## 4. Run154155Read the route's reference, from the table in step 1, before its first156call: request shapes, flags and limits are not repeated here. On a157pipeline,158[deployment-pipelines-tables.md](references/deployment-pipelines-tables.md)159adds the supported items, the full permission tables and the rule160limitations.161162## 5. Verify163164A deploy moves metadata, not data, on every route. After one:1651661. Read the operation's result. A pipeline deploy that failed keeps its167 error on one step of `executionPlan.steps[]`, and the steps after it168 stay `NotStarted`, not deployed169 ([deployment-pipelines.md](references/deployment-pipelines.md) §170 Deploying).1712. Refresh in the target, each dataflow before the semantic models that172 read it.1733. Check pairing and bindings: on a pipeline, each item's pairing through174 List stage items; on any route, each report bound to the target's175 semantic model and each Direct Lake model reading the target's176 lakehouse.1774. Name what the deploy did not carry. On a pipeline that includes a178 semantic model's refresh schedule, credentials and role assignments179 ([deployment-pipelines-tables.md](references/deployment-pipelines-tables.md)180 § What a deploy copies).181182## 6. When it fails183184| Symptom | Cause, and where the fix is |185| --- | --- |186| 403 from a pipeline call | Say which system is missing: pipeline Admin, a workspace role on both stages, or `Pipeline.Deploy` on an app registration's delegated token. [deployment-pipelines.md](references/deployment-pipelines.md) § Permissions, § Delegated scopes |187| 401 or "credential required" from the library | Since v1.0 it needs an explicit `token_credential`. [fabric-cicd.md](references/fabric-cicd.md) § Troubleshooting |188| An item duplicated instead of overwritten | Pairing. [deployment-pipelines.md](references/deployment-pipelines.md) § Item pairing and autobinding |189| A report that lost its semantic model | Autobinding, in the same section |190| Rules that didn't apply | Rules apply on the next deploy. [deployment-pipelines.md](references/deployment-pipelines.md) § Deployment rules |191| A `parameter.yml` value not substituted | [fabric-cicd.md](references/fabric-cicd.md) § Troubleshooting |192| An orphan lakehouse or warehouse not deleted | On purpose, behind a flag. [fabric-cicd.md](references/fabric-cicd.md) § Feature flags |193| Deploy to the previous stage greyed out | [deployment-pipelines.md](references/deployment-pipelines.md) § Limits and gotchas |194| A 404 from `fab api` on a pipeline path | The audience. [deployment-pipelines.md](references/deployment-pipelines.md) § Through `fab` |195| Update From Git refuses to start | `rest-api` § Git Integration APIs |196| Anything else on a pipeline | [deployment-pipelines-tables.md](references/deployment-pipelines-tables.md) § Troubleshooting |197198## See also199200- `rest-api` — long-running operations, Git integration, and the201 definition APIs every route sits on; `fab api` mechanics in its202 `references/cli.md`; token audiences and service principal setup in203 its `references/auth.md`204- `variable-library` — value sets, the other way to vary config205 per stage206- A Data Factory pipeline's activities are `data-items`', a207 different thing from a deployment pipeline despite the name