CI/CD with Xcode Cloud and the Command Line

{
  "data": {
    "type": "ciWorkflows",
    "id": "00000000-0000-0000-0000-000000000000",
    "attributes": {
      "name": "PR Checks",
      "description": "Builds every platform and runs FieldNotes.xctestplan on each pull request into main.",
      "isEnabled": true,
      "clean": false,
      "containerFilePath": "FieldNotes.xcodeproj",
      "pullRequestStartCondition": {
        "source": { "isAllMatch": true },
        "destination": { "isAllMatch": false, "patterns": [{ "pattern": "main", "isPrefix": false }] },
        "filesAndFoldersRule": {
          "mode": "DO_NOT_START_IF_ALL_FILES_MATCH",
          "matchers": [{ "directory": "docs" }, { "fileExtension": "md" }]
        },
        "autoCancel": true
      },
      "actions": [
        {
          "name": "Build watchOS",
          "actionType": "BUILD",
          "platform": "WATCHOS",
          "scheme": "FieldNotesWatch",
          "destination": "ANY_WATCHOS_SIMULATOR",
          "isRequiredToPass": true
        },
        {
          "name": "Test iOS",
          "actionType": "TEST",
          "platform": "IOS",
          "scheme": "FieldNotes",
          "isRequiredToPass": true,
          "testConfiguration": {
            "kind": "SPECIFIC_TEST_PLANS",
            "testPlanName": "FieldNotes",
            "testDestinations": [
              {
                "kind": "SIMULATOR",
                "deviceTypeName": "iPhone 17",
                "deviceTypeIdentifier": "com.apple.CoreSimulator.SimDeviceType.iPhone-17",
                "runtimeName": "iOS 27.0",
                "runtimeIdentifier": "com.apple.CoreSimulator.SimRuntime.iOS-27-0"
              }
            ]
          }
        },
        {
          "name": "Test macOS",
          "actionType": "TEST",
          "platform": "MACOS",
          "scheme": "FieldNotes",
          "isRequiredToPass": true,
          "testConfiguration": {
            "kind": "SPECIFIC_TEST_PLANS",
            "testPlanName": "FieldNotes",
            "testDestinations": [{ "kind": "MAC", "deviceTypeName": "Mac" }]
          }
        }
      ]
    }
  }
}

#!/bin/zsh
# ci_scripts/ci_post_clone.sh -- runs once per action, after the clone.
set -euo pipefail

# Only pull requests are linted; the release workflow trusts what was merged.
if [[ -n "${CI_PULL_REQUEST_NUMBER:-}" ]]; then
  echo "Linting pull request #$CI_PULL_REQUEST_NUMBER from $CI_PULL_REQUEST_SOURCE_BRANCH"
  cd "$CI_PRIMARY_REPOSITORY_PATH"
  xcrun swift-format lint --strict --recursive FieldNotes Packages
fi

#!/bin/zsh
# ci_scripts/ci_post_xcodebuild.sh -- runs after every xcodebuild command.
set -euo pipefail

# Nothing to do if xcodebuild failed; Xcode Cloud already reports the failure.
[[ "${CI_XCODEBUILD_EXIT_CODE:-1}" == "0" ]] || exit 0

# 1. TestFlight notes for builds that can go to TestFlight.
if [[ -d "${CI_APP_STORE_SIGNED_APP_PATH:-}" ]]; then
  cd "$CI_PRIMARY_REPOSITORY_PATH"
  mkdir -p TestFlight
  git fetch --deepen 3
  git log -3 --pretty=format:"- %s" > TestFlight/WhatToTest.en-US.txt
fi

# 2. Notarize the Developer ID export of the Mac archive with an App Store Connect API key
#    kept in secret workflow variables (never echo them).
if [[ "${CI_PRODUCT_PLATFORM:-}" == "macOS" && -d "${CI_DEVELOPER_ID_SIGNED_APP_PATH:-}" ]]; then
  # A private (0700) scratch directory; the trap removes exactly it, key and zip included.
  work_dir=$(mktemp -d "${TMPDIR:-/tmp}/fieldnotes-notary.XXXXXX")
  trap 'rm -rf "$work_dir"' EXIT
  key_file="$work_dir/AuthKey_${FIELDNOTES_ASC_KEY_ID}.p8"
  (umask 077 && print -r -- "$FIELDNOTES_ASC_PRIVATE_KEY" > "$key_file")

  zip_path="$work_dir/FieldNotes.zip"
  ditto -c -k --keepParent "$CI_DEVELOPER_ID_SIGNED_APP_PATH/FieldNotes.app" "$zip_path"
  xcrun notarytool submit "$zip_path" --wait \
    --key "$key_file" --key-id "$FIELDNOTES_ASC_KEY_ID" --issuer "$FIELDNOTES_ASC_ISSUER_ID"
fi

// Dashboard/XcodeCloudBuildEvent.swift -- the fields the FieldNotes dashboard reads from a webhook.
import Foundation

struct XcodeCloudBuildEvent: Decodable, Sendable {
    struct Metadata: Decodable, Sendable {
        struct Attributes: Decodable, Sendable { let eventType: String; let createdDate: String }
        let attributes: Attributes
    }
    struct Workflow: Decodable, Sendable {
        struct Attributes: Decodable, Sendable { let name: String }
        let id: String
        let attributes: Attributes
    }
    struct BuildRun: Decodable, Sendable {
        struct Attributes: Decodable, Sendable {
            let number: Int
            let executionProgress: String
            let completionStatus: String?      // absent until the build completes
            let isPullRequestBuild: Bool
        }
        let id: String
        let attributes: Attributes
    }

    let metadata: Metadata
    let ciWorkflow: Workflow
    let ciBuildRun: BuildRun
}

enum XcodeCloudWebhookError: Error { case unexpectedEvent(String) }

/// Decodes a webhook body. Throws on malformed JSON instead of guessing, so the endpoint can answer 400.
func decodeBuildEvent(_ body: Data) throws -> XcodeCloudBuildEvent {
    let event = try JSONDecoder().decode(XcodeCloudBuildEvent.self, from: body)
    let known: Set = ["BUILD_CREATED", "BUILD_STARTED", "BUILD_COMPLETED"]
    guard known.contains(event.metadata.attributes.eventType) else {
        throw XcodeCloudWebhookError.unexpectedEvent(event.metadata.attributes.eventType)
    }
    return event
}

# Resolve once, into a folder the CI cache can save and restore (keyed on Package.resolved).
xcodebuild -resolvePackageDependencies \
  -project FieldNotes.xcodeproj -scheme FieldNotes \
  -clonedSourcePackagesDirPath build/SourcePackages \
  -disableAutomaticPackageResolution

# Private packages over SSH, with the machine's own git configuration (proxies, URL rewrites).
xcodebuild -resolvePackageDependencies -project FieldNotes.xcodeproj -scheme FieldNotes \
  -clonedSourcePackagesDirPath build/SourcePackages -scmProvider system

# Compile-check every platform FieldNotes ships on, without running anything.
for platform in iOS macOS visionOS; do
  xcodebuild build -project FieldNotes.xcodeproj -scheme FieldNotes \
    -destination "generic/platform=$platform" \
    -clonedSourcePackagesDirPath build/SourcePackages -disableAutomaticPackageResolution \
    CODE_SIGNING_ALLOWED=NO
done
xcodebuild build -project FieldNotes.xcodeproj -scheme FieldNotesWatch \
  -destination 'generic/platform=watchOS Simulator' CODE_SIGNING_ALLOWED=NO

# Which destinations does a scheme support on this machine?
xcodebuild -showdestinations -project FieldNotes.xcodeproj -scheme FieldNotes

# The Default configuration on an iPhone and an iPad simulator, in parallel.
xcodebuild test -project FieldNotes.xcodeproj -scheme FieldNotes \
  -testPlan FieldNotes -only-test-configuration Default \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=27.0' \
  -destination 'platform=iOS Simulator,name=iPad Pro 13-inch (M5),OS=27.0' \
  -resultBundlePath build/FieldNotes-iOS.xcresult

# Build once, then test the same products elsewhere (this is what Xcode Cloud's two phases do).
xcodebuild build-for-testing -project FieldNotes.xcodeproj -scheme FieldNotes -testPlan FieldNotes \
  -destination 'generic/platform=iOS Simulator' -derivedDataPath build/DerivedData
xcodebuild test-without-building -xctestrun build/DerivedData/Build/Products/FieldNotes_FieldNotes_iphonesimulator27.0-arm64.xctestrun \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=27.0'

# A readable summary of the result bundle for the CI log.
xcrun xcresulttool get test-results summary --path build/FieldNotes-iOS.xcresult

<?xml version="1.0" encoding="UTF-8"?>
<!-- ExportOptions.plist; App Store Connect distribution (see App Store Connect, TestFlight and App Review) -->
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store-connect</string>
    <key>teamID</key>
    <string>ABCDE12345</string>
    <key>destination</key>
    <string>upload</string>
</dict>
</plist>

# Archive with a CI build number; the key file comes from a CI secret (see GitHub Actions below).
xcodebuild archive -project FieldNotes.xcodeproj -scheme FieldNotes \
  -destination 'generic/platform=iOS' \
  -archivePath build/FieldNotes-iOS.xcarchive \
  -clonedSourcePackagesDirPath build/SourcePackages -disableAutomaticPackageResolution \
  -allowProvisioningUpdates \
  -authenticationKeyPath "$ASC_KEY_PATH" \
  -authenticationKeyID "$ASC_KEY_ID" \
  -authenticationKeyIssuerID "$ASC_ISSUER_ID" \
  CURRENT_PROJECT_VERSION="$BUILD_NUMBER"

# Sign for App Store Connect and upload in one step.
xcodebuild -exportArchive -archivePath build/FieldNotes-iOS.xcarchive \
  -exportOptionsPlist ExportOptions.plist -exportPath build/export-iOS \
  -allowProvisioningUpdates \
  -authenticationKeyPath "$ASC_KEY_PATH" \
  -authenticationKeyID "$ASC_KEY_ID" \
  -authenticationKeyIssuerID "$ASC_ISSUER_ID"

# A throwaway iPhone for this job, booted and ready before tests start.
udid=$(xcrun simctl create "FieldNotes CI" "iPhone 17" com.apple.CoreSimulator.SimRuntime.iOS-27-0)
# Always clean up, even when a later step fails. Shutting down an already shut-down simulator
# fails, so that step must not stop the delete.
trap 'xcrun simctl shutdown "$udid" || true; xcrun simctl delete "$udid"' EXIT
xcrun simctl boot "$udid"
xcrun simctl bootstatus "$udid"

# Deterministic screenshots: fixed status bar, location permission granted up front.
xcrun simctl status_bar "$udid" override --time "9:41" --batteryState charged --batteryLevel 100
xcrun simctl privacy "$udid" grant location com.example.fieldnotes

# Install the test build, launch it the way UI tests do, open a deep link and capture the screen.
xcrun simctl install "$udid" build/DerivedData/Build/Products/Debug-iphonesimulator/FieldNotes.app
xcrun simctl launch "$udid" com.example.fieldnotes --uitesting
xcrun simctl openurl "$udid" "fieldnotes://note/3F2504E0-4F89-11D3-9A0C-0305E82C3301"
xcrun simctl io "$udid" screenshot build/screens/note-detail.png

# New in Xcode 27: reboot a simulator without deleting it (for example after changing a setting).
xcrun simctl reboot "$udid"

# Devices this Mac can use. In Xcode 27 the list shows a UDID (or ECID, or CoreDevice ID) per device.
xcrun devicectl list devices
xcrun devicectl list devices --json-output build/devices.json

# Install and relaunch the development build on one device.
xcrun devicectl device install app --device "$DEVICE_ID" \
  build/DerivedData/Build/Products/Debug-iphoneos/FieldNotes.app
xcrun devicectl device process launch --device "$DEVICE_ID" --terminate-existing com.example.fieldnotes

# Run the test plan on the device.
xcodebuild test -project FieldNotes.xcodeproj -scheme FieldNotes -testPlan FieldNotes \
  -destination "platform=iOS,id=$DEVICE_ID" -allowProvisioningUpdates

# .github/workflows/ios.yml
name: FieldNotes

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

# A new push to the same branch cancels the run in flight: macOS minutes are expensive.
concurrency:
  group: fieldnotes-${{ github.ref }}
  cancel-in-progress: true

env:
  DEVELOPER_DIR: /Applications/Xcode_27.0.app/Contents/Developer
  SPM_DIR: build/SourcePackages

jobs:
  test:
    name: Test (${{ matrix.name }})
    runs-on: xcode-27
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: iPhone
            destination: platform=iOS Simulator,name=iPhone 17,OS=27.0
          - name: iPad
            destination: platform=iOS Simulator,name=iPad Pro 13-inch (M5),OS=27.0
          - name: Mac
            destination: platform=macOS
          - name: Vision
            destination: platform=visionOS Simulator,name=Apple Vision Pro,OS=27.0
    steps:
      - uses: actions/checkout@v7

      - name: Cache Swift packages
        uses: actions/cache@v6
        with:
          path: ${{ env.SPM_DIR }}
          key: spm-${{ runner.os }}-${{ hashFiles('FieldNotes.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved') }}
          restore-keys: spm-${{ runner.os }}-

      - name: Resolve packages
        run: |
          xcodebuild -version
          xcodebuild -resolvePackageDependencies -project FieldNotes.xcodeproj -scheme FieldNotes \
            -clonedSourcePackagesDirPath "$SPM_DIR" -disableAutomaticPackageResolution

      - name: Test
        run: |
          xcodebuild test -project FieldNotes.xcodeproj -scheme FieldNotes -testPlan FieldNotes \
            -destination '${{ matrix.destination }}' \
            -clonedSourcePackagesDirPath "$SPM_DIR" -disableAutomaticPackageResolution \
            -resultBundlePath "build/FieldNotes-${{ matrix.name }}.xcresult"

      - name: Keep the result bundle
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: xcresult-${{ matrix.name }}
          path: build/FieldNotes-${{ matrix.name }}.xcresult

  testflight:
    name: Upload to TestFlight
    needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: xcode-27
    environment: release          # secrets below are scoped to this environment
    env:
      ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
      ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
    steps:
      - uses: actions/checkout@v7

      - name: Write the App Store Connect key
        env:
          ASC_PRIVATE_KEY: ${{ secrets.ASC_PRIVATE_KEY }}
        run: |
          umask 077
          printf '%s' "$ASC_PRIVATE_KEY" > "$RUNNER_TEMP/AuthKey.p8"
          echo "ASC_KEY_PATH=$RUNNER_TEMP/AuthKey.p8" >> "$GITHUB_ENV"

      - name: Archive and upload
        run: |
          BUILD_NUMBER=$((1000 + GITHUB_RUN_NUMBER))
          xcodebuild archive -project FieldNotes.xcodeproj -scheme FieldNotes \
            -destination 'generic/platform=iOS' -archivePath build/FieldNotes-iOS.xcarchive \
            -allowProvisioningUpdates -authenticationKeyPath "$ASC_KEY_PATH" \
            -authenticationKeyID "$ASC_KEY_ID" -authenticationKeyIssuerID "$ASC_ISSUER_ID" \
            CURRENT_PROJECT_VERSION="$BUILD_NUMBER"
          xcodebuild -exportArchive -archivePath build/FieldNotes-iOS.xcarchive \
            -exportOptionsPlist ExportOptions.plist -exportPath build/export-iOS \
            -allowProvisioningUpdates -authenticationKeyPath "$ASC_KEY_PATH" \
            -authenticationKeyID "$ASC_KEY_ID" -authenticationKeyIssuerID "$ASC_ISSUER_ID"

      - name: Remove the key
        if: always()
        run: rm -f "$RUNNER_TEMP/AuthKey.p8"