--- name: macos-ci-recipes description: > Copy-in CI recipes for adding macOS build/test/lint to a project on the ios profile — either a macOS-only app with no iOS target, or a hybrid app that also ships a separate macOS scheme sharing code with an iOS target. Use when scaffolding CI for a new macOS app, or adding a macOS target/scheme to an existing iOS project. The lacquer does not auto-sync macOS CI (only two fleet projects have needed it so far — not enough signal to justify conditional asset sync yet); these are reference recipes you copy into your project's own workflow files, adapted from two real, working implementations (a macOS-only app and an iOS+macOS hybrid). --- # macOS CI Recipes Two shapes, depending on whether an iOS target coexists in the same project. Both reuse the lacquer's existing iOS CI conventions (dedicated runner, `CODE_SIGNING_ALLOWED=NO` for non-release jobs, the exit-65 spurious-failure handling, the error-tail grep on real failures) — nothing here is a new pattern, just the iOS pattern applied to `-destination 'platform=macOS'`. **Why the dedicated runner, not a GitHub-hosted macOS one:** these jobs (and any other Xcode-touching job you add) must run on `runs-on: [self-hosted, macOS, ARM64, dedicated]` — never `macos-latest` or a stray label like `mac-mini`. Release jobs hold App Store Connect keys and unlock the login keychain, so signing must only ever happen on infrastructure you control; the pinned Xcode + simulator runtime lives only on the dedicated runner (GitHub-hosted macOS images drift); and GitHub-hosted macOS minutes are billed while the dedicated runner isn't. A pure script/REST-call job with no Xcode dependency uses `ubuntu-latest` instead. ## Which recipe - **No iOS target at all** (a macOS-only app on the `ios` profile): use "macOS-only app" below. It replaces the synced `ios-ci.yml` outright — `exclude` it in `.lacquer.toml` and add this file to your project's `root/` tree instead (the lacquer already supports excluding a synced file; this is that mechanism, just pointed at CI instead of release/testflight). - **An iOS target plus a separate macOS scheme sharing code** (e.g. a shared `Core/`+`Shared/` compiled into both an iOS app and a `MenuBarExtra`/full macOS app): use "Hybrid" below. It adds one job to your project's *own copy* of the synced `ios-ci.yml` — see "Living with a hand-edited managed file" for what that costs on future syncs. ## macOS-only app Lint, build, and test jobs mirroring the lacquer's iOS shape, with no simulator involved anywhere: ```yaml name: macOS CI on: workflow_dispatch: pull_request: branches: [main, develop, 'feat/*', 'fix/*'] push: branches: [main] permissions: contents: read concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: lint: name: swiftformat + swiftlint (strict) runs-on: [self-hosted, macOS, ARM64, dedicated] steps: - uses: actions/checkout@v6.0.2 - name: swiftformat --lint run: swiftformat --lint {{COMPONENT_PREFIX}}. - name: swiftlint --strict run: swiftlint --strict --config {{COMPONENT_PREFIX}}.swiftlint.yml {{COMPONENT_PREFIX}}. build: name: xcodebuild build (macOS) runs-on: [self-hosted, macOS, ARM64, dedicated] steps: - uses: actions/checkout@v6.0.2 # No actions/cache for SPM here: on a persistent dedicated runner, # DerivedData/SourcePackages already survives between runs on local # disk. actions/cache still tars+uploads+downloads on every run # regardless of whether anything changed — one fleet project measured # this at ~25 minutes of overhead against a 16-second compile. This is # an open question for the lacquer's OWN iOS ci.yml too (it still uses # actions/cache on the same runner class) — verify your runner is # actually the same persistent box across runs before dropping the # cache step; if it's ephemeral/rotating, keep it. - name: xcodebuild build run: | set -o pipefail xcodebuild build \ -project {{XCODEPROJ}} \ -scheme {{SCHEME}} \ -destination 'platform=macOS' \ -configuration Debug \ CODE_SIGNING_ALLOWED=NO \ | xcpretty --color || xcodebuild build \ -project {{XCODEPROJ}} \ -scheme {{SCHEME}} \ -destination 'platform=macOS' \ -configuration Debug \ CODE_SIGNING_ALLOWED=NO - name: xcodebuild test run: | set -o pipefail xcodebuild test \ -project {{XCODEPROJ}} \ -scheme {{SCHEME}} \ -destination 'platform=macOS' \ -configuration Debug \ CODE_SIGNING_ALLOWED=NO \ -only-testing: \ | xcpretty --color || xcodebuild test \ -project {{XCODEPROJ}} \ -scheme {{SCHEME}} \ -destination 'platform=macOS' \ -configuration Debug \ CODE_SIGNING_ALLOWED=NO \ -only-testing: ci-ok: name: CI OK runs-on: ubuntu-latest needs: [lint, build] if: always() timeout-minutes: 2 steps: - name: Verify required jobs passed (or were skipped) run: | for r in "${{ needs.lint.result }}" "${{ needs.build.result }}"; do if [ "$r" = "failure" ] || [ "$r" = "cancelled" ]; then echo "::error::A required job did not pass (result=$r)" exit 1 fi done ``` **UI tests are deliberately absent.** macOS UI tests need a real WindowServer/GUI login session on the runner — there's no simulator escape hatch like iOS has. One fleet project's UI tests hung with "test runner hung before establishing connection" on their dedicated runner and were dropped rather than fought. If your macOS app has UI tests, expect to need a runner with an active GUI session (not a headless/SSH-only box) before they'll run at all — don't assume the same runner that handles iOS simulator UI tests can run macOS ones for free. ## Hybrid: add a macOS job to an existing `ios-ci.yml` For a project that already syncs the lacquer's `ios-ci.yml` for its iOS target and adds a macOS scheme alongside it (shared `Core`/`Shared` code, `PRODUCT_MODULE_NAME` matching so `@testable import` resolves to whichever target owns the test bundle). Add this job to your project's copy of `ios-ci.yml`: ```yaml macos: name: macOS (Build + Test) runs-on: [self-hosted, macOS, ARM64, dedicated] needs: [lint, changes] # Skip on push-to-main (squash-merged tree == tested tree) and on # docs-only PRs. No simulator for macOS, so this is one xcodebuild that # builds + runs the macOS test bundle against the host Mac. # SECURITY: same-repo guard — fork-PR code must not build/test on the # self-hosted runner. if: (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && github.event_name != 'push' && needs.changes.outputs.code == 'true' timeout-minutes: 20 steps: - uses: actions/checkout@v6.0.2 - name: Create Secrets.xcconfig (build-time placeholder) run: | if [ -f "{{COMPONENT_PREFIX}}Secrets.xcconfig.example" ]; then cp "{{COMPONENT_PREFIX}}Secrets.xcconfig.example" "{{COMPONENT_PREFIX}}Secrets.xcconfig" fi - name: Clean stale build intermediates run: | # Gitignored DerivedData persists between runs on the dedicated # runner. Stale .o files from a prior failed/interrupted build cause # Swift incremental compilation crashes (exit 65). rm -rf {{COMPONENT_PREFIX}}DerivedData/Build - name: Install xcpretty run: | gem install xcpretty -v 0.4.1 --user-install --no-document echo "XCPRETTY=$(ruby -e 'puts File.join(Gem.user_dir, "bin", "xcpretty")')" >> $GITHUB_ENV - name: Build + Test (macOS) id: tests timeout-minutes: 12 run: | set -o pipefail rm -rf TestResults-macos.xcresult EXIT_CODE=0 xcodebuild test \ -project {{XCODEPROJ}} \ -scheme \ -destination 'platform=macOS' \ -derivedDataPath {{COMPONENT_PREFIX}}DerivedData \ -only-testing: \ -parallel-testing-enabled NO \ -resultBundlePath TestResults-macos.xcresult \ CODE_SIGNING_ALLOWED=NO \ CODE_SIGNING_REQUIRED=NO \ 2>&1 | tee xcodebuild-macos.log | $XCPRETTY --color --test || EXIT_CODE=$? # Exit code 65 is a known spurious Swift Testing failure. Confirm via # xcresulttool before trusting it — never assume pass on a code we # can't explain. if [ $EXIT_CODE -eq 65 ]; then if [ ! -d "TestResults-macos.xcresult" ]; then echo "::error::No test results found — tests may not have run" grep -iE 'error:|fatal|failed|ld:|actool|CodeSign' xcodebuild-macos.log | tail -60 exit 1 fi set +e XCRESULT_JSON=$(xcrun xcresulttool get --format json --path TestResults-macos.xcresult 2>/dev/null) set -e ALL_SUCCEEDED=$(echo "$XCRESULT_JSON" | jq -r '[.actions[]?.actionResult?.status // "unknown"] | all(. == "succeeded")' 2>/dev/null || echo "false") if [ "$ALL_SUCCEEDED" = "true" ]; then echo "All tests passed (xcresult). Exit code 65 was spurious." exit 0 fi echo "::error::Test failures detected via xcresult (or inconclusive)" grep -iE 'error:|fatal|failed|ld:|actool|CodeSign' xcodebuild-macos.log | tail -60 exit 65 elif [ $EXIT_CODE -ne 0 ]; then echo "::error::xcodebuild failed with exit code $EXIT_CODE — raw tail:" grep -iE 'error:|fatal|failed|ld:|actool|CodeSign' xcodebuild-macos.log | tail -60 exit $EXIT_CODE fi - name: Upload Test Results uses: actions/upload-artifact@v7.0.1 if: always() continue-on-error: true with: name: macos-test-results path: TestResults-macos.xcresult if-no-files-found: ignore retention-days: 1 ``` Then add `macos` to the `ci-ok` job's `needs:` list so it's part of the single required check, not a separate unenforced job. The source implementation this recipe is adapted from also validates its SPM cache for corruption (a cache saved mid-download from a cancelled run can be missing inner `.framework` bundles inside an `.xcframework`) before trusting a cache hit — worth adding if you keep `actions/cache` for SPM on this job (see the SPM-cache note in the macOS-only recipe above; the same open question applies here). ### Living with a hand-edited managed file `ios-ci.yml` is a lacquer-managed asset — normally synced verbatim. Adding a job to your own copy means `lacquer audit` will show it as `locally-modified` from then on, and a plain `lacquer sync` will refuse to overwrite it (the clobber guard) rather than silently dropping your job. When you want to pull in a lacquer update to the rest of the file, either re-apply the `macos` job after `sync --force`, or promote this pattern into the lacquer properly once a third project needs it (see `skill-authoring-standard`'s placement guidance) so it stops being a per-project patch.