Pourquoi utiliser un runner CircleCI auto-hébergé sur Mac ?
CircleCI propose des environnements d'exécution macOS dans le cloud, mais ils sont accompagnés de coûts et de limitations significatifs. CircleCI facture les jobs macOS en crédits : la classe de ressource m4pro.medium consomme 200 crédits par minute (environ 0,12 $) et m4pro.large 400 (environ 0,24 $), en octobre 2026. Pour les équipes effectuant des builds iOS fréquents, cela peut rapidement atteindre 300 à 500 $ par mois ou plus.
Un runner auto-hébergé sur un Mac Mini M4 dédié de MyRemoteMac élimine entièrement la facturation à la minute. Vous obtenez une machine Apple Silicon dédiée avec un stockage persistant, des caches préchauffés et un accès root complet pour un tarif mensuel fixe à partir de 85 $/mois. Voici une comparaison détaillée :
| Caractéristique | My Remote Mac auto-hébergé | CircleCI Cloud macOS |
|---|---|---|
| Modèle tarifaire | 85 $/mois forfaitaire (minutes illimitées) | 200 crédits/min en m4pro.medium (~0,12 $/min) |
| Architecture | Mac Apple M4 physique, attribué 1:1 | Machine virtuelle M4 Pro (6 vCPU, 28 Go) |
| Vitesse de build | ~5 min (même projet) | ~14 min (projet iOS moyen) |
| Persistance du cache | Persistant sur disque (instantané) | Éphémère (à restaurer à chaque job) |
| Temps d'attente en file | 0 s (matériel dédié) | 30 s - 5 min (variable selon l'offre) |
| Confidentialité / Contrôle des données | Machine dédiée, contrôle total | Infrastructure partagée |
| Logiciels personnalisés | Accès root complet, tout logiciel | Image pré-installée uniquement |
Prix My Remote Mac en USD, hors taxes.
Avantage clé : Avec un runner auto-hébergé persistant, DerivedData, les caches Swift Package Manager et CocoaPods sont préservés entre les builds. Cela seul peut réduire les temps de build de 50 à 70 % par rapport aux environnements macOS cloud éphémères de CircleCI qui repartent de zéro à chaque fois. Combiné aux performances supérieures du M4 en mono-thread, vos builds iOS seront considérablement plus rapides.
Prérequis
Avant de commencer, assurez-vous de disposer des éléments suivants :
- Un serveur de build Mac mini M4 dédié chez My Remote Mac (dès $85/mois, USD, HT)
- Une organisation CircleCI dont vous êtes administrateur (les runners auto-hébergés sont disponibles dans toutes les offres, y compris Free, qui autorise 5 tâches auto-hébergées simultanées en octobre 2026)
- Un accès SSH à votre Mac Mini (fourni avec votre abonnement My Remote Mac)
- Un compte Apple Developer (pour la signature de code et les profils de provisionnement)
- Une connaissance de base de YAML, de la configuration CircleCI et des commandes terminal
Étape 1 : Vérifier Xcode et installer les dépendances
Commencez par vous connecter à votre Mac Mini M4 via SSH avec les identifiants reçus lors de la mise en place de votre serveur My Remote Mac. Xcode, ses Command Line Tools et Homebrew sont déjà installés : vous n'ajoutez donc que les outils de build nécessaires à votre pipeline iOS avant de configurer le runner CircleCI.
Connexion via SSH
# Connect to your Mac mini M4
ssh admin@your-server-ip
# Verify you're on Apple Silicon
uname -m
# Expected output: arm64
# Show the macOS version
sw_vers
Vérifier Homebrew et les Command Line Tools de Xcode
# Homebrew comes preinstalled: put it on your PATH for your zsh sessions
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version
# Add Homebrew to PATH for CircleCI job steps
# (CircleCI runs macOS steps in a bash login shell)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile
# Xcode and its Command Line Tools come preinstalled
xcode-select -p
# /Applications/Xcode.app/Contents/Developer
# Accept the Xcode license if it asks
sudo xcodebuild -license accept
Vérifier Xcode et ajouter d'autres versions
Pour les builds iOS, vous avez besoin de l'application Xcode complète. Depuis le 28 avril 2026, App Store Connect n'accepte que les builds produits avec Xcode 26 ou plus récent, et le Xcode préinstallé sur votre serveur respecte cette règle. N'installez une autre version côte à côte avec xcodes que si votre projet en a besoin :
# Check the preinstalled Xcode
xcodebuild -version
# Xcode 27.2
# Optional: add other Xcode releases side by side with the xcodes CLI
brew install xcodes
xcodes list
# Install an older release next to the preinstalled one (asks for your Apple Account)
xcodes install 26.6
# Show the installed versions and their paths
xcodes installed
# e.g. /Applications/Xcode.app and /Applications/Xcode-26.6.0.app
# Set the default Xcode (sudo asks for your password)
# preinstalled Xcode; for another version, use the path from xcodes installed
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
Installer les simulateurs iOS et les outils de build
# Install the current iOS simulator runtime
xcodebuild -downloadPlatform iOS
# Verify simulator availability
xcrun simctl list runtimes
# Install additional build tools
brew install xcbeautify fastlane swiftlint
Étape 2 : Installer l'agent runner CircleCI
Le machine runner 3 de CircleCI connecte votre Mac mini à CircleCI : il reçoit les jobs et les exécute directement sur votre hôte macOS. Sur macOS, CircleCI recommande de l'installer avec son paquet Homebrew. C'est différent du container runner (qui ne fonctionne que sous Linux).
Choisir l'utilisateur qui exécute vos jobs
Le machine runner 3 exécute chaque job sous l'utilisateur macOS qui le démarre, avec le Homebrew, le trousseau et le Xcode de cet utilisateur. Installez-le et démarrez-le avec votre utilisateur administrateur, celui à qui appartient Homebrew, et non en root : Homebrew refuse de s'exécuter en root.
# Run the steps below as the user that will run CI jobs, not with sudo
whoami
# Homebrew must work for this user (prints /opt/homebrew)
brew --prefix
Installer le machine runner 3 avec Homebrew
# Add CircleCI's Homebrew tap and install machine runner 3
brew tap circleci-public/circleci
brew install circleci-runner
# Check that macOS accepts the binary notarized by CircleCI
spctl -a -vvv -t install "$(brew --prefix)/bin/circleci-runner"
# Expected: accepted, source=Notarized Developer ID,
# origin=Developer ID Application: Circle Internet Services Inc.
# Remove the quarantine attribute (asks for your macOS password)
sudo xattr -r -d com.apple.quarantine "$(brew --prefix)/bin/circleci-runner"
Configurer l'agent runner
Le paquet Homebrew crée le fichier de configuration. Vous aurez besoin de votre jeton d'authentification du runner depuis l'application web CircleCI (traité à l'étape 3). Pour l'instant, définissez le nom du runner et gardez un espace réservé pour le jeton :
# Open the configuration file created by the Homebrew package
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"
# Contents (the token comes in Step 3):
runner:
name: "mac-mini-m4-runner"
working_directory: "/Users/$USER/Library/com.circleci.runner/workdir"
cleanup_working_directory: true
api:
auth_token: "YOUR_RUNNER_TOKEN_HERE"
# The file will hold a secret: make it readable by you only
chmod 600 "$HOME/Library/Preferences/com.circleci.runner/config.yaml"
Préparer le service launchd pour un Mac sans écran
Le paquet Homebrew installe aussi un agent launchd, com.circleci.runner. Un agent démarre normalement à l'ouverture de session de votre utilisateur ; sur un Mac que vous ne joignez qu'en SSH, la configuration headless de CircleCI le déplace dans /Library/LaunchAgents pour qu'il se charge après un redémarrage. Démarrez-le à l'étape 3, une fois le jeton en place :
# The launchd agent installed by the Homebrew package
ls ~/Library/LaunchAgents/com.circleci.runner.plist
# Headless Mac reached over SSH only: move it to the per-user agents
# folder so it loads after a reboot (CircleCI's headless setup)
sudo mv ~/Library/LaunchAgents/com.circleci.runner.plist /Library/LaunchAgents/
Important : Le runner ne se connectera pas tant que config.yaml ne contient pas un jeton d'authentification valide. Générez-le à l'étape 3, ajoutez-le au fichier, puis démarrez le service.
Étape 3 : Configurer le runner dans le tableau de bord CircleCI
Vous devez maintenant enregistrer votre runner dans l'interface web CircleCI et générer un jeton d'authentification. Cela connecte votre Mac Mini à votre organisation CircleCI.
Créer une classe de ressource
Dans CircleCI, les runners auto-hébergés sont organisés par classes de ressources. Une classe de ressource est un label qui associe votre .circleci/config.yml à un ensemble spécifique de runners.
- Dans l'application web CircleCI, ouvrez Runners dans la barre latérale (vous devez être administrateur de l'organisation)
- Cliquez sur "Créer une classe de ressource"
- Définissez le Namespace avec le nom de votre organisation (ex. :
your-org) - Définissez le nom de la classe de ressource avec un nom descriptif (ex. :
mac-runner) - Cela crée un identifiant de classe de ressource :
your-org/mac-runner
Générer un jeton d'authentification du runner
- Cliquez sur "Save and continue" : CircleCI crée la classe de ressource et affiche son jeton d'authentification
- Copiez immédiatement le jeton et conservez-le en lieu sûr : il n'est affiché qu'une seule fois
- Perdu ? Créez-en un nouveau avec le CLI CircleCI :
circleci runner token create your-org/mac-runner mac-mini-m4
Ajouter votre jeton et démarrer le runner
# SSH back into your Mac mini
ssh admin@your-server-ip
# Replace YOUR_RUNNER_TOKEN_HERE with the resource class token
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"
# Start the service. Headless Mac (plist moved to /Library/LaunchAgents):
launchctl bootstrap user/$(id -u) /Library/LaunchAgents/com.circleci.runner.plist
launchctl enable user/$(id -u)/com.circleci.runner
launchctl kickstart -k user/$(id -u)/com.circleci.runner
# Or, from a desktop session (VNC), with the plist left in ~/Library/LaunchAgents:
# launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.circleci.runner.plist
# launchctl enable gui/$(id -u)/com.circleci.runner
# launchctl kickstart -k gui/$(id -u)/com.circleci.runner
# Verify the service, then read the runner log
launchctl print user/$(id -u)/com.circleci.runner
tail -20 "$HOME/Library/Logs/com.circleci.runner/runner.log"
Une fois connecté, le runner apparaît sous Runners dans l'application web CircleCI, et circleci runner instance list your-org/mac-runner l'affiche aussi. S'il n'apparaît pas dans les 60 secondes, vérifiez le fichier journal pour les messages d'erreur.
Utiliser le CLI CircleCI (alternative)
Vous pouvez également gérer les runners via le CLI CircleCI :
# Install the CircleCI CLI
brew install circleci
# Authenticate with CircleCI
circleci setup
# Create the namespace (once per organization)
circleci namespace create your-org --org-id YOUR_ORGANIZATION_ID
# Create the resource class and print its token
circleci runner resource-class create your-org/mac-runner \
"Mac mini M4 runner" --generate-token
# List the runners connected to this resource class
circleci runner instance list your-org/mac-runner
Étape 4 : Créer votre .circleci/config.yml pour les builds iOS
Créez un fichier .circleci/config.yml à la racine de votre dépôt. La différence clé avec une configuration CircleCI standard est l'utilisation de machine: true avec votre resource_class personnalisée pour cibler votre runner auto-hébergé.
version: 2.1
jobs:
build-and-test:
machine: true
resource_class: your-org/mac-runner
environment:
# Xcode for this job, without sudo
# (preinstalled Xcode; for another version, use the path from `xcodes installed`)
DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
SCHEME: "MyApp"
# Any device listed by: xcrun simctl list devices available
DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"
steps:
- checkout
- run:
name: Show the Xcode version
command: xcodebuild -version
# Caches live in $HOME, outside the job's working directory,
# so they survive cleanup_working_directory between jobs
- run:
name: Resolve Swift Package Dependencies
command: |
xcodebuild -resolvePackageDependencies \
-scheme "$SCHEME" \
-clonedSourcePackagesDirPath "$HOME/spm-cache"
- run:
name: Build the app
command: |
xcodebuild build \
-scheme "$SCHEME" \
-destination "generic/platform=iOS Simulator" \
-clonedSourcePackagesDirPath "$HOME/spm-cache" \
-derivedDataPath "$HOME/DerivedData/$SCHEME" \
| xcbeautify
# store_test_results needs JUnit XML: xcbeautify writes test-results/junit.xml
- run:
name: Run unit tests
command: |
xcodebuild test \
-scheme "$SCHEME" \
-destination "$DESTINATION" \
-clonedSourcePackagesDirPath "$HOME/spm-cache" \
-derivedDataPath "$HOME/DerivedData/$SCHEME" \
-resultBundlePath TestResults.xcresult \
| xcbeautify --report junit --report-path test-results
- store_test_results:
path: test-results
- store_artifacts:
path: TestResults.xcresult
destination: test-results
workflows:
ios-pipeline:
jobs:
- build-and-test:
filters:
branches:
only:
- main
- develop
Remarque : La valeur resource_class: your-org/mac-runner doit correspondre exactement à la classe de ressource que vous avez créée dans le tableau de bord CircleCI. Si elle ne correspond pas, les jobs resteront en file d'attente indéfiniment.
Étape 5 : Optimiser avec le cache et le parallélisme
L'un des plus grands avantages d'un runner auto-hébergé est le cache persistant. Comme le système de fichiers du runner est persistant, vous n'avez pas besoin de télécharger et restaurer les caches comme avec les ressources cloud CircleCI. Cependant, il existe des optimisations supplémentaires pour maximiser la vitesse de vos builds.
Exploiter le DerivedData persistant
Puisque le disque du runner persiste entre les builds, DerivedData est déjà mis en cache automatiquement. Utilisez un chemin cohérent :
# In your config.yml steps, always use a consistent DerivedData path:
- run:
name: Build with persistent cache
command: |
xcodebuild build \
-scheme "$SCHEME" \
-destination "$DESTINATION" \
-derivedDataPath ~/DerivedData/"$SCHEME" \
-clonedSourcePackagesDirPath ~/spm-cache \
| xcbeautify
# Periodically clean old DerivedData on the runner (cron job):
# 0 3 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +
Persistance de l'espace de travail entre les jobs
Utilisez les espaces de travail CircleCI pour transmettre les produits compilés à un job de test, qui peut s'exécuter sur un autre Mac de la même classe de ressource :
jobs:
build:
machine: true
resource_class: your-org/mac-runner
steps:
- checkout
- run:
name: Build for testing
command: |
xcodebuild build-for-testing \
-scheme "MyApp" \
-destination "generic/platform=iOS Simulator" \
-derivedDataPath DerivedData \
| xcbeautify
# Pass only the built products, not the whole DerivedData
- persist_to_workspace:
root: .
paths:
- DerivedData/Build/Products
test:
machine: true
resource_class: your-org/mac-runner
steps:
- attach_workspace:
at: .
- run:
name: Run the tests built by the previous job
command: |
xcodebuild test-without-building \
-xctestrun "$(ls DerivedData/Build/Products/*.xctestrun | head -n 1)" \
-destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
| xcbeautify --report junit --report-path test-results
- store_test_results:
path: test-results
workflows:
build-test:
jobs:
- build
- test:
requires:
- build
Exécution parallèle des tests
- run:
name: Run tests in parallel
command: |
# Xcode clones the simulator and runs test classes on up to 4 clones
xcodebuild test \
-scheme "MyApp" \
-destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
-parallel-testing-enabled YES \
-maximum-parallel-testing-workers 4 \
-derivedDataPath ~/DerivedData/MyApp \
| xcbeautify
Répartition des tests CircleCI
Pour les suites de tests volumineuses, la répartition des tests de CircleCI distribue les classes de test entre des tâches parallèles. Chaque tâche a besoin de son propre runner : parallelism: 3 demande donc trois Mac dans la classe de ressource ; sur un seul Mac, les tâches s'exécutent l'une après l'autre :
jobs:
test:
machine: true
resource_class: your-org/mac-runner
# One task per runner: 3 tasks need 3 Macs in this resource class
parallelism: 3
steps:
- checkout
- run:
name: Split test classes and run this task's share
command: |
# One XCTest class per file, named like the file (LoginTests.swift)
CLASSES=$(circleci tests glob "MyAppTests/**/*Tests.swift" \
| xargs -n1 basename | sed 's/\.swift$//' \
| circleci tests split)
# -only-testing takes Target/Class identifiers, not file paths
ONLY_TESTING=""
for CLASS in $CLASSES; do
ONLY_TESTING="$ONLY_TESTING -only-testing:MyAppTests/$CLASS"
done
xcodebuild test \
-scheme "MyApp" \
-destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
$ONLY_TESTING \
| xcbeautify --report junit --report-path test-results
- store_test_results:
path: test-results
Exemples de workflows
Voici des exemples de workflows complets, prêts pour la production, pour les scénarios CI/CD iOS courants.
Pipeline complet de build, test et déploiement iOS
version: 2.1
jobs:
lint:
machine: true
resource_class: your-org/mac-runner
steps:
- checkout
- run:
name: Run SwiftLint
command: swiftlint lint --reporter json > swiftlint-results.json || true
- store_artifacts:
path: swiftlint-results.json
build-and-test:
machine: true
resource_class: your-org/mac-runner
environment:
# Xcode for this job, without sudo
# (preinstalled Xcode; for another version, use the path from `xcodes installed`)
DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
steps:
- checkout
- run:
name: Resolve dependencies
command: |
xcodebuild -resolvePackageDependencies \
-scheme "MyApp" \
-clonedSourcePackagesDirPath ~/spm-cache
- run:
name: Build and test
command: |
xcodebuild test \
-scheme "MyApp" \
-destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
-clonedSourcePackagesDirPath ~/spm-cache \
-derivedDataPath ~/DerivedData/MyApp \
-resultBundlePath TestResults.xcresult \
-parallel-testing-enabled YES \
| xcbeautify --report junit --report-path test-results
- store_test_results:
path: test-results
- store_artifacts:
path: TestResults.xcresult
deploy-testflight:
machine: true
resource_class: your-org/mac-runner
environment:
DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
steps:
- checkout
- run:
name: Install dependencies
command: bundle install
# MATCH_PASSWORD and the App Store Connect API key variables
# (ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_CONTENT) come from a CircleCI
# context or the project's environment variables
- run:
name: Build and upload to TestFlight
command: bundle exec fastlane beta
workflows:
ios-pipeline:
jobs:
- lint
- build-and-test:
requires:
- lint
- deploy-testflight:
requires:
- build-and-test
filters:
branches:
only: main
Exemple d'intégration Fastlane
Si vous utilisez Fastlane pour votre automatisation de build, voici comment l'intégrer avec votre runner CircleCI auto-hébergé :
# Fastfile (fastlane/Fastfile)
default_platform(:ios)
platform :ios do
desc "Run tests"
lane :test do
scan(
scheme: "MyApp",
device: "iPhone 17",
derived_data_path: File.expand_path("~/DerivedData/MyApp"),
result_bundle: true,
output_directory: "./test_output",
# store_test_results reads JUnit XML
output_types: "junit",
output_files: "junit.xml"
)
end
desc "Build and push to TestFlight"
lane :beta do
# App Store Connect API key: no Apple ID password or 2FA on the runner
app_store_connect_api_key(
key_id: ENV["ASC_KEY_ID"],
issuer_id: ENV["ASC_ISSUER_ID"],
key_content: ENV["ASC_KEY_CONTENT"]
)
match(type: "appstore", readonly: true)
increment_build_number(
build_number: ENV["CIRCLE_BUILD_NUM"]
)
gym(
scheme: "MyApp",
export_method: "app-store",
derived_data_path: File.expand_path("~/DerivedData/MyApp")
)
pilot(skip_waiting_for_build_processing: true)
end
end
# .circleci/config.yml using Fastlane
version: 2.1
jobs:
fastlane-test:
machine: true
resource_class: your-org/mac-runner
steps:
- checkout
- run:
name: Install dependencies
command: bundle install
- run:
name: Run Fastlane tests
command: bundle exec fastlane test
- store_test_results:
path: ./test_output
- store_artifacts:
path: ./test_output
fastlane-deploy:
machine: true
resource_class: your-org/mac-runner
steps:
- checkout
- run:
name: Install dependencies
command: bundle install
- run:
name: Deploy to TestFlight
command: bundle exec fastlane beta
workflows:
ios-workflow:
jobs:
- fastlane-test
- fastlane-deploy:
requires:
- fastlane-test
filters:
branches:
only: main
Comparaison des performances
Voici une comparaison détaillée des performances et des coûts entre les ressources macOS cloud de CircleCI et un Mac Mini M4 auto-hébergé de My Remote Mac :
Benchmarks des temps de build
| Scénario | Mac Mini M4 auto-hébergé | CircleCI Cloud macOS | Amélioration |
|---|---|---|---|
| Build propre (app moyenne) | 5 min | 14 min | 2,8x plus rapide |
| Build incrémental | 1,5 min | 14 min (pas de cache) | 9,3x plus rapide |
| Résolution des dépendances SPM | 5 sec (cache sur disque) | 3-5 min (téléchargement à chaque fois) | ~60x plus rapide |
| Suite de tests unitaires (500 tests) | 2,5 min | 8 min | 3,2x plus rapide |
| Temps d'attente en file | 0 sec | 30 s - 5 min | Instantané |
Analyse des coûts mensuels
| Taille de l'équipe | Coût My Remote Mac | Builds/mois | Coût CircleCI Cloud | Économies mensuelles |
|---|---|---|---|---|
| Développeur solo | 85 $/mois | 100 builds (10 min moy.) | 120 $/mois | 35 $/mois |
| Petite équipe (5) | 85 $/mois | 500 builds (10 min moy.) | 600 $/mois | 515 $/mois |
| Équipe moyenne (15) | 229 $/mois (M4 Pro) | 1500 builds (10 min moy.) | 1 800 $/mois | 1 571 $/mois |
| Entreprise (50+) | 458 $/mois (2x M4 Pro) | 5000+ builds | 6 000+ $/mois | 5 542+ $/mois |
Prix My Remote Mac en USD, hors taxes.
En résumé : Au tarif CircleCI de la classe m4pro.medium (200 crédits, environ 0,12 $ par minute, en octobre 2026), un build de 10 minutes coûte environ 1,20 $ : un Mac mini M4 dédié à $85/mois (USD, HT) revient donc moins cher dès environ 71 builds par mois. Les caches préchauffés d'un Mac persistant réduisent aussi le temps d'attente de votre équipe à chaque build.
Résolution des problèmes courants
Le runner se déconnecte ou apparaît "Hors ligne"
Le runner peut perdre sa connexion après un problème réseau, un plantage ou un redémarrage. Démarré dans le domaine gui, il ne revient qu'à l'ouverture de session de son utilisateur ; la configuration headless de l'étape 2 évite ce cas. Vérifiez le service et son journal :
# Check the service (use gui/ instead of user/ if you started it
# from a desktop session)
launchctl print user/$(id -u)/com.circleci.runner
# View the runner log
tail -50 "$HOME/Library/Logs/com.circleci.runner/runner.log"
# Restart the service
launchctl kickstart -k user/$(id -u)/com.circleci.runner
# If the token was revoked, create a new one, put it in
# ~/Library/Preferences/com.circleci.runner/config.yaml and restart
circleci runner token create your-org/mac-runner mac-mini-m4
resource_class introuvable ou jobs bloqués en file d'attente
Si les jobs restent en file d'attente avec "Aucun runner correspondant trouvé", la classe de ressource dans votre configuration ne correspond pas au tableau de bord :
# Verify the exact resource class name in the CircleCI web app:
# Runners (sidebar) lists your resource classes
# The resource_class in .circleci/config.yml must match exactly:
# resource_class: your-org/mac-runner (case-sensitive!)
# Check your runner is online:
circleci runner instance list your-org/mac-runner
# Common mistakes:
# - Wrong namespace (org name vs personal namespace)
# - Typo in resource class name
# - Runner is offline or token is invalid
# - Using 'docker' executor instead of 'machine: true'
Erreurs de signature de code Xcode
La signature de code sur une machine CI nécessite une gestion soigneuse du trousseau. Le processus runner peut ne pas avoir accès au trousseau de session :
# Option 1: Use Fastlane Match (recommended)
# In your Fastfile:
match(type: "appstore", readonly: true)
# Option 2: Manual keychain management in your job steps
- run:
name: Setup code signing
command: |
# Decode and import the certificate
echo "$BUILD_CERTIFICATE_BASE64" | base64 --decode > /tmp/cert.p12
# Create a temporary keychain
security create-keychain -p "ci" /tmp/ci.keychain
security set-keychain-settings -lut 21600 /tmp/ci.keychain
security unlock-keychain -p "ci" /tmp/ci.keychain
# Import the certificate
security import /tmp/cert.p12 -P "$P12_PASSWORD" \
-A -t cert -f pkcs12 -k /tmp/ci.keychain
# Let codesign use the key without a GUI prompt
security set-key-partition-list -S apple-tool:,apple:,codesign: \
-s -k "ci" /tmp/ci.keychain
security list-keychain -d user -s /tmp/ci.keychain
# Install the provisioning profile (Xcode 16 and later location)
PROFILES=~/Library/Developer/Xcode/UserData/Provisioning\ Profiles
mkdir -p "$PROFILES"
echo "$PROVISIONING_PROFILE_BASE64" | base64 --decode \
> "$PROFILES/profile.mobileprovision"
Le simulateur ne démarre pas ou expire
Les simulateurs peuvent se retrouver dans un état incorrect sur les machines CI à longue durée de fonctionnement. Réinitialisez-les entre les builds :
# Add a pre-build step to clean simulators
- run:
name: Reset simulators
command: |
xcrun simctl shutdown all 2>/dev/null || true
xcrun simctl erase all 2>/dev/null || true
# If a specific runtime is missing, reinstall it:
xcodebuild -downloadPlatform iOS
# List available simulators
xcrun simctl list devices available
Espace disque insuffisant
Les builds Xcode génèrent des quantités importantes de données. Configurez un nettoyage automatique sur votre runner :
# Check available disk space
df -h /
# Clean DerivedData folders unused for a week
find ~/DerivedData ~/Library/Developer/Xcode/DerivedData \
-mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +
# Delete simulators the current Xcode no longer supports
xcrun simctl delete unavailable
# List simulator runtimes, then delete the ones you no longer test on
xcrun simctl runtime list
# xcrun simctl runtime delete <runtime-identifier>
# Clean Homebrew cache
brew cleanup --prune=7
# Set up a weekly cron job for automatic cleanup
(crontab -l 2>/dev/null; echo "0 4 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} + ; /opt/homebrew/bin/brew cleanup --prune=7") | crontab -