Automate deployments with a deployment plan (preview)

A deployment plan extends an existing API request. It doesn't replace the API's standard flow. Add a plan to set item order. A plan can also run actions before or after an item deploys. The original request still sets the source, target, and selected items.

Important

This feature is in preview.

Choose an automation workflow

Start with the automation guide for your operation. Then add the deployment plan input from this article.

API that accepts a deployment plan	Existing automation guidance
Update From Git	Automate Git integration by using APIs
Deploy Stage Content	Automate your deployment pipeline with Fabric APIs
Bulk Import Item Definitions	Fabric CI/CD with Bulk Import Item Definitions API

Without a deployment plan, each API works as before.

These are the APIs that accept the deploymentPlan input. Your workflow can also call other APIs to prepare the operation or check its status. Continue to use those supporting APIs as described in the existing automation guide.

Prerequisites

Before you add a plan:

Create the deployment plan. Make sure the operation can resolve it.
Get a Microsoft Entra access token. Use it for the Fabric API.
Make sure the caller has the roles required by the original operation.
Make sure the token includes the original operation's scope and Item.Execute.All.
Add beta=true to the operation URL.

The token must include these scopes:

Operation	Original operation scope	Additional scope when a plan is supplied
Update From Git	`Workspace.GitUpdate.All`	`Item.Execute.All`
Deploy Stage Content	`Pipeline.Deploy` or `DeploymentPipeline.Deploy.All`	`Item.Execute.All`
Bulk Import Item Definitions	`Item.ReadWrite.All`	`Item.Execute.All`

The caller also needs the roles listed in the original API reference. The same reference lists the identity types that the API supports. A service principal or managed identity works only if every item in the operation supports it.

Add the deployment plan to a request

For each supported API:

Add beta=true to the request URL.
Add a deploymentPlan object inside the existing options object.
Keep the rest of the request unchanged.

Use the lowercase referenceType property. Its value is case-sensitive.

Update a workspace from Git

Use the plan's logical ID. The plan can come from the workspace or the incoming Git content. For a plan stored in Git, find the logical ID in its .platform file.

For an API-driven initial sync, call Initialize Connection first. If the response requires an update, add the plan to the following Update From Git request. Initialize Connection doesn't accept a deployment plan.

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/git/updateFromGit?beta=true

Add the following object to the Update From Git request:

{
  "options": {
    "deploymentPlan": {
      "logicalId": "00000000-0000-0000-0000-000000000000",
      "referenceType": "ByLogicalId"
    }
  }
}

Keep workspaceHead, remoteCommitHash, conflict resolution, and the other options. Build the full request by using the Git automation guide. The guide also shows how to poll the operation status. See Update from Git.

Deploy content between pipeline stages

Reference the deployment plan by its item ID.

POST https://api.fabric.microsoft.com/v1/deploymentPipelines/{deploymentPipelineId}/deploy?beta=true

Add the following object to the Deploy Stage Content request:

{
  "options": {
    "deploymentPlan": {
      "itemId": "00000000-0000-0000-0000-000000000000",
      "referenceType": "ByItemId"
    }
  }
}

Keep the source stage, target stage, selected items, deployment note, and other options. Build the full request by using the deployment pipeline guide. The guide also shows how to poll the operation status. See Automate your deployment pipeline with Fabric APIs.

Import item definitions

Use the plan's logical ID. Find it in the plan's .platform file.

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/bulkImportDefinitions?beta=true

Add the deployment plan to the Bulk Import request options:

{
  "options": {
    "allowPairingByName": false,
    "deploymentPlan": {
      "logicalId": "00000000-0000-0000-0000-000000000000",
      "referenceType": "ByLogicalId"
    }
  }
}

Keep all item definition parts and import options. Build the full request by using the Bulk Import tutorial. The tutorial also shows how to poll the operation status. See Fabric CI/CD with Bulk Import Item Definitions API.

Understand what the plan changes

The plan changes only the order and actions. It doesn't change the selected items.

Request input	What it controls
Original API request	Source, target, selected items, and operation-specific settings
Deployment plan	Explicit item order and pre-deploy or post-deploy actions
Fabric lineage	Dependencies that Fabric detects between selected items

Selected items outside a deployment group use the operation's standard behavior.

For how the request scope, plan relationships, Fabric lineage, and actions work together, see How a deployment plan works.

Validate the request

Before you run the automation, verify that:

The URL includes beta=true.
The token includes Item.Execute.All and the original operation's scope.
The deploymentPlan object is inside options, not at the request root.
referenceType uses the documented value and casing.
The item ID or logical ID isn't empty or malformed.
The operation can resolve the plan in the relevant workspace or incoming content.
The plan definition is valid and doesn't contain a circular dependency.

The operation stops when validation, an item, or an action fails. Fabric doesn't roll back completed work.

Considerations and limitations

The fabric-cicd library doesn't support deployment plans. Use Update From Git, Deploy Stage Content, or Bulk Import Item Definitions when you automate a deployment with a plan.

For all deployment plan constraints, see Deployment plan considerations and limitations.

Manage the deployment plan item

A deployment plan is a Fabric item. Use the following Fabric REST APIs to manage it. These calls are separate from the deployment operation.

Task	REST API
Create a plan	Create Deployment Plan
List plans in a workspace	List Items
Get plan properties	Get Item
Get the plan definition	Get Item Definition
Update plan properties	Update Item
Update the plan definition	Update Item Definition
Delete a plan	Delete Item

The deployment plan definition contains parts with a path, Base64 payload, and InlineBase64 payload type.

Feedback

Was this page helpful?

Last updated on 2026-09-29