microsoft-agent-skills / rules

---
description: "Fix and prevent Power Platform solution imports that break on connection references, environment variables and flow ownership. Use when a solution import fails or needs manual reconnection in the target environment, when flows turn themselves off after deployment, when a departing employee breaks production, or when setting up a deployment pipeline that should not need hand-holding."
alwaysApply: false
---

<!-- Generated from SKILL.md by scripts/build-harnesses.mjs. Do not edit by hand; run `npm run build`. -->
<!-- Source: skills/operate/power-platform-alm-connection-refs/SKILL.md -->
Connection reference breakage on import is the most reported ALM pain in Power
Platform. Almost all of it comes from the same root: **the solution carries a
reference to a connection that only exists in the environment it was built in**,
and nothing told the target environment what to use instead.

The re-authentication experience after import is a product limitation. The
reasons you are hitting it usually are not.

## Diagnose first

Ask which of these is happening, because the fixes differ:

- **Import succeeds, flows are off or failing.** Connection references
  resolved to nothing and the flow cannot run. The usual case.
- **Import prompts for connections every time.** No deployment settings are
  being supplied, so each import is a manual dance.
- **Worked for months, then broke.** Almost always ownership: someone left,
  changed a password, or hit an MFA prompt. The connection was personal.
- **Works in test, fails in production only.** Environment-specific
  configuration is hardcoded, or the production identity lacks something the
  test identity had.
- **Import fails outright.** Usually a missing dependency or a managed/unmanaged
  layering problem, not connections. Different conversation.

## The four causes worth fixing

### 1. Connections owned by a person

**The one that eventually bites everyone.** A flow authenticating as a named
individual is a production dependency on that person's employment, password and
MFA state. When they leave, production breaks, and it breaks at a time nobody
chose.

Deployment identities should be service principals, not people. This is the
single highest-value change and it is usually deferred because personal
connections work fine right up until they do not.

Ask directly: if the person who built this left tomorrow, what stops working?
The answer is often unwelcome and always clarifying.

### 2. No deployment settings supplied at import

Connection references and environment variables are *designed* to be bound per
environment. If you do not supply those bindings at import time, the target has
nothing to bind to and you get the manual reconnection prompt.

The fix is to supply a settings file per environment as part of the import, so
each target gets its own values without touching the solution. The Power
Platform CLI both generates and consumes these; see the CLI documentation for
current command syntax rather than trusting a command copied from a blog post,
because the flags have changed over time.

The important habit: **the settings file is per environment and belongs in
source control alongside the pipeline** - not generated by hand each time.

### 3. Environment-specific values baked into the solution

A hardcoded URL, site, list, table or key means the solution is not portable and
never will be. Every such value should be an environment variable, seeded per
environment.

Watch for the half-migration: environment variables created, but with default
values that silently work in test, so nobody notices production is using the
wrong one until it does something visible.

### 4. Unmanaged in production

Importing unmanaged into a downstream environment makes changes there
permanent and un-removable, and layering problems follow. Development
environments are unmanaged; everywhere else is managed. If production is
already unmanaged, say plainly that this is a cleanup project, not a quick fix.

## Pre-import checklist

Worth walking before promoting anything to production.

**Identity**
- Is the import running as a service principal rather than a person?
- Does that identity have access in the target environment, and to the
  connections it is expected to own?
- Is the client secret or certificate rotation tracked? Expiry is a scheduled
  outage nobody schedules.

**Bindings**
- Is there a deployment settings file for *this* target environment?
- Is every connection reference in it, and does each point at a connection that
  exists in the target?
- Is every environment variable in it, with a value that is right for this
  environment rather than inherited from a default?

**Solution hygiene**
- Managed, going to a non-development environment?
- Are all dependencies present in the target, including any the solution
  assumes rather than declares?
- Is the publisher prefix the intended one? Wrong prefixes are painful to
  correct after the fact.

**After import**
- Are the flows actually on? Import success does not mean running.
- Did anything need manual reconnection? If so, the settings file is
  incomplete, and fixing it now is what prevents this recurring next time.

## Say plainly what is a product limitation

- The **re-authentication experience** after import is genuinely awkward. You
  can automate around it with service principals and settings files; you cannot
  make it elegant.
- **Copilot Studio knowledge sources** are bound to the environment where the
  agent was created, and there is no supported way to parameterise them the way
  you would an environment variable. If someone is fighting this, tell them it
  is a known gap rather than letting them keep looking for the setting. Treat
  knowledge bindings as per-environment configuration with a documented
  post-deployment rebinding step, and revisit if Microsoft ships native
  support.
- Some connectors behave differently under a service principal than under a
  user. Where that is the case it is a connector constraint, not a
  configuration error.

## Do not

- Quote exact CLI command syntax, flags or file schema from memory. These have
  changed more than once. Describe what the step does and link the CLI
  documentation.
- Recommend re-creating the solution to fix layering. It is occasionally right
  and usually a very expensive way to avoid understanding the problem.
- Assume Azure DevOps. GitHub Actions, Power Platform Pipelines and manual
  imports are all in use, and the advice differs.
- Treat "it works now" as resolved when the connection is still personally
  owned. That is a deferred outage, and it should be named as one.

## Sources

Verified as resolving on 2026-08-18.

- Power Platform ALM overview:
  https://learn.microsoft.com/en-us/power-platform/alm/overview-alm
- Environment strategy for ALM:
  https://learn.microsoft.com/en-us/power-platform/alm/environment-strategy-alm
- Power Platform CLI, for current command syntax:
  https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction
- Creating a service principal for Power Platform:
  https://learn.microsoft.com/en-us/power-platform/admin/powerplatform-api-create-service-principal

If a link 404s, the page was probably renamed. Say you could not verify it
rather than guessing a replacement URL.