debug-agent

Debug Agent

Diagnose a pipeline failure or customer issue end-to-end. Accepts a log file path, pasted error text, ADO work item ID, or GitHub issue URL. Determines ownership, resolves if PPBT-owned, or produces a precise triage package for the right team.

Invoke as: /debug-agent <log-file-path | error-text | issue-url | ado-id>

Works autonomously through all steps. One exception: pauses to request pipeline logs if they are referenced in an ICM/work item but not yet provided — log evidence is required before classifying the failure layer.

---

Step 0 — Ingest the input

Determine input type:

• File path (.txt, .log, or similar): read it with the Read tool
• ADO work item (dev.azure.com/... URL or bare integer): az boards work-item show --id <id> 2>&1
• GitHub issue (github.com/.../issues/<n>): gh issue view <n> --comments 2>&1
• Pasted text: use as-is

Extract and print:

Input summary:
- Type: <file | ado | github | text>
- Task/tool identified: <name from log header, or "unknown">
- Error snippet: <first clear error line, or "none found">
- Timestamp range: <start → end>
- Deployment result: <SUCCESS | FAILED | unknown>

Step 0b — Check for missing logs

If input is an ICM or ADO work item AND any of the following are true:

• Custom field LogsAttached = "Yes"
• Description mentions "logs attached" or "see attachment"
• Issue cannot be diagnosed from text alone (no error snippet, no pac CLI output visible)

AND no log file path or log content was provided by the user:

→ STOP. Prompt the user:

Pipeline logs are attached to this ICM/work item but aren't accessible via API.
Please download the logs from the portal and provide the folder path.
Example: C:\Users\<you>\Downloads\

Once you share the path, I'll read the logs and continue the analysis from Step 1.

Do not proceed to Step 1 until log content is available. Do NOT classify the failure layer, assign ownership, or draw conclusions based solely on the ICM title or description — log evidence is mandatory. If the user confirms no logs exist or they are unavailable, continue with Confidence: low noted throughout.

---

Step 1 — Verify PPBT is involved

ADO (Azure DevOps) — PPBT task identifiers

Every PPBT v2 task follows the pattern: microsoft-IsvExpTools.PowerPlatform-BuildTools.<task-id>.<TaskClass>@2

Display Name	Task ID (in YAML/log)	Task Class
Power Platform Tool Installer	tool-installer	PowerPlatformToolInstaller@2
Power Platform WhoAmI	whoami	PowerPlatformWhoAmi@2
Power Platform Checker	checker	PowerPlatformChecker@2
Power Platform Import Solution	import-solution	PowerPlatformImportSolution@2
Power Platform Export Solution	export-solution	PowerPlatformExportSolution@2
Power Platform Unpack Solution	unpack-solution	PowerPlatformUnpackSolution@2
Power Platform Pack Solution	pack-solution	PowerPlatformPackSolution@2
Power Platform Delete Solution	delete-solution	PowerPlatformDeleteSolution@2
Power Platform Add Solution Component	add-solution-component	PowerPlatformAddSolutionComponent@2
Power Platform Apply Solution Upgrade	apply-solution-upgrade	PowerPlatformApplySolutionUpgrade@2
Power Platform Publish Customizations	publish-customizations	PowerPlatformPublishCustomizations@2
Power Platform Set Solution Version	set-solution-version	PowerPlatformSetSolutionVersion@2
Power Platform Set Connection Variables	set-connection-variables	PowerPlatformSetConnectionVariables@2
Power Platform Deploy Package	deploy-package	PowerPlatformDeployPackage@2
Power Platform Create Environment	create-environment	PowerPlatformCreateEnvironment@2
Power Platform Delete Environment	delete-environment	PowerPlatformDeleteEnvironment@2
Power Platform Assign User	assign-user	PowerPlatformAssignUser@2
Power Platform Reset Environment	reset-environment	PowerPlatformResetEnvironment@2
Power Platform Backup Environment	backup-environment	PowerPlatformBackupEnvironment@2
Power Platform Copy Environment	copy-environment	PowerPlatformCopyEnvironment@2
Power Platform Restore Environment	restore-environment	PowerPlatformRestoreEnvironment@2
Export Dataverse Data	export-data	PowerPlatformExportData@2
Import Dataverse Data	import-data	PowerPlatformImportData@2
Power Platform Download PAPortal	download-paportal	PowerPlatformDownloadPaportal@2
Power Platform Upload PAPortal	upload-paportal	PowerPlatformUploadPaportal@2

PPBT signals (any one is sufficient):

• Task class matches any entry in the table above
• Author is Microsoft (not Wael Hamze or other community authors)
• Log contains POWERPLATFORMTOOLS_PACCLIPATH or PP_TOOLS_AUTOMATION_AGENT
• pac CLI invoked: lines containing pac solution, pac auth, pac env, pac admin, pac package
• BuildTools.EnvironmentUrl pipeline variable present

GitHub Actions — PPBT action identifiers

All PPBT GitHub Actions use: microsoft/powerplatform-actions/<action-name>@v1

Action	uses: value
Install Power Platform Tools	microsoft/powerplatform-actions/actions-install@v1
WhoAmI	microsoft/powerplatform-actions/whoAmI@v1
Import Solution	microsoft/powerplatform-actions/import-solution@v1
Export Solution	microsoft/powerplatform-actions/export-solution@v1
Unpack Solution	microsoft/powerplatform-actions/unpack-solution@v1
Pack Solution	microsoft/powerplatform-actions/pack-solution@v1
Publish Customizations	microsoft/powerplatform-actions/publish-solution@v1
Clone Solution	microsoft/powerplatform-actions/clone-solution@v1
Check Solution	microsoft/powerplatform-actions/check-solution@v1
Upgrade Solution	microsoft/powerplatform-actions/upgrade-solution@v1
Deploy Package	microsoft/powerplatform-actions/deploy-package@v1
Upload PAPortal	microsoft/powerplatform-actions/upload-paportal@v1
Catalog Install	microsoft/powerplatform-actions/install@v1
Catalog Submit	microsoft/powerplatform-actions/submit@v1
Catalog Status	microsoft/powerplatform-actions/status@v1

Not-PPBT signals — deflect immediately:

• Author: Wael Hamze → CRM Build Tools (community)
• Microsoft.Xrm.Tooling.* PowerShell → old XRM Tooling
• PackageDeployer PowerShell task (v12.x) → Wael Hamze legacy tooling
• Task version @v1 and no microsoft/powerplatform-actions prefix → unrelated action

If not PPBT: skip to Step 5 (non-PPBT triage) immediately.

---

Step 2 — Identify the failing task and classify the layer

2a — Map the failing task to its inputs

Use the tables below to check whether required inputs are present in the log or YAML.

Helper tasks

Tool Installer (tool-installer) — must be FIRST task in every pipeline/workflow

• No required inputs beyond defaults
• Critical: if missing → all other tasks fail with "pac.exe not found" or POWERPLATFORMTOOLS_PACCLIPATH not set
• Optional: AddToolsToPath: true (adds pac to PATH for script tasks)

WhoAmI (whoami / whoAmI)

• Required: authenticationType + one of PowerPlatformEnvironment or PowerPlatformSPN
• GitHub: environment-url + auth credentials (user-name/password-secret OR app-id/client-secret/tenant-id)
• Use: connectivity check early in pipeline — failure here = auth or network issue, not solution issue

Quality check

Checker (checker / check-solution)

• Required: PowerPlatformSPN (SPN only — username/password NOT supported for checker)
• Required: RuleSet GUID
• Optional: UseDefaultPACheckerEndpoint (default true) — if false, must set CustomPACheckerEndpoint
• Output: SARIF file as pipeline artifact (ArtifactDestinationName)
• Common issue: checker fails for username/password connections — SPN required

Solution tasks

Import Solution (import-solution)

• Required: service connection + SolutionInputFile
• Key options: AsyncOperation: true (recommended for large solutions — avoids 4-min timeout), HoldingSolution (for upgrade pattern), UseDeploymentSettingsFile (for connection references + env vars)
• Common issue: sync import times out on large solutions → set AsyncOperation: true, MaxAsyncWaitTime: 60
• Common issue: connection references not set → use DeploymentSettingsFile

Export Solution (export-solution)

• Required: service connection + SolutionName + SolutionOutputFile
• Note: use solution Name not Display Name
• Managed: true exports as managed

Apply Solution Upgrade (apply-solution-upgrade)

• Required: service connection + SolutionName
• Use after Import with HoldingSolution: true

Pack / Unpack Solution — local operations, no service connection needed

• SolutionType: Managed | Unmanaged | Both

Set Solution Version (set-solution-version)

• Required: service connection + SolutionName + SolutionVersionNumber
• Tip: use $(Build.BuildId) as version number

Set Connection Variables (set-connection-variables)

• Sets pipeline variables: BuildTools.TenantId, BuildTools.ApplicationId, BuildTools.ClientSecret, BuildTools.DataverseConnectionString
• Username/password auth also requires ApplicationId and RedirectUri

Deploy Package (deploy-package)

• Required: service connection + PackageFile (.dll)
• GitHub Actions: Windows runner only (runs-on: windows-latest)

Environment management tasks

Create Environment (create-environment)

• Required: DisplayName, LocationName, EnvironmentSku, CurrencyName, LanguageName, DomainName
• Side effect: sets BuildTools.EnvironmentUrl pipeline variable — subsequent tasks use this automatically
• Note: BuildTools.EnvironmentUrl overrides any service connection URL for downstream tasks

Copy Environment (copy-environment)

• Required: TargetEnvironmentUrl
• CopyType: FullCopy (data + metadata) or MinimalCopy (metadata only)

Restore Environment (restore-environment)

• RestoreLatestBackup: true OR provide RestoreTimeStamp in mm/dd/yyyy hh:mm format

Export/Import Dataverse Data

• Schema file created via Configuration Migration tool
• Import accepts zip file or folder with data-schema.xml + data.xml

Power Pages tasks

• download-paportal / upload-paportal: requires WebsiteId GUID, optional ModelVersion (1=standard, 2=enhanced data model)

2b — When is it a PPBT bug (this repo)?

PPBT owns exactly the boundary between the ADO/GitHub pipeline and cli-wrapper. A bug is PPBT's if the wrong value reaches cli-wrapper or no value reaches cli-wrapper when the user configured the pipeline correctly.

PPBT owns it — fix in this repo — when:

Symptom	Root cause	File to fix
Task input exists in task.json but is silently ignored / not passed to pac	index.ts doesn't read it via parameterMap	src/tasks/<name>/index.ts
Task input works on Windows but breaks on Linux (path, binary location)	CliLocator.ts platform logic	src/host/CliLocator.ts
Wrong cloud instance sent to pac for a valid service connection	resolveCloudInstance() missing a cloud mapping	src/params/auth/getCredentials.ts
BuildTools.EnvironmentUrl not set after create-environment runs	index.ts not calling tl.setVariable	src/tasks/create-environment/index.ts
Service connection field (e.g. tenantId) extracted as null/undefined	getCredentials.ts reading wrong endpoint field	src/params/auth/getCredentials.ts
Environment URL fallback chain skips a valid source	getEnvironmentUrl.ts fallback order wrong	src/params/auth/getEnvironmentUrl.ts
Tasks appear in wrong pipeline stage / wrong task GUIDs	GUID substitution bug in pack step	gulp/pack.mjs, extension/task-metadata.json
Tool installer fails to download pac or set POWERPLATFORMTOOLS_PACCLIPATH	Installer task logic	src/tasks/tool-installer/index.ts
New task input added to task.json but not wired through to pac	index.ts parameterMap not updated	src/tasks/<name>/index.ts
Task breaks after cli-wrapper version bump (interface mismatch)	BuildToolsHost or BuildToolsRunnerParams out of sync	src/host/BuildToolsHost.ts, src/host/BuildToolsRunnerParams.ts
Error message from task is unhelpful / missing context	Better error surfacing needed	src/tasks/<name>/index.ts

PPBT does NOT own it — do not fix in this repo — when:

Symptom	Actual owner
User forgot to add tool-installer to pipeline	User/pipeline config — document the fix, no code change
User passed solution display name instead of unique name	User error
cli-wrapper assembles wrong pac args (but PPBT passed the right values to it)	cli-wrapper repo
pac CLI crashes or returns a wrong result	pac CLI / admin-tools
Dataverse operation fails (solution import engine, HTTP 5xx)	CDS / Solution Framework
Auth fails because service connection credentials are wrong/expired	User / service connection admin
MFA required on username/password connection	User — must switch to SPN

The test: ask "If the user configured the pipeline exactly right, would this still fail?" If yes → PPBT bug. If no → user error or downstream team.

2c — Classify the failure layer

Azure DevOps / GitHub Actions pipeline
  → [L1] user/pipeline config error (task ordering, missing inputs, wrong auth type)
  → [L2] PPBT code bug  (src/tasks/<name>/index.ts, getCredentials.ts, CliLocator.ts, etc.)
  → [L3] cli-wrapper bug  (@microsoft/powerplatform-cli-wrapper/dist/actions/)
  → [L4] pac CLI binary  (pac.exe / pac)
       └─ [L4-admin]  pac env/admin commands → admin-tools team
       └─ [L4-pac]    pac CLI crash / .NET exception → pac CLI team
       └─ [L4→L5]     pac correctly relays Dataverse error → CDS team
  → [L5] Power Platform API  (Dataverse / crm.dynamics.com)

Symptom	Layer	Owner
pac.exe not found / POWERPLATFORMTOOLS_PACCLIPATH not set	L1	User — tool-installer step missing
BuildTools.EnvironmentUrl targets wrong env	L1	User — task ordering side effect
Required input missing because user left it blank	L1	User — pipeline config
Checker fails with username/password	L1	User — SPN required for checker
Import times out (~4 min) on large solution	L1	User — set AsyncOperation: true
Input exists in task.json but is ignored / not passed to pac	L2	PPBT bug — index.ts parameterMap
resolveCloudInstance() returns wrong cloud for valid endpoint	L2	PPBT bug — getCredentials.ts
Service connection field extracted as null despite being set	L2	PPBT bug — getCredentials.ts
BuildTools.EnvironmentUrl not set after create-environment	L2	PPBT bug — index.ts missing setVariable
Task breaks on Linux but works on Windows	L2	PPBT bug — CliLocator.ts
Wrong task GUIDs / tasks conflict in marketplace	L2	PPBT bug — pack.mjs / task-metadata.json
auth create failed after correct args passed	L3	cli-wrapper auth bug
Cannot resolve AAD authority / wrong AAD endpoint	L3	cli-wrapper resolveCloudInstance()
WhoAmI fails on non-English agent	L3	cli-wrapper (known ADO #4846644)
pac CLI crashes / .NET exception inside pac	L4-pac	pac CLI team
pac env create/delete/backup/restore/copy fails	L4-admin	admin-tools team
pac admin * command fails	L4-admin	admin-tools team
pac auth create crashes after correct args	L4-pac	pac CLI team
pac solution import/export/publish + Dataverse HTTP error	L4→L5	CDS / Solution Framework
pac solution check / checker API error	L4→L5	Power Apps Checker team
pac package deploy + Dataverse-side error	L4→L5	CDS / Solution Framework
HTTP 4xx/5xx from crm.dynamics.com	L5	CDS / Solution Framework
Solution component errors / missing dependencies	L5	CDS / Solution Framework
PVA component import failure	L5	pac CLI team (known IcM 604312672)

2d — pac command → owning team (the critical split)

When pac CLI exits non-zero, the owning team depends on which pac command ran AND where the error originates:

pac command                    → Error origin               → Owner
─────────────────────────────────────────────────────────────────────────────
pac auth create/clear          → pac crashes / token error  → pac CLI (admin-tools)
pac auth create/clear          → wrong args from wrapper    → cli-wrapper (L3)

pac env create/delete/         → any pac-side failure       → admin-tools
  backup/restore/copy/reset

pac admin *                    → any failure                → admin-tools

pac solution import            → pac crashes / bad args     → pac CLI (admin-tools)
pac solution import            → Dataverse API error        → CDS / Solution Framework
pac solution import            → PVA component error        → pac CLI (IcM 604312672)

pac solution export            → pac crashes / bad args     → pac CLI (admin-tools)
pac solution export            → Dataverse API error        → CDS / Solution Framework

pac solution publish           → Dataverse API error        → CDS / Solution Framework

pac solution check             → checker service error      → Power Apps Checker team

pac package deploy             → pac crashes               → pac CLI (admin-tools)
pac package deploy             → Dataverse-side error       → CDS / Solution Framework

How to tell pac crash vs Dataverse error:

• pac crash / pac team: System.Exception, NullReferenceException, Unhandled exception, pac process exits with code 1 and no HTTP status in the message, InnerException in .NET stack trace
• Dataverse error / CDS team: HTTP status code in error (400, 403, 404, 500), OrganizationServiceFault, ErrorCode:, Microsoft.Crm.* in the message, ImportJobId, solution operation GUID, The import of solution messages
• Auth error / admin-tools or cli-wrapper: Azure AD / MSAL errors, AADSTS* error codes, interaction_required, token acquisition errors

Print:

Failing task: <task name>
pac command: <exact pac subcommand, e.g. "pac solution import">
Layer: <L1 | L2 | L3 | L4-pac | L4-admin | L4→L5>
Owner: <PPBT | cli-wrapper | pac-CLI/admin-tools | CDS/solution-framework | pipeline-config>
Error origin signal: <pac crash | Dataverse HTTP error | auth/AAD error | pipeline config>
Confidence: <high | medium | low>
Reasoning: <one sentence>

2d — pac CLI telemetry (L4-pac and L4→L5 only)

Run this step if and only if the layer is L4-pac or L4→L5.

pac CLI sends telemetry to PPUX Analytics via OneCollector. If the error output contains a Session ID like:

Sorry, the app encountered a non recoverable error and will need to terminate.
Session Id: 57f79894-80fb-4f44-8c94-8f800fc13e63,
Exception Type: System.ServiceModel.CommunicationException

Extract the Session ID and run the following Kusto query in PPUX Analytics to pull all telemetry events for that session:

EventAll
| where data_appName == "ppdevtools-pac"
| where data_clientSessionId == "<session-id-from-error>"

Additional useful queries:

Get the exact commands executed in the session:

EventAll
| where data_appName == "ppdevtools-pac"
| where data_clientSessionId == "<session-id-from-error>"
| where data_eventModifier == "Complete"
| extend eventInfo = parse_json(data_eventInfo)
| project eventInfo.command, timestamp

Get all errors in the session:

EventAll
| where data_appName == "ppdevtools-pac"
| where data_clientSessionId == "<session-id-from-error>"
| where data_eventModifier == "Failed" or data_severity >= 3
| project timestamp, data_eventName, data_eventInfo

If no Session ID is present in the log: note it and proceed — telemetry lookup not possible without it.

Print telemetry findings before continuing to Step 3.

---

Step 3 — Search for known issues (run all in parallel)

Extract 2–3 keywords from the error.

3a — GitHub issues

gh search issues --repo microsoft/powerplatform-build-tools \
  --state open --limit 10 "<keyword1> <keyword2>" 2>&1
gh search issues --repo microsoft/powerplatform-build-tools \
  --state closed --limit 5 "<keyword1> <keyword2>" 2>&1

3b — Merged PRs

gh search prs --repo microsoft/powerplatform-build-tools \
  --state merged --limit 5 "<keyword1> <keyword2>" 2>&1

3c — ADO work items

az boards query --wiql "
  SELECT [System.Id], [System.Title], [System.State], [System.ChangedDate]
  FROM WorkItems
  WHERE [System.AreaPath] UNDER 'OneCRM\Client\UnifiedClient\AppLifeCycle\PPBT Extensions'
    AND [System.Title] CONTAINS '<keyword1>'
  ORDER BY [System.ChangedDate] DESC
" --output json 2>&1

3d — Local knowledge base

Read memory/ado-knowledge.md and check MEMORY.md known customer issues section.

Research summary (print before acting)

Known issue match: <issue/PR/ADO ID + title, or "none">
Accepted risk: <yes — <reason>, or "no">
Fix already shipped: <yes — in PR #<n> / pac version <v>, or "no">
Recommended action: <resolve | triage | deflect | update-pac | pipeline-fix>

If a confirmed fix already exists in a merged PR or shipped pac CLI version, report it and stop here.

---

Step 4 — Resolve (L1 pipeline config or L2 build-tools code)

L1 — Pipeline configuration fix (no code change)

Produce a precise fix instruction:

Pipeline fix required:
- Issue: <what's wrong>
- Fix: <exact YAML or UI step>
- Reference: <task name + parameter from Step 2 tables>

Common L1 fixes:

• Missing tool-installer → add PowerPlatformToolInstaller@2 as first step
• Import timeout → add AsyncOperation: true and MaxAsyncWaitTime: 60
• Wrong environment targeted → check BuildTools.EnvironmentUrl side effect from create-environment
• Checker with username/password → switch service connection to SPN
• Connection references missing → add UseDeploymentSettingsFile: true + provide DeploymentSettingsFile
• GitHub Actions: timeout installing pac CLI → add actions-install@v1 before other actions

L2 — Build-tools code fix (this repo)

1. Read the relevant src/tasks/<name>/index.ts and task.json
2. Make the minimal fix
3. npm run build 2>&1 — must pass
4. npm test 2>&1 — must pass (functional test failures are expected locally — not a blocker)
5. git commit -m "fix: <description> (#<work-item-id-if-known>)"
6. Hand off to /create-pr

---

Step 5 — Triage package (L3–L5 and non-PPBT)

Routing table

Layer / Signal	Route to	Contact / Repo
L3 — cli-wrapper arg assembly or auth arg bug	cli-wrapper repo	GH issue on microsoft/powerplatform-cli-wrapper
L4-pac — pac CLI crash, .NET exception in pac	pac CLI / admin-tools	ADO: OneCRM\Client\UnifiedClient\AppLifeCycle\Deployment Hub\Admin
L4-admin — pac env * or pac admin * failure	admin-tools	ADO: OneCRM\Client\UnifiedClient\AppLifeCycle\Deployment Hub\Admin
L4→L5 — pac solution import/export/publish + Dataverse HTTP error	CDS / Solution Framework	ADO: OneCRM\CDS (use pac team as router if area unclear)
L4→L5 — pac solution check / checker API	Power Apps Checker service	Route via PAC team or CDS
L5 — PVA component import failure	pac CLI team (known IcM 604312672)	ADO: Deployment Hub\Admin
L5 — pure Dataverse API error, no pac involvement	CDS / Solution Framework	ADO: OneCRM\CDS
Non-PPBT (Wael Hamze, XRM Tooling)	Deflect	Community tool — not Microsoft PPBT
ADO Server 2020 on-prem	Deflect	Not supported — cloud or Server 2022+ only

Triage package

This is mandatory output for ALL L3–L5 and non-PPBT cases. You MUST produce this block — do not skip it, summarize it, or replace it with prose.

For non-PPBT deflects (Wael Hamze, XRM Tooling, ADO Server 2020), fill in:

• Route to: Deflect to CSS / community tool owner
• ADO area path: N/A
• PPBT is not the root cause because: — cite the exact log signal that proves it (author, task class, tool name, absence of PPBT signals)

═══════════════════════════════════════════════════════
TRIAGE PACKAGE
═══════════════════════════════════════════════════════
Route to:        <team name | "Deflect — community tool">
ADO area path:   <path, or N/A>
GitHub repo:     <repo, or N/A>

Issue summary:
  <2–3 sentence plain-English description of what failed and where>

Reproduction evidence:
  Platform:      <ADO | GitHub Actions>
  Task/Action:   <name + version>
  pac CLI ver:   <version from log, or unknown>
  Auth type:     <SPN | Username/Password | Workload Identity Federation>
  Environment:   <cloud / region if visible>
  Error line:    <exact log line that proves the failure>
  Timestamp:     <ISO timestamp>

PPBT is not the root cause because:
  <one sentence — e.g. "pac CLI exited with code 1 after a Dataverse HTTP 500 on the import endpoint">

Suggested next steps for the receiving team:
  1. <action>
  2. <action>

Related known issues:
  <ADO ID / GH issue / IcM, or "none found">

Log file / evidence:
  <file path, or "pasted text — see conversation">
═══════════════════════════════════════════════════════

---

Step 6 — Outcome summary

Always end with a plain-English paragraph covering:

• What failed and where in the call chain
• Whether PPBT owns it
• What was done (fix applied / triage package / deflected)
• Any follow-up needed from the user

---

Quick-reference: authentication types

ADO authenticationType	GitHub secrets	pac CLI args	MFA support
PowerPlatformSPN (recommended)	app-id + client-secret + tenant-id	--applicationId --clientSecret --tenant	Yes
PowerPlatformEnvironment (user/pass)	user-name + password-secret	--username --password	No
Workload Identity Federation	ADO service connection only	--azureDevOpsFederated	Yes
Managed Identity	ADO service connection only	--managedIdentity	Yes

Quick-reference: task ordering rules

tool-installer / actions-install     ← MUST run first (sets POWERPLATFORMTOOLS_PACCLIPATH)
      │
      ├── whoAmI                     ← optional connectivity check
      │
      ├── create-environment         → sets BuildTools.EnvironmentUrl (auto-used by downstream tasks)
      │         │
      │         ├── import-solution  ← use AsyncOperation:true for large solutions
      │         ├── apply-solution-upgrade  ← only after import with HoldingSolution:true
      │         ├── export-solution
      │         ├── pack-solution / unpack-solution  (local, no connection needed)
      │         ├── publish-customizations
      │         ├── set-solution-version
      │         ├── checker          ← SPN only, no username/password
      │         └── deploy-package   ← Windows runner only (GitHub Actions)
      │
      ├── backup-environment → restore-environment
      ├── copy-environment
      └── delete-environment

Quick-reference: common error → fix mapping

Error message / symptom	Likely cause	Fix
pac.exe not found / POWERPLATFORMTOOLS_PACCLIPATH not set	tool-installer not run first	Add PowerPlatformToolInstaller@2 as first pipeline step
Task times out at 4 minutes (import)	Sync import of large solution	Add AsyncOperation: true
auth create failed	Wrong credentials or cloud instance	Check service connection; verify cloudInstance via resolveCloudInstance()
Cannot resolve AAD authority	Wrong cloud / blocked AAD endpoint	Check cloudInstance, check network/proxy on agent
WhoAmI failed on non-English agent	cli-wrapper locale bug (ADO #4846644)	Set LANG=en_US.UTF-8 on agent; workaround only
Connection references not configured	DeploymentSettingsFile not provided	Set UseDeploymentSettingsFile: true and provide settings file
Checker fails with username/password	Checker only supports SPN	Switch service connection to SPN
deploy-package fails on Linux	Windows-only task	Use runs-on: windows-latest (GitHub Actions)
PVA component import fails	pac CLI issue (IcM 604312672)	Update pac CLI version in nuget.json; escalate to pac team if persists
BuildTools.EnvironmentUrl wrong env	Create-environment side effect overriding	Explicitly set Environment input on subsequent tasks to override
Timeout installing pac (GitHub Actions)	pac CLI install race condition	Add actions-install@v1 before other actions
Old v1 tasks used with v2 tasks	Cannot mix task versions	Upgrade all tasks to @v2