xcode-cloud-ci

name	xcode-cloud-ci
description	Check Xcode Cloud CI build status via App Store Connect API. Triggers after `git push` in iOS/macOS projects using Xcode Cloud (no .github/workflows directory). Monitors builds, reports results, and helps debug failures.

Xcode Cloud CI Watcher

After performing a git push in an iOS/macOS project using Xcode Cloud, check build status.

Prerequisites

Credentials must be configured at ~/.config/app-store-connect/credentials.json. See setup instructions below.

Required Python packages: pip3 install PyJWT requests

Workflow

1. After pushing, wait before checking (builds need time to start)
2. Determine polling strategy:
   • Xcode Cloud builds typically take 5-15 minutes
   • Wait 2-3 minutes initially, poll every 30-60s
3. Check status using the check script
4. On success: Report and continue
5. On failure: Analyze the error, propose a fix

Checking Status

# Check most recent build
scripts/check_xcode_cloud.py

# Filter by app/product name
scripts/check_xcode_cloud.py --product "MyApp"

# Filter by workflow
scripts/check_xcode_cloud.py --product "MyApp" --workflow "Release"

# Poll for up to 10 minutes
scripts/check_xcode_cloud.py --wait 600

# List available products
scripts/check_xcode_cloud.py --list-products

# List workflows for a product
scripts/check_xcode_cloud.py --product "MyApp" --list-workflows

On Failure

1. Check the build details in App Store Connect
2. Analyze the error and identify root cause
3. Propose a specific fix with code changes
4. Ask: "Xcode Cloud build failed due to [reason]. I can fix this by [solution]. Should I implement this fix?"

Credentials Setup

1. Go to App Store Connect → Users and Access → Integrations → App Store Connect API
2. Click + to create a new key
3. Name it (e.g., "CI Watcher"), select Developer or Admin role
4. Download the .p8 private key file (only downloadable once!)
5. Note the Key ID and Issuer ID

Create the credentials file:

mkdir -p ~/.config/app-store-connect

Create ~/.config/app-store-connect/credentials.json:

{
  "issuer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "key_id": "XXXXXXXXXX",
  "private_key_path": "~/.config/app-store-connect/AuthKey_XXXXXXXXXX.p8"
}

Move your .p8 file to ~/.config/app-store-connect/ and update the path.

Set restrictive permissions:

chmod 600 ~/.config/app-store-connect/credentials.json
chmod 600 ~/.config/app-store-connect/*.p8