2026 Global iOS Build Cache Governance: Xcode Derived Data & Dependency Caches—Single-Region Authority or Regional Physical Mac Nodes?
Global iOS teams oscillate between “one authoritative cache + cross-region sync” and “local caches on physical Macs in every region.” This article aligns latency, consistency, and cost with sign-off thresholds: two decision matrices, a seven-step runbook, copy-paste rsync and environment-variable snippets, and an FAQ.
Who and what hurts: When global teams reuse Xcode Derived Data and SPM/CocoaPods caches across CI and remote physical Macs, cross-ocean cache pulls inflate P95 build time, while cache skew causes sporadic link errors. Takeaway: Do not bind low-churn read-only dependency caches to the same replication policy as high-churn Derived Data; use threshold matrices to choose single-region authority versus regional colocation. What you get: Two tables, seven rollout steps, copy-paste commands, FAQ.
1. Pain points
- Hidden cost is “small-file storms”: Derived Data contains huge numbers of tiny files and indexes. Cross-region rsync or object listing metadata often exceeds useful throughput, so jobs queue in “Restore cache” instead of compiling slowly.
- Consistency beats “latest”: Mixing Xcode patch versions, Swift toolchains, module caches, and indexes produces flaky incremental failures. Teams need auditable content-addressed keys—not a vague “last night’s build.” For cross-border RTT baselines, see the 2026 multi-region remote physical Mac acceptance: RTT, jitter, and packet-loss SLO matrix, and for collaboration latency tactics, the global collaboration latency optimization handbook 2026.
- Permissions and compliance: Single-region concentration often co-locates source fingerprints and build artifacts in one bucket. With per-region physical Macs, define which directories may leave a jurisdiction and which must stay on local audited disks—avoid syncing intermediate binaries to shares without a chain of custody.
2. Derived Data & dependency caches: single-region authority vs regional physical Macs
The table below first cuts on whether builds run independently in each region and how much job time cache restore consumes (order-of-magnitude thresholds you can tune per repository size).
| Dimension | Single-region authority + async replication | Per-region physical Mac local cache (colocated) |
|---|---|---|
| Best fit | One primary build region; other regions run < 3 builds/day and tolerate 15–45 min cold starts | Each region runs ≥ 5 integration or full builds/day, or cache restore exceeds ~25% of job duration |
| Network assumptions | Replication uses private line or same-cloud backbone; cross-region bulk copy happens in maintenance windows | Builders sit in-region with Git and artifacts; Derived Data never sits on a cross-ocean hot path |
| Derived Data | Keep “golden” snapshots for other regions to pull; strict bucketing by exact Xcode version | Independent writable directory per region; never hard-link reuse across Xcode patch versions |
| SPM / CocoaPods | Object storage + CDN read-only; decouple from Derived Data | Regional volume mount or local SSD; periodically reconcile checksums with upstream registries |
| Main risks | One bad snapshot poisons every region; cross-region bandwidth bills spike | Disk layout and retention policies drift by region; automate eviction |
3. Cross-border collaboration: latency × consistency decision matrix
Plot Git and artifact RTT against cache incident rate (non-deterministic failures attributed to cache per week ÷ total builds) for fast review meetings.
| Cache incident rate < 0.5% | Cache incident rate ≥ 0.5% | |
|---|---|---|
| Regional P95 RTT to Git < 80 ms | Prefer colocation: local Derived Data + in-region dependency cache | Fix keyspace first: bucket by exact Xcode version and branch, then colocate |
| Regional P95 RTT ≥ 80 ms or intermittent loss | Allow single-region authoritative dependency cache + minimal compile-critical sets outside the region | Forbid hot cross-ocean Derived Data sync; switch to canary clean rebuilds |
Add these to your SLO doc: cache entry max age within the current release train; P95 time from cache restore complete to first xcodebuild compile start under 90 s (medium repos) or 180 s (monorepos). Breach disables remote cache for that job label and forces a regional clean build.
4. Seven-step runbook
- Inventory paths: Separate
DerivedData, SPM global cache, CocoaPods cache, and custom binary framework dirs. Only content-addressed read-only trees belong in object storage. - Define cache keys: Keys must include at least Xcode version, Swift version, branch or lockfile hash, and configuration (Debug/Release). Ban a single repo-wide
latestpointer. - Pick the primary build region: Align with the main Git remote and artifact registry; other regions sync dependency layers only or accept longer cold starts.
- Canary job: Promote a new cache bucket only after one physical Mac completes a full clean build and tests pass.
- Measure three phases: Instrument restore, compile, and test separately. If restore dominates, fix topology before buying more CPU.
- Invalidation: On Xcode upgrade day retire old buckets automatically; keep N−1 read-only snapshots for 7–14 days for rollback.
- Sign-off artifact: Print both matrices on one page for the on-call runbook cover. Before each cache topology change, re-run the regional RTT/jitter acceptance probes from the multi-region remote Mac SLO article linked under pain points above.
5. Copy-paste sync parameter checklist
Paste into scripts after substituting hosts and paths. Always dry-run deletions first.
A. rsync: Derived Data bulk sync (timestamps preserved; use --delete variants with care)
Push to regional volume (example):
rsync -aH --numeric-ids --delete-delay \ --exclude 'ModuleCache.noindex/**' \ --exclude 'CompilationCache.noindex/**' \ --timeout=300 --contimeout=60 \ ~/Library/Developer/Xcode/DerivedData/ \ build@REGION-MAC.CORP:/Volumes/BuildCache/DerivedData/
B. rsync: SPM read-only cache (omit --delete to avoid deleting concurrent builders’ files)
rsync -aH --numeric-ids --omit-dir-times \ ~/Library/Caches/org.swift.swiftpm/ \ s3proxy-local:/spm-ro/KEY/
C. CocoaPods cache tarball stream (for expensive cross-region bandwidth, hour-level staleness OK)
tar --posix -cf - -C ~/Library/Caches/CocoaPods . \ | pigz -1 \ | ssh -o ServerAliveInterval=30 build@REMOTE 'pigz -d | tar -xf - -C /Volumes/Cache/CocoaPods'
D. Environment variables (CI template fragment)
export DERIVED_DATA_PATH="/Volumes/BuildCache/DerivedData/${CACHE_KEY}"
export CLONED_SOURCE_PACKAGES_DIR_PATH="/Volumes/BuildCache/SPM/${CACHE_KEY}"
export COCOAPODS_CACHE_DIR="/Volumes/BuildCache/CocoaPods/${CACHE_KEY}"
# Before xcodebuild: verify writable paths and Xcode build matches CACHE_KEY
6. Summary
Quotable thresholds (examples): ① Cache restore > ~25% of job time → architecture review. ② Cache-related failures ≥ 0.5% per week → freeze cross-region Derived Data sync. ③ Per-job rsync timeout 300 s, connection timeout 60 s. ④ Keys must include exact Xcode version. ⑤ Pool-wide promotion only after canary clean build passes.
There is no silver bullet: dependency caches want “far, slow, read-only,” while Derived Data wants “near, fast, disposable.” Split buckets first; the single-region versus multi-region debate then reduces to bandwidth arithmetic and SLO math.
7. Run this governance stack on Mac mini
Every path above works natively on macOS: Xcode, SwiftPM, local SSDs, and Unix tooling without extra shims. Apple Silicon Mac mini pairs high unified-memory bandwidth with roughly 4 W-class idle power—ideal as a 24/7 regional cache anchor that warms indexes and dependencies while the fleet sleeps. macOS crash rates stay low, and Gatekeeper, SIP, and FileVault stack cleanly for security reviews compared with generic build hosts.
If you want every geography to complete restore plus compile inside local RTT instead of dragging Derived Data across oceans as tarballs, standardizing on Mac mini pools per region is the least noisy form factor—compact, often fanless or whisper-quiet, and cheaper in power and ops attention over a multi-year horizon.
When you are ready to move from “it builds somewhere” to “we can sign an SLO,” Mac mini M4 is one of the best price-to-stability anchors for standardized build nodes—rent or scale regional physical Mac capacity today and land cache policy on real disks and networks.
8. FAQ
Should Derived Data live in one region or on every regional physical Mac?
If builds primarily run in one region and other regions only validate lightly, use single-region authority with async replication. If each region runs daily full builds and cross-ocean Git or artifact RTT dominates, colocate writable Derived Data on regional physical Macs and keep dependency resolution in-region.
Which consistency thresholds matter most?
Sign-off friendly examples: max cache age within one release train, checksum or content key agreement, never sharing Derived Data paths across Xcode patch versions, SPM resolution failure rate, and cold-start share. Above threshold, prefer regional clean rebuild over incremental cross-region sync.
Must SPM and CocoaPods follow the same policy as Derived Data?
No. Dependencies suit content-addressed read-only storage; Derived Data is build output and indexes. Keep dependencies on object storage or shared read-only volumes and Derived Data as per-region writable storage.
What is the biggest risk of single-region concentration?
Cross-region bandwidth, long-tail latency on huge trees, and one bad sync poisoning multiple regions. Mitigate with chunked verification, per-branch buckets, and canary builds before promotion.
Running iOS builds on multi-region physical Macs?
Colocate nodes with Git and artifacts to cut Derived Data and dependency restore latency—spin up Xcode build pools and remote desktops on demand.