Aller au contenu

Comment configurer un runner CircleCI auto-hébergé sur Mac Mini M4

Guide complet étape par étape pour installer et configurer un machine runner CircleCI auto-hébergé sur un Mac mini M4 dédié. Performances Apple Silicon natives, cache persistant et jusqu'à 90 % moins cher que les ressources macOS cloud de CircleCI.

CI/CD 35 min de lecture Mis à jour en octobre 2026

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 :

Pourquoi utiliser un runner CircleCI auto-hébergé sur Mac ?
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.

  1. Dans l'application web CircleCI, ouvrez Runners dans la barre latérale (vous devez être administrateur de l'organisation)
  2. Cliquez sur "Créer une classe de ressource"
  3. Définissez le Namespace avec le nom de votre organisation (ex. : your-org)
  4. Définissez le nom de la classe de ressource avec un nom descriptif (ex. : mac-runner)
  5. Cela crée un identifiant de classe de ressource : your-org/mac-runner

Générer un jeton d'authentification du runner

  1. Cliquez sur "Save and continue" : CircleCI crée la classe de ressource et affiche son jeton d'authentification
  2. Copiez immédiatement le jeton et conservez-le en lieu sûr : il n'est affiché qu'une seule fois
  3. 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

Benchmarks des temps de build
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

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 -

Questions fréquentes

Combien coûte un runner CircleCI auto-hébergé sur Mac Mini M4 ?
Un Mac mini M4 dédié chez My Remote Mac commence à $85/mois (USD, HT) avec des minutes de build illimitées, et CircleCI ne facture pas à la minute de build sur les runners auto-hébergés. Les jobs macOS cloud de CircleCI coûtent environ 0,12 $ par minute en classe m4pro.medium (200 crédits à 0,0006 $ chacun, en octobre 2026), soit environ 300 à 500 $/mois pour les équipes actives. Avec votre propre runner, les coûts restent prévisibles quel que soit le volume de builds.
Puis-je utiliser un runner CircleCI auto-hébergé pour les builds iOS et macOS ?
Oui. Un runner auto-hébergé sur un Mac Mini M4 peut exécuter n'importe quelle charge de travail macOS, y compris les builds iOS, les builds d'applications macOS, les tests de paquets Swift, les tests UI Xcode et l'automatisation Fastlane. Comme il s'exécute nativement sur Apple Silicon, les builds sont plus rapides que sur des runners cloud émulés ou basés sur Intel.
Quelle est la différence entre le machine runner et le container runner de CircleCI ?
Le machine runner de CircleCI exécute les jobs directement sur le système d'exploitation de la machine hôte, ce qui est nécessaire pour les builds macOS/iOS qui ont besoin de Xcode, des simulateurs et des frameworks Apple. Le container runner exécute les jobs dans des conteneurs Docker et n'est disponible que sur Linux. Pour les builds Mac, vous devez utiliser le machine runner.
Comment maintenir mon runner CircleCI auto-hébergé à jour ?
Le machine runner 3 ne se met pas à jour tout seul : avec le paquet Homebrew, vous choisissez quand le mettre à jour en lançant brew upgrade circleci-runner, puis vous redémarrez le service. Consultez le changelog du runner chaque mois et maintenez aussi Xcode et macOS à jour.
Un runner auto-hébergé est-il plus rapide que les runners macOS cloud de CircleCI ?
Oui, généralement 2 à 3 fois plus rapide pour les builds propres et jusqu'à 9 fois plus rapide pour les builds incrémentaux. CircleCI exécute chaque job macOS cloud dans une machine virtuelle M4 Pro neuve, si bien que DerivedData et les caches de paquets doivent être restaurés à chaque fois. Un Mac mini M4 auto-hébergé est une machine physique qui vous est dédiée, avec des caches DerivedData et SPM persistants et sans attendre le démarrage d'une machine cloud.
Puis-je exécuter plusieurs jobs CircleCI simultanément sur un seul Mac Mini ?
Pas avec un seul runner. CircleCI prend en charge un seul machine runner par machine, et chaque runner traite un job à la fois : les jobs envoyés à la même classe de ressource attendent que le Mac soit libre. Pour exécuter des jobs en parallèle, ajoutez un Mac par job simultané supplémentaire et enregistrez-le dans la même classe de ressource : CircleCI confie chaque job en attente à un runner libre, dans la limite de tâches auto-hébergées simultanées de votre offre (5 en Free, 20 en Performance, en octobre 2026). Au sein d'un job, Xcode peut toujours exécuter les tests en parallèle sur plusieurs simulateurs. Pour des jobs plus lourds, le Mac mini M4 Pro (CPU 12 cœurs, 24 Go, dès $229/mois, USD, HT) offre plus de marge.

Démarrez avec un Mac Mini M4 pour vos pipelines CircleCI

Déployez un Mac Mini M4 dédié comme runner CircleCI auto-hébergé. Minutes de build illimitées à partir de 85 $/mois.

Prix My Remote Mac en USD, hors taxes.

Besoin de plus de détails ?

Parcourez la documentation complète : guides pas à pas, références de configuration et dépannage.

Ouvrir la documentation →