force-link-environment

Name: force-link-environment
Author: microsoft

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".

星标

★ 440

来源

GitHub

更新于

2026-07-11

// 安全评估低风险

仅提示词，不执行代码
开源可审计
社区验证· 440

正在进行安全审计…

凭证密钥
网络外发
代码执行
数据访问
来源供应链

// 安装

复制安装指令，让 AI 自动完成配置 · 推荐新手

请帮我安装 askskill 上的 "force-link-environment" 技能：
1. 下载 https://raw.githubusercontent.com/microsoft/power-platform-skills/main/plugins/power-pages/skills/force-link-environment/SKILL.md
2. 保存为 ~/.claude/skills/force-link-environment/SKILL.md
3. 装好后重载技能，告诉我可以用了

// 下载

下载 SKILL.md机读安装清单 ↗

// 文档

Plugin check: Run node "${CLAUDE_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

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 ${CLAUDE_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 "${CLAUDE_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

…

查看完整文档 ↗

microsoft装→

$ loading_