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

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

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

Content truncated.