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.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- business-process-flowsSkill
- classic-workflowsSkill
- cloud-flowsSkill
- command-bar-buttonsSkill
- form-authoringSkill
- modeling-patternsSkill
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
- Distinctive: line 64
Only sent if the solution has any mandatory EnvVars or ConnRefs on the target.
- Very specific: line 148
Default to Pipeline: when staging/prod targets are involved.
- Very specific: line 193
Use solution layers (solution_remove_active_layer) to peel off the most recent unmanaged layer if the previous managed solution is still …
- Very specific: line 214
Run hangs at "Nicht gestartet" forever: if you only do step 1. Always follow with PATCH + DeployPackageAsync (or use autoConfirm=true).
- Very specific: line 225
After deploying a ribbon change, run ribbon_diagnose for the table on the target.
≈ “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.
Files
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, anddeploymentstagerunentities 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
prvImportCustomizationon each target environment the pipeline imports into. Without it, validation itself fails — the run goes tostagerunstatus = FehlgeschlagenandvalidationresultscontainsSecLib::CheckPrivilege failed … PrivilegeName: prvImportCustomizationwith the user/BU GUID of the target env. Granting the user a Pipeline-Host group/role does NOT help — it must be a role carryingprvImportCustomization(e.g. System Customizer) on the target. Verified2026-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-devwritable without confirmation,contoso-stagingandcontoso-prodneed 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 AppIda8f7a65c-f5ba-4859-b2d6-df772c264e9d. A run created with any other appid returns HTTP 201 but stays inNicht gestartetforever (validation never starts). The problem: a headless MCP cannot mint ana8f7a65ctoken —- Device Code Flow directly with
a8f7a65c→ token redemption fails withAADSTS7000218(requires a client_secret; not a public client for device-code). - FOCI refresh-token exchange to
a8f7a65c(from Azure CLI04b07795or PAC9cee029c) →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 atNicht gestartet.
So
solution_deploy_pipeline/pipeline_auth_initare effectively non-functional for committing a deploy. The create-payload, sequence, andDeployPackageAsynccall are otherwise correct (verified call-for-call against a Maker-UI HAR capture). Recommended deployment path for MCP: the file-basedsolution_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:a8f7a65chas no manually-capturable redirect URI registered — bothhttp://localhostandhttps://login.microsoftonline.com/common/oauth2/nativeclientreturnAADSTS50011(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 ana8f7a65ctoken —solution_deploy_pipelinecannot be made to work from a headless MCP. Use file-based export/import instead.- Device Code Flow directly with
Tool map
| User intent | MCP tool |
| List pipelines on a host | pipeline_list(pipelineHostOrgUrl) |
| List stages of a pipeline | pipeline_stages(pipelineHostOrgUrl, pipelineId) |
Map Power-Platform env GUID → pipeline-internal deploymentenvironmentid | pipeline_environments(pipelineHostOrgUrl) |
| Poll a run's status | pipeline_run_status(pipelineHostOrgUrl, stageRunId) |
| Check, on the target, that a deployed ribbon change can take effect — before and after the run | ribbon_scan_unmanaged_layers, then ribbon_diagnose(table) (connected to the target) |
| Commit a deploy | No tool — removed (see below). Use solution_export + solution_import, or the Maker UI / PAC CLI. |
Note: the deploy tools
solution_deploy_pipeline,pipeline_auth_initandpipeline_auth_completewere 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-onlypipeline_*calls above are live. Thedeploymentsettingsjson/ 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 ContentThe 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 Contentartifactversion 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 ContentThe 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:
| Code | Label (DE) | Meaning |
| 200000000 | Nicht gestartet | Run row created, validation queue not yet entered |
| 200000001 | Wird ausgeführt | Currently active (validation or deploy) |
| 200000002 | Erfolgreich | Terminal — completed without errors |
| 200000003 | Fehlgeschlagen | Terminal — see validationresults or errormessage |
| 200000004 | Abgebrochen / Cancelled | Terminal — user/system cancelled |
| 200000007 | Überprüfung erfolgreich | Validation OK, awaiting commit (steps 2+3) |
| 200000010 | Bereitstellung wird ausgeführt | Deploy 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: prvImportCustomizationThe 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
| Aspect | Pipeline | solution_export + solution_import |
| Audit / history | Auto-logged in deploymentstagerun | Manual notes only |
| Stage enforcement (Dev → Stage → Prod order) | Yes | No |
| Approval gates | Configurable per stage | None |
| Version bumping | Mandatory new artifactversion | Solution version is whatever the export says |
| Speed for ad-hoc | Slow (5–15 min) | Fast (1–3 min) |
| Works without Pipelines installed | No | Yes |
| Solution stays managed-only on target | Yes by default | Configurable |
| Auth | Maker-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?)— withfilePaththe zip is written to local disk and only the path + byte size come back; without it the base64 is returned inline. UsefilePathfor large solutions to avoid pumping megabytes of base64 through the MCP channel.solution_import(filePath? | zipBase64?, overwriteUnmanaged, timeoutSeconds=600)— runs the asyncImportSolutionAsyncaction (not the timeout-prone syncImportSolution), polls theasyncoperationuntil terminal, and returnsSuccess(driven by async statuscode 30) plusComponentErrors[]parsed from the ImportJob'sdataXML. ProvidefilePathto read the zip from disk (preferred) orzipBase64inline.- 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
ServiceClientSDK withtokenProviderFunction(reusesDataverseTokenProvider) is the preferred next step — not the CLI. See memoryproject_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.
| Item | Value |
| Pipeline-Host org URL | https://orgexample.crm4.dynamics.com |
Pipeline "Example" deploymentpipelineid | 10000000-0000-0000-0000-000000000001 |
Stage "contoso-staging" deploymentstageid | 20000000-0000-0000-0000-000000000002 (first stage, previous=null) |
Stage "contoso-prod" (Prod) deploymentstageid | 20000000-0000-0000-0000-000000000003 (previous=contoso-staging) |
Dev-env mapping (contoso-dev) deploymentenvironmentid | 30000000-0000-0000-0000-000000000004 |
contoso-dev Power-Platform environmentid | 40000000-0000-0000-0000-000000000005 |
Admin account with prvImportCustomization | admin@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"
- Capture current solution version:
mcp__dataverse-modelling-mcp__solution_get(uniqueName='ContosoSales')→version(e.g.1.10.0). - Compute target version (typically bump second segment:
1.10.0 → 1.11.0). - Confirm contoso-staging write with the user (per project memory).
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, returnsstageRunId.- Poll
pipeline_run_status(pipelineHostOrgUrl, stageRunId)untilstagerunstatus = Erfolgreich(or Fehlgeschlagen). - 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"
pipeline_run_status(pipelineHostOrgUrl, stageRunId)→ look atstagerunstatus@…FormattedValueandoperationstatus@…FormattedValue.- Parse
validationresultsJSON:SolutionValidationResults[].Message. For permission errors the user-GUID is in that string. For missing dependencies,MissingDependencieslists what's not in the target. - 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
solutionidsnapshot (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.
| Call | URL | Method |
| List pipelines | /api/data/v9.2/deploymentpipelines | GET |
| List stages of a pipeline | /api/data/v9.2/deploymentstages?$filter=_deploymentpipelineid_value eq {id} | GET |
| Env mapping rows | /api/data/v9.2/deploymentenvironments | GET |
| Create stage run + start validation | /api/data/v9.0/deploymentstageruns?$select=deploymentstagerunid | POST |
| Set version + notes | /api/data/v9.0/deploymentstageruns({runId}) | PATCH |
| Kick off actual deploy | /api/data/v9.0/DeployPackageAsync | POST |
| 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 deprecatedpipelines({id})/Deployendpoint that older MCP code used is dead; do not call it. DeployPackageAsyncis unbound, despite naming. Don't try/deploymentstageruns({id})/DeployPackageAsync— fails. It takesStageRunIdin the body.api-version=2016-11-01is wrong. Pipelines use Dataverse Web API (/api/data/v9.0or/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_diagnosefor the table on the target. The command-bar-buttons skill has the details.- An unmanaged ribbon layer on the target overrides the managed deployment. It cannot be removed,
only overwritten (
0x80071151 "Cannot start another [Import]"while Microsoft updates its ownmsdyn_*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, readmsdyn_solutionhistorieswith$orderby=msdyn_starttime desc&$top=10: a filter onmsdyn_starttimeis silently ignored, and thousands of old rows have nomsdyn_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-flowsskill for editing the cloud-flow content (FetchXML, action inputs) before deploying.
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
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.

