Portal Walkthrough: Force-Link Environments¶

This guide provides step-by-step UI procedures for force-linking environments to your designated pipelines host. These steps cannot be automated - they require manual admin interaction in the Power Platform admin center and Deployment Pipeline Configuration app.

Overview¶

Force-linking an environment: - Removes the environment from its current pipelines host (if any) - Associates it with your designated pipelines host - Enables pipelines created in your host to target this environment - Makers lose access to pipelines configured in the previous host

Prerequisites¶

Before starting, ensure you have:

Power Platform Admin role or Deployment Pipeline Administrator role
Access to your designated pipelines host environment
Power Platform Pipelines app installed on the host
Target environment ID (GUID) to force-link
Documentation of current pipeline ownership (for communication)
Target environment is a Managed Environment - Pipeline targets must be Managed Environments

Important: Starting February 2026, Microsoft requires all pipeline target environments to be Managed Environments. If your target environment is not managed, enable it in Power Platform Admin Center before force-linking. See Microsoft Learn: Managed Environments.

Part 0: Identify Your Pipelines Host Environment¶

Before Force Linking environments, determine what type of host you're using.

Step 0.1: Check Dynamics 365 Apps List¶

Navigate to admin.powerplatform.microsoft.com
Select your suspected host environment
Click Resources > Dynamics 365 apps
Look for "Power Platform Pipelines" (exact app name)

Decision tree: - If "Power Platform Pipelines" appears as Installed → You have a custom host. Proceed to Part 1. - If NOT listed (not installed, not available) → You may be using the platform host. Continue to Step 0.2.

Step 0.2: Verify via Pipelines Page¶

Go to make.powerapps.com
Open any solution in a development environment
Click Pipelines > Manage pipelines
Note the behavior:
Embedded app opens within Power Apps → Using platform host (infrastructure-managed)
Opens dedicated Deployment Pipeline Configuration app → Using custom host

Step 0.3: If Using Platform Host¶

If you determine you're using the platform host and need full governance control:

Choose an environment to become your custom host (must be Managed Environment)
Install "Power Platform Pipelines" app via Resources > Dynamics 365 apps > Install app
Configure the custom host per Microsoft Learn
Force Link all environments to your new custom host (Parts 1-5 of this guide)
Optionally set as default via Set a default pipelines host

Note: Existing pipelines in the platform host will NOT automatically migrate. Users must recreate their pipelines in the new custom host. Makers lose access to pipelines in the previous host when you Force Link their development environment.

Decision Tree: Which Scenario Are You In?¶

Use this table to identify your current state and determine the appropriate action:

Symptom	Scenario	Recommended Action
No "Power Platform Pipelines" app visible in any environment	Platform host only	Create custom host → Set as default → Link all environments
App visible in ONE environment only	Single custom host exists	Verify it's your designated host → Link remaining environments
App visible in MULTIPLE environments	Multiple custom hosts exist	Inventory all hosts → Consolidate to one → Force Link environments from others
App visible AND pipelines exist in platform host	Mixed state (custom + platform)	Create/designate custom host → Force Link all environments
No pipelines anywhere (verified via `pac pipeline list`)	Greenfield (clean state)	Create custom host → Set as default → See README.md Greenfield section

FSI Recommendation¶

For U.S. Financial Services organizations, a custom host is required for governance and compliance. The platform host:

Cannot be governed directly by your organization
Has limited administrative controls
Does not support role-based access restrictions for pipeline creation
Does not provide visibility into pipeline configurations

Always migrate to a custom host you control. See Migration Guide for brownfield migration guidance.

Which Environments to Force Link¶

Environment Type	Should Force Link?	Priority
Production (target)	Yes	1 - Highest
UAT/QA (target)	Yes	2
Development (where makers build)	Yes	3
Sandbox (general purpose)	Yes	4
Trial environments	Optional	5 - Lowest
Default environment	No - Cannot be Force Linked	N/A
The custom host itself	No - It IS the host	N/A

Part 1: Verify Pipelines Host Setup¶

Before force-linking environments, confirm your pipelines host is properly configured.

Step 1.1: Access Power Platform Admin Center¶

Navigate to admin.powerplatform.microsoft.com
Sign in with your admin credentials
Select Environments from the left navigation

Step 1.2: Locate Your Pipelines Host¶

Find your designated pipelines host environment in the list
Click the environment name to open details
Verify:
Type is Production or Sandbox (not Developer)
Managed shows as "Yes"
Dataverse database is provisioned

Step 1.3: Verify Pipelines App Installation¶

With your host environment selected, click Resources
Click Dynamics 365 apps
Look for Power Platform Pipelines
Status should be Installed

If not installed: 1. Click Install app 2. Search for "Power Platform Pipelines" 3. Select and install 4. Wait for installation to complete (may take several minutes)

Step 1.4: Open Deployment Pipeline Configuration App¶

Click Open next to Power Platform Pipelines, OR
Navigate directly to: https://[your-host-env].crm.dynamics.com/main.aspx?appid=[app-guid]
You should see the Deployment Pipeline Configuration model-driven app
Verify you have access to:
Pipelines - View existing pipelines
Environments - Manage linked environments
Stages - Configure deployment stages

Part 2: Identify Environment's Current Pipeline Status¶

Before force-linking, understand the environment's current state.

Step 2.1: Check if Environment Has Pipelines Enabled¶

In Power Platform Admin Center, select the target environment
Click Resources > Dynamics 365 apps
Look for Power Platform Pipelines

Status	Meaning
Not listed	Environment has never been linked to a pipelines host
Installed	Environment may have its own pipelines OR is linked to a host

Step 2.2: Determine Current Host (if any)¶

If the environment shows Pipelines installed:

Open the environment's URL in a browser
Navigate to Settings > Advanced Settings
Look for Deployment Pipeline Configuration app
If present, this environment may BE a pipelines host
Check for existing pipelines targeting other environments

Note: There is no direct way to see which host an environment is currently linked to from the target environment. You must check from potential host environments.

Step 2.3: Check From Your Designated Host¶

Open Deployment Pipeline Configuration on your designated host
Click Environments in the left navigation
Search for the target environment name or ID
If listed with status Active, it's already linked to your host
If not listed, proceed to force-link

Part 3: Force-Link an Environment¶

Scenario A: Environment Not Currently Linked¶

Use this when the target environment has never been linked to any pipelines host.

Step 3A.1: Navigate to Environments¶

Open Deployment Pipeline Configuration app on your designated host
Click Environments in the left navigation
You'll see a list of currently linked environments

Step 3A.2: Add New Environment¶

Click + New in the command bar
In the New Deployment Environment form:

Field	Value
Name	Friendly name (e.g., "Sales Team Dev")
Environment Id	Paste the target environment GUID
Environment Type	Select appropriate type

Click Save

Step 3A.3: Verify Link¶

The environment should appear in your Environments list
Status should be Active
Test by creating a pipeline targeting this environment

Scenario B: Environment Already Linked to Another Host¶

Use this when the target environment is currently linked to a different pipelines host. This is the "force-link" scenario.

Step 3B.1: Navigate to Environments¶

Open Deployment Pipeline Configuration app on your designated host
Click Environments in the left navigation

Step 3B.2: Attempt to Add Environment¶

Click + New in the command bar
Enter the environment details:

Field	Value
Name	Friendly name
Environment Id	Target environment GUID

Click Save

Step 3B.3: Handle "Already Associated" Error¶

If you see the error:

"This environment is already associated with another pipelines host"

This indicates the environment is linked to a different host. To proceed:

Communicate with current owner (recommended)
Notify makers who use the current host
Provide migration timeline
Document acknowledgment
Proceed with force-link:
The Force Link button will appear in the command bar after the "already associated" error is triggered
Click Force Link
Confirm the action when prompted

Warning: Force-linking immediately removes the environment from the previous host. Makers using pipelines in that host will lose the ability to deploy to this environment.

Step 3B.4: Confirm Force-Link¶

A confirmation dialog will appear:

"This will remove the environment from its current pipelines host. Continue?"
Click Confirm or Yes
Wait for the operation to complete
The environment should now appear in your Environments list

Step 3B.5: Verify New Link¶

Refresh the Environments list
Find the target environment
Status should be Active
Create a test pipeline targeting this environment to confirm

Part 4: Post-Force-Link Actions¶

Step 4.1: Document the Change¶

Record in your tracking spreadsheet or Dataverse table:

Field	Value
Environment ID	Target environment GUID
Environment Name	Display name
Previous Host	Name/ID of previous host (if known)
New Host	Your designated host ID
Force-Link Date	Today's date
Performed By	Your name/email
Reason	Governance consolidation

Step 4.2: Notify Affected Users¶

Send notification to previous pipeline users:

Subject: Environment [Name] Pipeline Access Changed

Body:

The environment [Environment Name] has been consolidated to the corporate
pipelines host as part of our ALM governance initiative.

What changed:
- Pipelines you created in your personal host can no longer deploy to this environment
- New pipelines must be created in the corporate pipelines host

To continue using pipelines:
1. Request access to the corporate pipelines host
2. Recreate your pipeline configurations
3. Contact Platform Ops if you need assistance

Questions? Contact platform-ops@example.com

Step 4.3: Update Compliance Tracking¶

If using a PipelineCleanupLog table:

Find the record for this environment
Update:
Status = "ForceLinked"
Notes = "Force-linked on [date] by [admin]"

Part 5: Bulk Force-Link Process¶

When force-linking many environments, follow this structured approach.

Step 5.1: Prepare Environment List¶

Create a spreadsheet with:

Environment ID	Environment Name	Owner	Notification Sent	Force-Link Date	Status
guid-1	Sales Dev	user@co.com	2026-01-15	2026-02-15	Pending
guid-2	HR Test	user2@co.com	2026-01-15	2026-02-15	Pending

Step 5.2: Process Environments¶

For each environment:

Open Deployment Pipeline Configuration
Click Environments > + New
Enter Environment ID from your list
Click Save (or Force Link if needed)
Update spreadsheet: Status = "ForceLinked"
Repeat for next environment

Tip: Keep the app open in one browser tab and your spreadsheet in another for efficiency.

Step 5.3: Verify All Links¶

After processing all environments:

Refresh the Environments list
Verify all target environments appear
Check Status = Active for each
Run a test pipeline to one environment to confirm functionality

Troubleshooting¶

Error: "Insufficient privileges"¶

Cause: Missing Deployment Pipeline Administrator role

Solution: 1. Go to Power Platform Admin Center 2. Select the pipelines host environment 3. Click Users > Manage users in Dynamics 365 4. Find your user 5. Assign Deployment Pipeline Administrator security role

Error: "Environment not found"¶

Cause: Invalid environment ID or environment deleted

Solution: 1. Verify the environment ID in admin center 2. Ensure environment exists and is active 3. Check for typos in the GUID

Error: "Force Link button not visible"¶

Cause: May not be available in older versions

Solution: 1. Ensure Power Platform Pipelines app is updated 2. Try the operation from a different browser 3. Contact Microsoft Support if persists

Error: "Operation timed out"¶

Cause: Network issues or service degradation

Solution: 1. Wait and retry 2. Check Power Platform status 3. Try during off-peak hours

Environment still shows old host after force-link¶

Cause: Caching or propagation delay

Solution: 1. Wait 15-30 minutes 2. Refresh the browser 3. Clear browser cache 4. If persists after 1 hour, contact support

Quick Reference¶

Admin Center URLs¶

Resource	URL
Power Platform Admin Center	https://admin.powerplatform.microsoft.com
Power Apps Maker Portal	https://make.powerapps.com
Environment Details	Admin Center > Environments > [Select environment]

Key Actions¶

Action	Location
Install Pipelines app	Environment > Resources > Dynamics 365 apps > Install
Open Pipeline Config	Environment > Resources > Dynamics 365 apps > Open
Add environment	Deployment Pipeline Configuration > Environments > + New
Force-link	Deployment Pipeline Configuration > Environments > New > Force Link

Required GUIDs¶

Keep a reference of: - Your designated pipelines host environment ID - Target environment IDs to force-link - Your user ID (for audit trail)

Part 6: Reversing a Force-Link (Rollback)¶

If you need to move an environment to a different pipelines host after it has been force-linked.

When to Use¶

Force-link was applied to wrong environment
Business requirement changed requiring different host
Testing/troubleshooting requires host change
Team reorganization requires moving to different host

Understanding Rollback¶

There is no "unlink" operation. To reverse a force-link, you must force-link the environment to a different pipelines host. The environment can only be linked to ONE host at a time.

Procedure¶

Open Deployment Pipeline Configuration app in the NEW target host (not the current host)
Navigate to Environments in the left navigation
Click + New to add the environment
Enter the environment details (Name, Environment ID)
Click Save
If prompted with "already associated" error, click Force Link
Confirm the action when prompted

Impact of Rollback¶

Impact	Description
Immediate	Breaks deployments from the previous host
Pipeline access	Pipelines in previous host can no longer deploy to this environment
Maker notification	Pipeline owners in previous host should be notified
No data loss	Solutions in the environment are not affected

Important Notes¶

Force-linking is always manual (no API or CLI support)
Coordinate with pipeline owners in BOTH hosts before executing
Document the change for audit trail
Test deployment from new host after rollback

Rollback Tracking¶

Update your tracking spreadsheet with rollback details:

Field	Value
Environment ID	Target environment GUID
Previous Host	Host environment being abandoned
New Host	New host environment ID
Rollback Date	Today's date
Reason	Business justification
Performed By	Admin name/email

Part 7: Managing Pipeline Creator Access¶

To restrict makers from creating personal pipeline hosts, configure the "Deployment pipeline default" role in your custom host.

When to Use This¶

After setting your custom host as the tenant default
When you want to control who can create new pipelines
As part of initial governance configuration (greenfield or brownfield)

Step 7.1: Access Security Roles¶

Open Power Platform Admin Center
Select your custom host environment
Click Settings (gear icon in the header)
Navigate to Users + permissions > Security roles

Step 7.2: Locate the Deployment Pipeline Roles¶

Review these pipeline-related security roles:

Role	Purpose	Default Assignment
Deployment Pipeline Administrator	Full pipeline management	Environment admins
Deployment Pipeline User	Run deployments, view pipelines	Environment makers
Deployment pipeline default	Create pipelines when host is set as default	All users (by default)

Step 7.3: Modify Role Assignment¶

To restrict who can create pipelines:

Click on Deployment pipeline default role
Click Members tab
Remove users or teams that should not create pipelines
Add only approved users/teams who need pipeline creation rights

Alternative: Assign the role to an empty team, effectively disabling it for all users.

What This Controls¶

Action	Controlled by Role?
Create new pipeline in your custom host	Yes - requires Deployment pipeline default role
Run existing pipeline	No - controlled by Deployment Pipeline User role
Create personal host in another environment	No - users with Environment Admin can still install the app

Important Limitations¶

Restricting the "Deployment pipeline default" role only affects pipeline creation when your custom host is set as the tenant default. Users with environment admin rights can still:

Install the Power Platform Pipelines app in other environments
Create their own custom host environments
Configure pipelines in those environments

Full prevention requires: 1. Setting your custom host as tenant default 2. Restricting the "Deployment pipeline default" role (this section) 3. Force-linking all environments to your host (prevents deployment to/from other hosts)

See Limitations Section 6 for details on these boundaries.