Force Link Environment

What the source does

• FilesystemUndeclared2 observations, not in its own description
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

} = require('../../../scripts/lib/validation-helpers');

const { almPath } = require('../../../scripts/lib/alm-paths');

Audit 0.4.1 · source sha 8075ef5705c5 · 18 Oct 2026Report an issue or request a re-scan

• Publishermicrosoft GitHub organizationOwner of the repository this skill is read from
• Source foldermicrosoft/power-platform-skills/plugins/power-pages/skills/force-link-environmentThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict8075ef5705c5A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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:

```bash
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

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/microsoft/power-platform-skills
git -C power-platform-skills checkout 8075ef5705c5

Works in

1. 2026-10-18
   ✓SAFE B 89 / 100

   first audit · source 8075ef5705c5

Questions about Force Link Environment

• github.com/microsoft/power-platform-skills/tree/main/plugins/pow — the audited source at commit 8075ef5705c5 and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology