agentleFS
hydrhydr/dataverse-modelling-mcp/skills/solution-pipelines/SKILL.md

solution-pipelines

Skill8 starsChanged 41 days agoMITView on GitHub

Deploy Dataverse solutions across environments via Power Platform Pipelines (deploymentpipeline / deploymentstagerun). Includes pipeline-host discovery, the 3-call Maker-UI workflow, stage-run status code mapping, permission pitfalls, and trade-offs between Pipeline deployment and direct solution export/import. Use when the user wants to promote a solution from dev → staging → prod, or when troubleshooting pipeline runs.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Only sent if the solution has any mandatory EnvVars or ConnRefs on the target.

    line 64
  2. Very specific:

    Default to Pipeline: when staging/prod targets are involved.

    line 148
  3. Very specific:

    Use solution layers (solution_remove_active_layer) to peel off the most recent unmanaged layer if the previous managed solution is still …

    line 193
  4. Very specific:

    Run hangs at "Nicht gestartet" forever: if you only do step 1. Always follow with PATCH + DeployPackageAsync (or use autoConfirm=true).

    line 214
  5. Very specific:

    After deploying a ribbon change, run ribbon_diagnose for the table on the target.

    line 225

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Solution Deployment via Power Platform Pipelines

Expert reference for deploying Dataverse solutions through Power Platform Pipelines via the dataverse-modelling-mcp server.

Hard prerequisites

  • Pipeline-Host environment is separate. The deploymentpipeline, deploymentstage, and deploymentstagerun entities live in a dedicated Pipeline-Host env (often hidden from non-admin users in the BAP environments list). The source/Dev env (where the solution actually lives) does NOT have these entities. All pipeline calls go against the Pipeline-Host URL — never against the source/target.
  • Permission (on the TARGET env, not the Pipeline-Host): the deploying user must have prvImportCustomization on each target environment the pipeline imports into. Without it, validation itself fails — the run goes to stagerunstatus = Fehlgeschlagen and validationresults contains SecLib::CheckPrivilege failed … PrivilegeName: prvImportCustomization with the user/BU GUID of the target env. Granting the user a Pipeline-Host group/role does NOT help — it must be a role carrying prvImportCustomization (e.g. System Customizer) on the target. Verified 2026-06-02: the same failure occurs identically in the Maker UI, confirming it is purely a target-env permission, not an MCP issue. After a role change allow for security-cache propagation / re-login.
  • Environment write policy (per project memory): contoso-dev writable without confirmation, contoso-staging and contoso-prod need explicit user confirmation before triggering a pipeline that writes there.
  • ⚠️ Token-AppId blocker — headless pipeline deploy via the direct API does NOT currently work (empirically established 2026-06-02). The Pipeline-Backend's validation workflow only fires for runs created by the Power Apps Maker portal AppId a8f7a65c-f5ba-4859-b2d6-df772c264e9d. A run created with any other appid returns HTTP 201 but stays in Nicht gestartet forever (validation never starts). The problem: a headless MCP cannot mint an a8f7a65c token —

    • Device Code Flow directly with a8f7a65c → token redemption fails with AADSTS7000218 (requires a client_secret; not a public client for device-code).
    • FOCI refresh-token exchange to a8f7a65c (from Azure CLI 04b07795 or PAC 9cee029c) → AADSTS70000 (not in the same client family).
    • The current code authenticates as PAC CLI (9cee029c) — that token IS obtainable headlessly but is NOT accepted by the backend → runs hang at Nicht gestartet.

    So solution_deploy_pipeline / pipeline_auth_init are effectively non-functional for committing a deploy. The create-payload, sequence, and DeployPackageAsync call are otherwise correct (verified call-for-call against a Maker-UI HAR capture). Recommended deployment path for MCP: the file-based solution_export + solution_import (normal Dataverse token, no appid gate). Pipelines remain a Maker-UI (or PAC CLI) operation. Read-only Pipeline calls (pipeline_list/pipeline_stages/pipeline_environments/pipeline_run_status) work fine — they are not appid-gated. The Auth-Code + PKCE avenue was also tested (2026-06-02) and fails: a8f7a65c has no manually-capturable redirect URI registered — both http://localhost and https://login.microsoftonline.com/common/oauth2/nativeclient return AADSTS50011 (redirect mismatch); only the Maker portal's own web origins are registered, which can't be captured from a CLI. Conclusion: there is no headless way to obtain an a8f7a65c token — solution_deploy_pipeline cannot be made to work from a headless MCP. Use file-based export/import instead.

Tool map

User intentMCP tool
List pipelines on a hostpipeline_list(pipelineHostOrgUrl)
List stages of a pipelinepipeline_stages(pipelineHostOrgUrl, pipelineId)
Map Power-Platform env GUID → pipeline-internal deploymentenvironmentidpipeline_environments(pipelineHostOrgUrl)
Poll a run's statuspipeline_run_status(pipelineHostOrgUrl, stageRunId)
Check, on the target, that a deployed ribbon change can take effect — before and after the runribbon_scan_unmanaged_layers, then ribbon_diagnose(table) (connected to the target)
Commit a deployNo tool — removed (see below). Use solution_export + solution_import, or the Maker UI / PAC CLI.

Note: the deploy tools solution_deploy_pipeline, pipeline_auth_init and pipeline_auth_complete were removed. A headless MCP cannot mint the Power-Apps-Maker (a8f7a65c) token the pipeline backend requires, so a committed deploy never starts. The investigation below is kept as background; only the read-only pipeline_* calls above are live. The deploymentsettingsjson / version-bump payloads are documented for anyone re-implementing the deploy path outside this server.

The 3-/4-call Maker-UI workflow

When a user clicks "Bereitstellung" (Deploy) on a stage card in the Maker UI, the browser makes three or four sequential calls (depending on whether the solution has mandatory environment variables / connection references on the target). Our solution_deploy_pipeline mirrors them when autoConfirm=true. Documented here for the case the tool needs extending.

Step 1 — POST: create stage run, kick off validation

POST {pipelineHostOrgUrl}/api/data/v9.0/deploymentstageruns?$select=deploymentstagerunid

{
  "artifactname": "<solution-unique-name>",
  "devdeploymentenvironment@odata.bind": "/deploymentenvironments(<devDeploymentEnvironmentId>)",
  "deploymentstageid@odata.bind": "/deploymentstages(<targetStageId>)",
  "makerainoteslanguagecode": "de-DE",
  "solutionid": "<solution-guid-from-source-env>"
}
→ 201 Created
{ "deploymentstagerunid": "<new-run-guid>" }

Validation now runs server-side; the row's stagerunstatus walks through Nicht gestartet → Überprüfen → Überprüfung erfolgreich. Skipping steps 2+3 leaves the run hanging at "Nicht gestartet" forever — this is the trap that the older deprecated pipelines({id})/Deploy endpoint never explained.

Step 2a (optional) — PATCH: set environment variables & connection-reference overrides

Only sent if the solution has any mandatory EnvVars or ConnRefs on the target. The UI shows this as the "Umgebungsvariablen" (environment variables) step in the dialog. Skip when there are none.

PATCH {pipelineHostOrgUrl}/api/data/v9.0/deploymentstageruns({runId})

{
  "deploymentsettingsjson": "{\"EnvironmentVariables\":[{\"SchemaName\":\"sample_my_var\",\"Value\":\"42\"}],\"ConnectionReferences\":[]}"
}
→ 204 No Content

The deploymentsettingsjson field is a stringified inner JSON. Schema name comes from the env-var's logical name in Dataverse; value is a string regardless of the env-var's actual type (decimal/boolean/etc — Pipeline coerces server-side).

Step 2b — PATCH: set version + notes

PATCH {pipelineHostOrgUrl}/api/data/v9.0/deploymentstageruns({runId})

{
  "artifactdevcurrentversion": "1.10.0",
  "artifactversion":           "1.11.0",
  "deploymentnotes":           "what changed"
}
→ 204 No Content

artifactversion is the new version the solution will carry after deploy. Maker UI typically auto-increments the second segment (1.10.0 → 1.11.0); we expose it as a required parameter for explicit control.

Step 3 — POST: actually start the deploy

POST {pipelineHostOrgUrl}/api/data/v9.0/DeployPackageAsync

{ "StageRunId": "<runId>" }
→ 204 No Content

The Pipeline-System workflow then takes over: solution gets exported from Dev, imported into the target stage's env. Total runtime observed: ~5–15 min depending on solution size and dependency tree.

Stage-run status codes

The stagerunstatus and operationstatus fields use a shared option-set. Always read the @OData.Community.Display.V1.FormattedValue annotation for the localized label, but know the codes for code-side logic:

CodeLabel (DE)Meaning
200000000Nicht gestartetRun row created, validation queue not yet entered
200000001Wird ausgeführtCurrently active (validation or deploy)
200000002ErfolgreichTerminal — completed without errors
200000003FehlgeschlagenTerminal — see validationresults or errormessage
200000004Abgebrochen / CancelledTerminal — user/system cancelled
200000007Überprüfung erfolgreichValidation OK, awaiting commit (steps 2+3)
200000010Bereitstellung wird ausgeführtDeploy in progress (after step 3)

operation discriminates which sub-phase:

  • 200000200 = Kein Wert (initial)
  • 200000201 = Überprüfen
  • 200000202 = Bereitstellen

Validation duration & polling

Empirically: validation completes in 5–10 min on solutions with 10–100 components, can climb past 15 min on larger ones. Our service uses a default validationTimeoutSeconds=600 (10 min) and polls every 10 s; raise both for big solutions. solution_deploy_pipeline polls server-side so the MCP call blocks until step 3 fires (or validation fails or times out).

Permission pitfall — fast diagnosis

Symptom: validation completes but validationresults shows:

SecLib::CheckPrivilege failed.
User: <systemuserid>,
PrivilegeName: prvImportCustomization

The user-GUID in the error message is the calling user on the target env. Cross-check against an admin account. The error is fatal for the run — start a new one with the admin token.

Pipeline vs. direct export/import — trade-offs

AspectPipelinesolution_export + solution_import
Audit / historyAuto-logged in deploymentstagerunManual notes only
Stage enforcement (Dev → Stage → Prod order)YesNo
Approval gatesConfigurable per stageNone
Version bumpingMandatory new artifactversionSolution version is whatever the export says
Speed for ad-hocSlow (5–15 min)Fast (1–3 min)
Works without Pipelines installedNoYes
Solution stays managed-only on targetYes by defaultConfigurable
AuthMaker-AppId token (Device Code Flow, pipeline_auth_init)Regular Dataverse token — no extra login

Default to Pipeline when staging/prod targets are involved. Use direct export/import for throwaway envs (service-test), bulk migrations, or — importantly — as the robust fallback when host-managed Pipelines misbehave (validation/auth/deploy issues).

Direct export/import — capabilities (since 2026-06-01)

  • solution_export(uniqueName, managed, filePath?) — with filePath the zip is written to local disk and only the path + byte size come back; without it the base64 is returned inline. Use filePath for large solutions to avoid pumping megabytes of base64 through the MCP channel.
  • solution_import(filePath? | zipBase64?, overwriteUnmanaged, timeoutSeconds=600) — runs the async ImportSolutionAsync action (not the timeout-prone sync ImportSolution), polls the asyncoperation until terminal, and returns Success (driven by async statuscode 30) plus ComponentErrors[] parsed from the ImportJob's data XML. Provide filePath to read the zip from disk (preferred) or zipBase64 inline.
  • Architecture note: the PAC CLI was deliberately NOT used as the engine (own auth store, external-process dependency). If deeper SDK features are ever needed, the ServiceClient SDK with tokenProviderFunction (reuses DataverseTokenProvider) is the preferred next step — not the CLI. See memory project_solution_import_export_architecture.

Environment reference values (example)

Illustrative placeholders showing the shape of a pipeline setup. All IDs are tenant-specific — resolve the real values for your own environment with pipeline_environments(...) before relying on them.

ItemValue
Pipeline-Host org URLhttps://orgexample.crm4.dynamics.com
Pipeline "Example" deploymentpipelineid10000000-0000-0000-0000-000000000001
Stage "contoso-staging" deploymentstageid20000000-0000-0000-0000-000000000002 (first stage, previous=null)
Stage "contoso-prod" (Prod) deploymentstageid20000000-0000-0000-0000-000000000003 (previous=contoso-staging)
Dev-env mapping (contoso-dev) deploymentenvironmentid30000000-0000-0000-0000-000000000004
contoso-dev Power-Platform environmentid40000000-0000-0000-0000-000000000005
Admin account with prvImportCustomizationadmin@contoso.com

The deploymentenvironmentid (pipeline-internal mapping row id) is NOT the Power-Platform env GUID. Resolve via pipeline_environments(pipelineHostOrgUrl) and filter by EnvironmentId if you only know the PP env GUID.

Typical workflows

"Deploy ContosoSales from contoso-dev → contoso-staging"

  1. Capture current solution version: mcp__dataverse-modelling-mcp__solution_get(uniqueName='ContosoSales') → version (e.g. 1.10.0).
  2. Compute target version (typically bump second segment: 1.10.0 → 1.11.0).
  3. Confirm contoso-staging write with the user (per project memory).
  4. solution_deploy_pipeline(pipelineHostOrgUrl, solutionId, artifactName='ContosoSales', devDeploymentEnvironmentId, targetStageId=<contoso-staging>, currentVersion='1.10.0', newVersion='1.11.0', deploymentNotes='<reason>', autoConfirm=true) — blocks ~6–10 min, returns stageRunId.
  5. Poll pipeline_run_status(pipelineHostOrgUrl, stageRunId) until stagerunstatus = Erfolgreich (or Fehlgeschlagen).
  6. On success: solution and its components (cloud flows, tables, etc.) are now in contoso-staging as managed.

"Validate without deploying"

Same as above but autoConfirm=false. Tool returns immediately after step 1 with the runId. Inspect pipeline_run_status until stagerunstatus = Überprüfung erfolgreich and read validationresults JSON — useful to preview which components will be imported and to catch missing dependencies before committing.

"Diagnose a failed run"

  1. pipeline_run_status(pipelineHostOrgUrl, stageRunId) → look at stagerunstatus@…FormattedValue and operationstatus@…FormattedValue.
  2. Parse validationresults JSON: SolutionValidationResults[].Message. For permission errors the user-GUID is in that string. For missing dependencies, MissingDependencies lists what's not in the target.
  3. Common causes: missing prvImportCustomization, connection references not yet present on target, dependent solutions not yet deployed, target env not "managed-environment-enabled" (Pipeline UI shows a banner about this).

"Roll back a deployed solution"

Pipelines do not offer one-click rollback. Options:

  • Trigger a new pipeline deploy with an older solutionid snapshot (requires keeping snapshots in dev).
  • Use solution layers (solution_remove_active_layer) to peel off the most recent unmanaged layer if the previous managed solution is still intact.
  • Direct import of an older managed solution file (bypasses Pipeline audit but is fastest).

Reverse-engineered endpoints (Maker UI parity)

Documented for the rare case the wrappers need extending.

CallURLMethod
List pipelines/api/data/v9.2/deploymentpipelinesGET
List stages of a pipeline/api/data/v9.2/deploymentstages?$filter=_deploymentpipelineid_value eq {id}GET
Env mapping rows/api/data/v9.2/deploymentenvironmentsGET
Create stage run + start validation/api/data/v9.0/deploymentstageruns?$select=deploymentstagerunidPOST
Set version + notes/api/data/v9.0/deploymentstageruns({runId})PATCH
Kick off actual deploy/api/data/v9.0/DeployPackageAsyncPOST
Poll a run's status/api/data/v9.0/deploymentstageruns({runId})?$select=stagerunstatus,errormessage,operation,operationdetails,operationstatus,validationresults,...GET

API-version inconsistency (v9.2 for read, v9.0 for the run-creation + deploy actions) is intentional Microsoft-side — keep both.

Pitfalls

  • Run hangs at "Nicht gestartet" forever if you only do step 1. Always follow with PATCH + DeployPackageAsync (or use autoConfirm=true). The deprecated pipelines({id})/Deploy endpoint that older MCP code used is dead; do not call it.
  • DeployPackageAsync is unbound, despite naming. Don't try /deploymentstageruns({id})/DeployPackageAsync — fails. It takes StageRunId in the body.
  • api-version=2016-11-01 is wrong. Pipelines use Dataverse Web API (/api/data/v9.0 or /api/data/v9.2), not the PA Flow API.
  • outputsLink-style retrieval doesn't apply. Stage-run details come back directly on GET — no SAS-signed URL juggling like flow run actions need.
  • A green run does not mean a changed ribbon button reaches the users. Two things can stop it, and neither shows in the run:

    • An unmanaged ribbon layer on the target overrides the managed deployment. It cannot be removed, only overwritten (ribbon_sync_unmanaged_layer).
    • The server keeps delivering the old client ribbon until the table's metadata changes (ribbon_refresh_client_metadata).

    After deploying a ribbon change, run ribbon_diagnose for the table on the target. The command-bar-buttons skill has the details.

  • 0x80071151 "Cannot start another [Import]" while Microsoft updates its own msdyn_* solutions on the environment — a chain that can run for ten minutes and more. Every import and publish is refused meanwhile; wait and retry. To see what runs, read msdyn_solutionhistories with $orderby=msdyn_starttime desc&$top=10: a filter on msdyn_starttime is silently ignored, and thousands of old rows have no msdyn_endtime, so "no end time" is no sign of a running operation.

Related memories

  • See [[feedback_environment_write_policy]] for contoso-dev vs contoso-staging/contoso-prod write confirmations.
  • See cloud-flows skill for editing the cloud-flow content (FetchXML, action inputs) before deploying.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.