afv-library/skills/dx-devops-test-pipeline-configure/references/gotchas.md

Critical Gotchas

Duplicate provider configuration (the big one)

POST /connect/devops/pipeline/<pipelineId>/testProvider creates a new provider configuration record (DevopsPipelineTestProvider). Use it ONLY to configure a provider for the first time (Mode A).

To re-sync an already-configured provider for new suites, use POST /connect/devops/sync (Mode B). Calling the configure endpoint on an already-configured provider produces duplicate DevopsPipelineTestProvider records.

Decision tree:

• Provider is Available → configure via POST .../pipeline/<id>/testProvider (Mode A).
• Provider is Configured, new suites missing → sync via POST /connect/devops/sync (Mode B).
• Provider is Configured, suites missing only when assigning to a stage → stage-assignment gap; redirect to dx-devops-test-suite-assignments-configure.

API name differences

Issue	Resolution
DevopsPipeline query returns empty	DevOps Center not installed on the target org, or wrong org alias — ask the user to verify
DevopsWorkItem sObject not supported	Use WorkItem (no namespace) — the correct API name for this org version
sf plugins doesn't match agentforce	The installed plugin is @salesforce/plugin-agent — match on plugin-agent too

Trigger-type rules

Issue	Resolution
Review trigger is pipeline-level, not stage-level	Query DevopsPipelineStageTrigger where TriggerType = 'Review' and RelatedRecordId = <pipelineId>
Connect API testSuites returns empty with ?stageId=	Use ?triggerId=<reviewTriggerId> — stageId only works for stage-level triggers

Endpoint families

• Configure provider: POST /connect/devops/pipeline/<pipelineId>/testProvider
• Sync provider: POST /connect/devops/sync
• List providers: GET /connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all
• Quality gate: POST /connect/devopstesting/qualityGate

Note the devops vs devopstesting path segment differs between sync/configure and the listing/quality-gate endpoints — copy them exactly.