Trigger and monitor an Xcode Cloud build via the App Store Connect API, then retrieve its build actions and downloadable artifacts

Documented steps

1. Authenticate with Authorization: Bearer <JWT>. Xcode Cloud READ endpoints (Products, Workflows, Build Runs, Build Actions, Git References) are on Apple's long-lived-token allowlist for scoped GET-only JWTs; the build-triggering POST still needs a normal short-lived token.
2. List products: GET /v1/ciProducts (optionally ?filter[productType]=APP — the enum is APP or FRAMEWORK — and &include=app,bundleId,primaryRepositories). Note the product id.
3. List workflows: GET /v1/ciProducts/{id}/workflows?fields[ciWorkflows]=name,isEnabled,product,repository,xcodeVersion,buildRuns&include=product,repository,xcodeVersion,macOsVersion. Note the workflow id.
4. Optionally review history: GET /v1/ciWorkflows/{id}/buildRuns?sort=-number&include=builds,workflow,product,sourceBranchOrTag,destinationBranch,pullRequest&limit=20
5. Trigger a build: POST /v1/ciBuildRuns with {"data":{"type":"ciBuildRuns","relationships":{"workflow":{"data":{"type":"ciWorkflows","id":"<workflow-id>"}}}}}. To build a specific branch or tag, add "sourceBranchOrTag":{"data":{"type":"scmGitReferences","id":"<gitReference-id>"}} inside relationships. buildRun and pullRequest relationships are also accepted.
6. curl: curl -X POST https://api.appstoreconnect.apple.com/v1/ciBuildRuns -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"data":{"type":"ciBuildRuns","relationships":{"workflow":{"data":{"type":"ciWorkflows","id":"WORKFLOW_ID"}}}}}'
7. Poll GET /v1/ciBuildRuns/{id} and watch attributes.executionProgress, the CiExecutionProgress enum: PENDING, RUNNING, COMPLETE. Use a backoff interval, not a tight loop.
8. Once executionProgress is COMPLETE, read attributes.completionStatus, the CiCompletionStatus enum: SUCCEEDED, FAILED, ERRORED, CANCELED, SKIPPED. Related attributes are startReason (GIT_REF_CHANGE, MANUAL, MANUAL_REBUILD, PULL_REQUEST_OPEN, PULL_REQUEST_UPDATE, SCHEDULE) and cancelReason (AUTOMATICALLY_BY_NEWER_BUILD, MANUALLY_BY_USER).
9. List the run's actions: GET /v1/ciBuildRuns/{id}/actions?fields[ciBuildActions]=name,actionType,executionProgress,completionStatus,issueCounts,artifacts,testResults&limit=200. Build, test, archive and analyze run as separate actions with their own progress/status.
10. List artifacts per action: GET /v1/ciBuildActions/{id}/artifacts?fields[ciArtifacts]=fileType,fileName,fileSize,downloadUrl. fileType enum: ARCHIVE, ARCHIVE_EXPORT, LOG_BUNDLE, RESULT_BUNDLE, TEST_PRODUCTS, XCODEBUILD_PRODUCTS, STAPLED_NOTARIZED_ARCHIVE.
11. Download each artifact promptly from attributes.downloadUrl; treat the URL as short-lived and re-list to refresh it rather than caching.
12. Find the App Store Connect build record the run produced: GET /v1/ciBuildRuns/{id}/builds, which returns a BuildsResponse. Xcode Cloud runs and App Store Connect builds are separate resources linked only by this relationship.
13. You can also filter run history by produced build: GET /v1/ciWorkflows/{id}/buildRuns?filter[builds]=<buildId>
14. Official docs: https://developer.apple.com/documentation/appstoreconnectapi/xcode-cloud-workflows-and-builds | https://developer.apple.com/documentation/appstoreconnectapi/post-v1-cibuildruns | https://developer.apple.com/documentation/appstoreconnectapi/ciexecutionprogress | https://developer.apple.com/documentation/appstoreconnectapi/cicompletionstatus