deploy-pipeline

Plugin check: Run node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

deploy-pipeline

Triggers a Power Platform Pipeline deployment run. Reads the existing pipeline configuration from docs/alm/last-pipeline.json, selects a target stage, validates the solution package, and deploys it to the target environment.

Prerequisite: Run /power-pages:setup-pipeline first to create the pipeline configuration.

Refer to ${CLAUDE_PLUGIN_ROOT}/references/cicd-pipeline-patterns.md for all HAR-confirmed API patterns used in this skill.

Prerequisites

Important: The source (dev) environment must have a Power Platform Pipelines host environment configured. This is set in Power Platform Admin Center (Environments → select env → Pipelines) or via the tenant-level DefaultCustomPipelinesHostEnvForTenant setting. Without this configuration, pac pipeline deploy will fail. The setup-pipeline skill creates the pipeline definition in the host; this admin step connects the dev environment to that host.

• docs/alm/last-pipeline.json exists (created by setup-pipeline)
• .solution-manifest.json exists
• Azure CLI logged in (az account show succeeds)
• PAC CLI logged in (pac env who succeeds)

Phases

Phase 0 — ALM plan gate

plan-alm is the front door. When the user expresses an ALM intent (promote / ship / deploy / move to staging / push to prod / release this version), the orchestrator (/power-pages:plan-alm) should run first. Direct invocation of deploy-pipeline bypasses the orchestrator's pre-plan completeness check, env-var resolution per stage, activation steps, and validation runs. This gate makes that bypass explicit.

Skip rule. If this skill was invoked as part of an active plan-alm orchestration, skip Phase 0 entirely and proceed to Phase 1. The gate helper exposes this via its inExecution block — pass through silently to Phase 1 when:

inExecution.status === "active"

The helper computes this from docs/.alm-plan-data.json — PLAN_STATUS === "In Execution" AND LAST_INVOCATION_AT within the last 60 minutes. check-alm-plan.js refreshes LAST_INVOCATION_AT automatically on every invocation that finds the plan in execution, so each in-chain skill keeps the chain alive for the next one — even multi-hour deploys (deploy-pipeline alone can take 60 min per stage) survive the window without the chain incorrectly de-classifying. Stalled chains (no heartbeat for > 60 min) reclassify as stale-heartbeat and Phase 0 gates fire normally so an abandoned plan doesn't silently bypass user confirmation.

When inExecution.status is anything other than "active" ("not-running", "stale-heartbeat", "no-plan"), run the Phase 0 gate flow below. Branch on the remaining helper fields:

Step 1 — Run the gate helper.

node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/check-alm-plan.js" \
  --projectRoot "." \
  --envUrl "{devEnvUrl}" \
  --token "{token}" \
  --solutionId "{solutionId from .solution-manifest.json, if available}"

The helper returns JSON with { exists, stale, staleness: { reason, detail }, generatedAt, planStatus, ... }. The freshness check requires env credentials + solutionId; without those the helper does an existence-only check.

Step 2 — Branch on the result.

| Result | Behavior | |---|---| | deferred: true | The user has explicitly deferred ALM for this project (.alm-deferred marker present). Pass through silently to Phase 1 — do not nag. | | exists: false | The user hasn't run plan-alm yet. See Step 3. | | exists: true, stale: false | Plan is current. Pass through silently to Phase 1. | | exists: true, stale: true (reason: solution-modified) | The solution changed after the plan was generated. See Step 4. |

Step 3 — No plan. Tell the user:

"No ALM plan exists for this project. /power-pages:plan-alm builds one — it detects the project state, asks about your promotion strategy, and orchestrates this skill in the right order alongside setup-solution / setup-pipeline / activate-site / test-site. Want me to run plan-alm now?"

<!-- gate: deploy-pipeline:0.no-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · deploy-pipeline:0.no-plan): Fail-closed entry gate when check-alm-plan.js returns exists:false. Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Run /power-pages:plan-alm first? | ALM plan gate | Yes — run /power-pages:plan-alm now (Recommended), Continue without a plan (advanced — I just want to deploy), Cancel |

• Yes (Recommended) → invoke /power-pages:plan-alm. plan-alm's Phase 7 dispatches back into this skill at the appropriate stage.
• Continue without a plan → set BYPASSED_PLAN_GATE = true and proceed to Phase 1. The deploy will still work, but env-var per-stage values, activation, and post-deploy validation aren't orchestrated.
• Cancel → exit cleanly.

Step 4 — Stale plan. Tell the user:

"ALM plan exists from {generatedAt} but the source solution has been modified since (at {solution.modifiedon}). The plan's component count, size analysis, and split decisions may be outdated. Re-running plan-alm will refresh the analysis."

<!-- gate: deploy-pipeline:0.stale-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · deploy-pipeline:0.stale-plan): Fail-closed entry gate when check-alm-plan.js returns stale:true. Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Refresh the plan first? | ALM plan freshness | Refresh — re-run /power-pages:plan-alm (Recommended), Continue with the existing plan, Cancel |

• Refresh (Recommended) → invoke /power-pages:plan-alm. After completion, re-run the Phase 0 helper once to confirm freshness; if still stale, surface the detail and proceed to Phase 1 anyway (don't infinite-loop).
• Continue → set STALE_PLAN_ACK = true and proceed to Phase 1.
• Cancel → exit cleanly.

Relationship to Phase 3.5 (pre-deploy completeness check). Phase 3.5 (later in this skill) catches solution gaps right before deploy. Phase 0 catches the bigger miss: the user who never ran the orchestrator at all and is about to push a half-baked deploy through. The two are complementary.

Phase 1 — Verify Prerequisites

Create all tasks upfront at the start of this phase.

Tasks to create:

1. "Verify prerequisites"
2. "Select target stage"
3. "Resolve pipeline info"
4. "Validate package" — in MULTI_RUN_MODE this becomes a single parallel batch (Phase 3.6) covering all N non-skipped solutions; in single-solution / legacy v2 mode it runs per-iteration inline in Phase 4
5. "Configure deployment settings"
6. "Deploy and monitor"
7. "Write deployment record"

Steps:

1. Run verify-alm-prerequisites.js to confirm PAC CLI auth, acquire a token, and verify API access:

``bash node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js" --require-manifest ` Capture output as JSON; extract .envUrl (store as devEnvUrl) and .token (store as DEV_TOKEN). If the script exits non-zero, stop and surface the error — it will indicate whether az login, pac auth`, or WhoAmI failed.

1. Run detect-project-context.js to read project config and solution manifest:

``bash node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/detect-project-context.js" ` Capture output as JSON; extract .solutionManifest (store as solutionManifest), .siteName (store as siteName), and .websiteRecordId. If solutionManifest is null, continue — the manifest is not strictly required at this step (solution info will come from docs/alm/last-pipeline.json`).

1. Locate docs/alm/last-pipeline.json — if not found, stop and advise running /power-pages:setup-pipeline first.

Manifest version check:

• If schemaVersion === 3, set MULTI_RUN_MODE = true