How to Boot a Specific Simulator in GitHub Actions

Use xcrun simctl to create, boot, and wait on a specific simulator before any UI test that needs it already running.

Resolve a device UDID with simctl list, boot it with simctl boot, and bootstatus -b to block until it is ready. Useful when a step needs the simulator alive before xcodebuild starts.

Steps

• Find or create the device with xcrun simctl list devices / create.
• Boot it with xcrun simctl boot <udid>.
• Wait with xcrun simctl bootstatus <udid> -b.

Workflow

jobs:
  ui-test:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - name: Boot simulator
        run: |
          UDID=$(xcrun simctl create ci-iphone \
            "iPhone 16" "iOS17.5" 2>/dev/null \
            || xcrun simctl list devices "iPhone 16" -j | \
               python3 -c 'import json,sys;print(json.load(sys.stdin)["devices"].popitem()[1][0]["udid"])')
          xcrun simctl boot "$UDID"
          xcrun simctl bootstatus "$UDID" -b
      - run: xcrun simctl list devices booted

Gotchas

• Runtime identifiers like iOS17.5 must match an installed runtime; check xcrun simctl list runtimes.
• xcodebuild can boot the simulator itself; explicit booting only helps when you need it up beforehand.

Related guides