/force-link-environment

name: force-link-environment
description: >-
  Force-links a development or target environment to a Power Platform Pipelines
  host, overriding any existing association with a previous host. Use when
  creating a deploymentenvironments record fails with "this environment is
  already associated with another pipelines host", or when intentionally
  migrating an environment from one host to another (e.g., Platform Host →
  Custom Host, or between two Custom Hosts). Calls the documented
  `ManageEnvironmentStamp` Dataverse action (the API behind the "Force Link"
  button in the Deployment Pipeline Configuration app). DESTRUCTIVE to the
  previous host: makers lose access to any pipelines in that host that used
  this environment. Reversible by running Force Link from the previous host.
  Use when asked to: "force link environment", "force-link to new host",
  "switch pipelines host", "environment already associated with another host",
  "take over pipelines association", "relink environment to host".
user-invocable: true
argument-hint: "Optional: '--host <url>' to skip the host resolution step; '--dev-env <bapEnvId>' to skip the dev env prompt. With both flags supplied, the skill still pauses for destructive-action confirmation."
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, AskUserQuestion, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
model: opus

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

force-link-environment

Move a dev or target environment's Power Platform Pipelines host association from one host to another. This is the documented remediation when `deploymentenvironments` create fails with *"this environment is already associated with another pipelines host"*, and also the right tool when intentionally migrating environments between hosts.

**Microsoft Learn (ground truth):** [Using Force Link to associate an environment with a new host](https://learn.microsoft.com/en-us/power-platform/alm/custom-host-pipelines#using-force-link-to-associate-an-environment-with-a-new-host)

What this skill changes

In the **target host** (the new host the user wants to use):

• Marks the existing `deploymentenvironments` record as the active stamp for the BAP environment.
• Re-runs validation; on success, `validationstatus` flips to `Succeeded` (200000001).

In the **previous host** (the host the env was previously linked to):

• The corresponding `deploymentenvironments` row is **delinked**. Its `validationstatus` is left stale until refreshed in the previous host's UI.
• Makers who could run pipelines through that environment in the previous host **lose access** to those pipelines via this environment.

The action is reversible by running Force Link again from the previous host.

Phase 1.5 — Microsoft Learn grounding (required)

Before any Dataverse call, refresh the agent's grounding by fetching the doc above via `mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch`. If the doc has updated behaviors (e.g., new permission requirements, new warning text), surface them to the user before continuing. See `${PLUGIN_ROOT}/references/alm-docs-grounding.md` for the shared pattern.

Phases

| # | Phase | Output | |---|---|---| | 1 | Prerequisites | Azure CLI token for the host environment; PAC CLI authenticated | | 1.5 | MCP Learn grounding | Confirmed current behavior of Force Link / `ManageEnvironmentStamp` | | 2 | Identify host + dev env | `hostEnvUrl`, target host's `deploymentEnvironmentId`, source BAP env GUID | | 3 | Resolve `deploymentenvironments` record | Either an existing record on the new host, or a freshly created one | | 4 | Confirm destructive action | Explicit user consent via `AskUserQuestion` | | 5 | Execute Force Link | 204 from `ManageEnvironmentStamp` + post-validation Succeeded | | 6 | Write marker + summary | `docs/alm/last-force-link.json` + human-readable summary |

Create all tasks at Phase 1 start with `TaskCreate`. Mark each `in_progress` when starting and `completed` when done.

---

Phase 1 — Prerequisites

Reuse the shared verifier:

node "${PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js"

Specifically required:

• **PAC CLI auth** — `pac env who` must report an authenticated environment (for `--dev-env` auto-discovery).
• **Azure CLI auth** — `az account show` succeeds.
• **Host-scoped token** — the caller must have Deployment Pipeline Administrator on the target host (the host the env is being linked TO). Without it, `ManageEnvironmentStamp` returns 403.

Fetch the host token from Azure CLI using the host's Dataverse URL as the resource. Reuse `getAuthToken` from `scripts/lib/validation-helpers.js`.

Phase 1.5 — MCP Learn grounding

Call:

mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch(url=
  "https://learn.microsoft.com/en-us/power-platform/alm/custom-host-pipelines")

Confirm the *"Using Force Link…"* section's current warnings before proceeding. If the section now mentions new prerequisites or rollback constraints not covered in this skill, surface them to the user.

Phase 2 — Identify host + dev env

<!-- gate: force-link-environment:2.host-url | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · force-link-environment:2.host-url):** Pick the target host environment URL when arg / marker resolution paths all came up empty. Fires only on the "no `--host` arg, no `last-host-check.json`, no `last-pipeline.json`" branch (step 4 below). > > **Trigger:** Phase 2 resolution order steps 1–3 all returned no value. > **Why we ask:** Auto-picking the wrong host runs `ManageEnvironmentStamp` against the wrong tenant and moves the stamp irreversibly without consent. > **Cancel leaves:** Nothing — no API call yet.

<!-- gate: force-link-environment:2.dev-env | category=plan | cancel-