Zum Inhalt springen

So richten Sie einen CircleCI Self-Hosted Runner auf dem Mac Mini M4 ein

Vollständige Schritt-für-Schritt-Anleitung zur Installation und Konfiguration eines CircleCI Self-Hosted Machine Runners auf einem dedizierten Mac mini M4. Native Apple-Silicon-Leistung, persistentes Caching und bis zu 90 % günstiger als CircleCI-Cloud-macOS-Ressourcen.

CI/CD 35 Min. Lesezeit Aktualisiert im Oktober 2026

Warum einen Self-Hosted CircleCI Runner auf dem Mac verwenden?

CircleCI bietet cloudbasierte macOS-Ausführungsumgebungen, doch diese sind mit erheblichen Kosten und Einschränkungen verbunden. CircleCI rechnet macOS-Jobs in Credits ab: Die Resource Class m4pro.medium verbraucht 200 Credits pro Minute (etwa $0,12), m4pro.large 400 (etwa $0,24), Stand Oktober 2026. Für Teams mit häufigen iOS-Builds kann sich das schnell auf $300-$500 pro Monat oder mehr summieren.

Ein Self-Hosted Runner auf einem dedizierten Mac Mini M4 von MyRemoteMac eliminiert die Abrechnung pro Minute vollständig. Sie erhalten eine dedizierte Apple-Silicon-Maschine mit persistentem Speicher, warmen Caches und vollem Root-Zugriff für eine feste monatliche Gebühr ab $85/Monat. Hier ist ein detaillierter Vergleich:

Warum einen Self-Hosted CircleCI Runner auf dem Mac verwenden?
MyRemoteMac Self-Hosted CircleCI Cloud macOS
Kostenmodell $85/Mon. pauschal (unbegrenzte Minuten) 200 Credits/Min. bei m4pro.medium (~$0,12/Min.)
Architektur Physischer Apple-M4-Mac, 1:1 zugewiesen Virtuelle M4-Pro-Maschine (6 vCPU, 28 GB)
Build-Geschwindigkeit ~5 Min. (dasselbe Projekt) ~14 Min. (mittelgroßes iOS-Projekt)
Cache-Persistenz Persistent auf der Festplatte (sofort) Ephemer (muss bei jedem Job wiederhergestellt werden)
Wartezeit in der Warteschlange 0 Sek. (dedizierte Hardware) 30 Sek. - 5 Min. (je nach Plan)
Datenschutz / Datenkontrolle Dedizierte Maschine, volle Kontrolle Geteilte Infrastruktur
Individuelle Software Voller Root-Zugriff, beliebige Software Nur vorinstalliertes Image

Preise von My Remote Mac in USD, exkl. Steuern.

Wichtigster Vorteil: Mit einem persistenten Self-Hosted Runner bleiben DerivedData, Swift-Package-Manager-Caches und CocoaPods zwischen den Builds erhalten. Allein das kann die Build-Zeiten im Vergleich zu den ephemeren Cloud-macOS-Umgebungen von CircleCI, die jedes Mal bei null beginnen, um 50-70 % verkürzen. In Kombination mit der überlegenen Single-Thread-Leistung des M4-Chips werden Ihre iOS-Builds dramatisch schneller.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

  • Einen dedizierten Mac mini M4 Build Server von My Remote Mac (ab $85/Monat, USD, exkl. Steuern)
  • Eine CircleCI-Organisation, in der Sie Admin sind (Self-Hosted Runner gibt es in jedem Plan, auch im Free-Plan mit 5 gleichzeitigen Self-Hosted-Tasks, Stand Oktober 2026)
  • SSH-Zugang zu Ihrem Mac Mini (im Lieferumfang Ihres MyRemoteMac-Abonnements enthalten)
  • Einen Apple-Developer-Account (für Code-Signierung und Provisioning-Profile)
  • Grundkenntnisse in YAML, CircleCI-Konfiguration und Terminal-Befehlen

Schritt 1: Xcode prüfen und Abhängigkeiten installieren

Verbinden Sie sich zunächst per SSH mit Ihrem Mac Mini M4, mit den Anmeldedaten, die Sie beim Einrichten Ihres MyRemoteMac-Servers erhalten haben. Xcode, seine Command Line Tools und Homebrew sind bereits installiert, sodass Sie vor der Einrichtung des CircleCI Runners nur noch die Build-Werkzeuge ergänzen, die Ihre iOS-Pipeline braucht.

Per SSH verbinden

# 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

Homebrew und Xcode Command Line Tools prüfen

# 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

Xcode prüfen und weitere Versionen hinzufügen

Für iOS-Builds benötigen Sie die vollständige Xcode-Anwendung. Seit dem 28. April 2026 akzeptiert App Store Connect nur Builds, die mit Xcode 26 oder neuer erstellt wurden, und das auf Ihrem Server vorinstallierte Xcode erfüllt diese Vorgabe. Installieren Sie mit xcodes nur dann eine weitere Version parallel dazu, wenn Ihr Projekt sie braucht:

# 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

iOS-Simulatoren und Build-Tools installieren

# 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

Schritt 2: Den CircleCI Runner Agent installieren

CircleCI Machine Runner 3 verbindet Ihren Mac mini mit CircleCI: Er empfängt Jobs und führt sie direkt auf Ihrem macOS-Host aus. Unter macOS empfiehlt CircleCI die Installation über das Homebrew-Paket. Das unterscheidet sich vom Container Runner (der nur unter Linux funktioniert).

Den Benutzer wählen, der Ihre Jobs ausführt

Machine Runner 3 führt jeden Job als der macOS-Benutzer aus, der ihn startet, mit dessen Homebrew, Schlüsselbund und Xcode. Installieren und starten Sie ihn mit Ihrem Admin-Benutzer, dem Homebrew gehört, nicht als root: Homebrew verweigert die Ausführung als 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

Machine Runner 3 mit Homebrew installieren

# 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"

Den Runner Agent konfigurieren

Das Homebrew-Paket legt die Konfigurationsdatei an. Sie benötigen Ihr Runner-Authentifizierungs-Token aus der CircleCI-Web-App (in Schritt 3 behandelt). Legen Sie vorerst den Runner-Namen fest und lassen Sie einen Platzhalter für das Token:

# 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"

Den launchd-Dienst für einen Mac ohne Bildschirm vorbereiten

Das Homebrew-Paket installiert außerdem einen launchd-Agenten, com.circleci.runner. Ein Agent startet normalerweise, wenn sich Ihr Benutzer anmeldet; auf einem Mac, den Sie nur per SSH erreichen, verschiebt ihn das Headless-Setup von CircleCI nach /Library/LaunchAgents, damit er nach einem Neustart geladen wird. Starten Sie ihn in Schritt 3, sobald das Token eingetragen ist:

# 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/

Wichtig: Der Runner verbindet sich erst, wenn config.yaml ein gültiges Authentifizierungs-Token enthält. Erzeugen Sie es in Schritt 3, tragen Sie es in die Datei ein und starten Sie dann den Dienst.

Schritt 3: Den Runner im CircleCI-Dashboard konfigurieren

Nun müssen Sie Ihren Runner in der CircleCI-Weboberfläche registrieren und ein Authentifizierungs-Token generieren. Dies verbindet Ihren Mac Mini mit Ihrer CircleCI-Organisation.

Eine Resource Class erstellen

In CircleCI werden Self-Hosted Runner nach Resource Classes organisiert. Eine Resource Class ist ein Label, das Ihre .circleci/config.yml einem bestimmten Satz von Runnern zuordnet.

  1. Öffnen Sie in der CircleCI-Web-App Runners in der Seitenleiste (Sie müssen Organisations-Admin sein)
  2. Klicken Sie auf "Create Resource Class"
  3. Setzen Sie den Namespace auf Ihren Organisationsnamen (z. B. your-org)
  4. Setzen Sie den Namen der Resource Class auf etwas Aussagekräftiges (z. B. mac-runner)
  5. Dadurch wird ein Resource-Class-Bezeichner erstellt: your-org/mac-runner

Ein Runner-Authentifizierungs-Token generieren

  1. Klicken Sie auf "Save and continue": CircleCI erstellt die Resource Class und zeigt ihr Authentifizierungs-Token an
  2. Kopieren Sie das Token sofort und bewahren Sie es sicher auf: Es wird nur einmal angezeigt
  3. Verloren? Erstellen Sie mit der CircleCI CLI ein neues: circleci runner token create your-org/mac-runner mac-mini-m4

Token eintragen und den Runner starten

# 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"

Nach der Verbindung erscheint der Runner unter Runners in der CircleCI-Web-App, und circleci runner instance list your-org/mac-runner zeigt ihn ebenfalls an. Wenn er nicht innerhalb von 60 Sekunden erscheint, überprüfen Sie die Protokolldatei auf Fehlermeldungen.

Verwendung der CircleCI CLI (Alternative)

Sie können Runner auch über die CircleCI CLI verwalten:

# 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

Schritt 4: Ihre .circleci/config.yml für iOS-Builds erstellen

Erstellen Sie eine .circleci/config.yml-Datei im Stammverzeichnis Ihres Repositorys. Der wesentliche Unterschied zu einer Standard-CircleCI-Konfiguration ist die Verwendung von machine: true mit Ihrer benutzerdefinierten resource_class, um Ihren Self-Hosted Runner anzusprechen.

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

Hinweis: Der Wert resource_class: your-org/mac-runner muss exakt mit der Resource Class übereinstimmen, die Sie im CircleCI-Dashboard erstellt haben. Stimmt er nicht überein, bleiben Jobs unbegrenzt in der Warteschlange.

Schritt 5: Mit Caching und Parallelisierung optimieren

Einer der größten Vorteile eines Self-Hosted Runners ist das persistente Caching. Da das Dateisystem des Runners persistent ist, müssen Sie Caches nicht wie bei CircleCI-Cloud-Ressourcen hoch- und herunterladen. Es gibt jedoch zusätzliche Optimierungen, um Ihre Build-Geschwindigkeit zu maximieren.

Persistente DerivedData nutzen

Da die Runner-Festplatte zwischen den Builds persistent bleibt, sind DerivedData bereits automatisch zwischengespeichert. Verwenden Sie einen konsistenten Pfad:

# 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 {} +

Workspace-Persistenz zwischen Jobs

Verwenden Sie CircleCI-Workspaces, um die gebauten Produkte an einen Test-Job weiterzugeben, der auf einem anderen Mac derselben Resource Class laufen kann:

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

Parallele Testausführung

- 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

CircleCI Test-Splitting

Bei großen Test-Suites verteilt das Test-Splitting von CircleCI die Testklassen auf parallele Tasks. Jeder Task braucht einen eigenen Runner, daher erfordert parallelism: 3 drei Macs in der Resource Class; auf einem einzigen Mac laufen die Tasks nacheinander:

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

Workflow-Beispiele

Hier sind vollständige, produktionsreife Workflow-Beispiele für gängige iOS-CI/CD-Szenarien.

Vollständige iOS-Build-, Test- und Deploy-Pipeline

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

Fastlane-Integrationsbeispiel

Wenn Sie Fastlane für Ihre Build-Automatisierung verwenden, erfahren Sie hier, wie Sie es in Ihren CircleCI Self-Hosted Runner integrieren:

# 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

Performance-Vergleich

Hier ist ein detaillierter Performance- und Kostenvergleich zwischen CircleCI-Cloud-macOS-Ressourcen und einem Self-Hosted Mac Mini M4 von MyRemoteMac:

Build-Zeit-Benchmarks

Build-Zeit-Benchmarks
Self-Hosted Mac Mini M4 CircleCI Cloud macOS Verbesserung
Clean-Build (mittelgroße App) 5 Min. 14 Min. 2,8x schneller
Inkrementeller Build 1,5 Min. 14 Min. (kein Cache) 9,3x schneller
SPM-Abhängigkeitsauflösung 5 Sek. (auf der Festplatte zwischengespeichert) 3-5 Min. (jedes Mal Download) ~60x schneller
Unit-Test-Suite (500 Tests) 2,5 Min. 8 Min. 3,2x schneller
Wartezeit in der Warteschlange 0 Sek. 30 Sek. - 5 Min. Sofort

Monatliche Kostenanalyse

Monatliche Kostenanalyse
Teamgröße MyRemoteMac-Kosten Builds/Monat CircleCI-Cloud-Kosten Monatliche Ersparnis
Einzelentwickler $85/Mon. 100 Builds (Ø 10 Min.) $120/Mon. $35/Mon.
Kleines Team (5) $85/Mon. 500 Builds (Ø 10 Min.) $600/Mon. $515/Mon.
Mittleres Team (15) $229/Mon. (M4 Pro) 1500 Builds (Ø 10 Min.) $1.800/Mon. $1.571/Mon.
Enterprise (50+) $458/Mon. (2x M4 Pro) 5000+ Builds $6.000+/Mon. $5.542+/Mon.

Preise von My Remote Mac in USD, exkl. Steuern.

Fazit: Zum CircleCI-Tarif der Klasse m4pro.medium (200 Credits, etwa $0,12 pro Minute, Stand Oktober 2026) kostet ein 10-minütiger Build etwa $1,20. Ein dedizierter Mac mini M4 für $85/Monat (USD, exkl. Steuern) ist daher ab etwa 71 Builds pro Monat günstiger. Warme Caches auf einem persistenten Mac verkürzen zudem die Wartezeit Ihres Teams bei jedem Build.

Häufige Probleme beheben

Runner trennt die Verbindung oder wird als "Offline" angezeigt

Der Runner kann nach einem Netzwerkproblem, einem Absturz oder einem Neustart die Verbindung verlieren. In der gui-Domain gestartet, kommt er erst zurück, wenn sich sein Benutzer anmeldet; das Headless-Setup aus Schritt 2 vermeidet das. Prüfen Sie den Dienst und sein Protokoll:

# 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 nicht gefunden oder Jobs bleiben in der Warteschlange hängen

Wenn Jobs mit "No matching runner found" in der Warteschlange bleiben, stimmt die Resource Class in Ihrer Konfiguration nicht mit dem Dashboard überein:

# 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'

Xcode-Code-Signing-Fehler

Die Code-Signierung auf einer CI-Maschine erfordert eine sorgfältige Verwaltung des Schlüsselbunds. Der Runner-Prozess hat möglicherweise keinen Zugriff auf den Login-Schlüsselbund:

# 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"

Simulator startet nicht oder es kommt zu einem Timeout

Simulatoren können auf langlaufenden CI-Maschinen in einen fehlerhaften Zustand geraten. Setzen Sie sie zwischen den Builds zurück:

# 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

Speicherplatz wird knapp

Xcode-Builds erzeugen erhebliche Datenmengen. Richten Sie eine automatische Bereinigung auf Ihrem Runner ein:

# 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 -

Häufig gestellte Fragen

Wie viel kostet ein CircleCI Self-Hosted Runner auf dem Mac Mini M4?
Ein dedizierter Mac mini M4 von My Remote Mac beginnt bei $85/Monat (USD, exkl. Steuern) mit unbegrenzten Build-Minuten, und CircleCI berechnet auf Self-Hosted Runnern keine Build-Minuten. Die Cloud-macOS-Jobs von CircleCI kosten in der Klasse m4pro.medium etwa $0,12 pro Minute (200 Credits zu je $0,0006, Stand Oktober 2026), grob $300-500/Monat für aktive Teams. Mit Ihrem eigenen Runner bleiben die Kosten unabhängig vom Build-Volumen vorhersehbar.
Kann ich einen CircleCI Self-Hosted Runner für iOS- und macOS-Builds verwenden?
Ja. Ein Self-Hosted Runner auf einem Mac Mini M4 kann jeden macOS-Workload ausführen, einschließlich iOS-Builds, macOS-App-Builds, Swift-Paket-Tests, Xcode-UI-Tests und Fastlane-Automatisierung. Da er nativ auf Apple Silicon läuft, sind Builds schneller als auf emulierten oder Intel-basierten Cloud-Runnern.
Was ist der Unterschied zwischen CircleCI Machine Runner und Container Runner?
Der CircleCI Machine Runner führt Jobs direkt auf dem Betriebssystem des Host-Rechners aus, was für macOS/iOS-Builds erforderlich ist, die Xcode, Simulatoren und Apple-Frameworks benötigen. Der Container Runner führt Jobs in Docker-Containern aus und ist nur unter Linux verfügbar. Für Mac-Builds müssen Sie den Machine Runner verwenden.
Wie halte ich meinen CircleCI Self-Hosted Runner aktuell?
Machine Runner 3 aktualisiert sich nicht selbst: Mit dem Homebrew-Paket entscheiden Sie, wann Sie mit brew upgrade circleci-runner aktualisieren, und starten danach den Dienst neu. Prüfen Sie monatlich das Runner-Changelog und halten Sie auch Xcode und macOS aktuell.
Ist ein Self-Hosted Runner schneller als CircleCI-Cloud-macOS?
Ja, typischerweise 2-3x schneller bei Clean-Builds und bis zu 9x schneller bei inkrementellen Builds. CircleCI führt jeden Cloud-macOS-Job in einer frischen virtuellen M4-Pro-Maschine aus, daher müssen DerivedData und Paket-Caches jedes Mal wiederhergestellt werden. Ein Self-Hosted Mac mini M4 ist eine physische Maschine, die nur Ihnen gehört, mit persistenten DerivedData- und SPM-Caches und ohne Warten auf den Start einer Cloud-Maschine.
Kann ich mehrere CircleCI-Jobs gleichzeitig auf einem Mac Mini ausführen?
Nicht mit einem einzigen Runner. CircleCI unterstützt einen Machine Runner pro Maschine, und jeder Runner nimmt einen Job nach dem anderen an, sodass Jobs für dieselbe Resource Class warten, bis der Mac frei ist. Um Jobs parallel auszuführen, fügen Sie pro zusätzlichem gleichzeitigem Job einen Mac hinzu und registrieren ihn in derselben Resource Class: CircleCI gibt jeden wartenden Job an einen freien Runner, innerhalb des Limits Ihres Plans für gleichzeitige Self-Hosted-Tasks (5 im Free-Plan, 20 im Performance-Plan, Stand Oktober 2026). Innerhalb eines Jobs kann Xcode Tests weiterhin parallel auf mehreren Simulatoren ausführen. Für schwerere Jobs bietet der Mac mini M4 Pro (12-Kern-CPU, 24 GB, ab $229/Monat, USD, exkl. Steuern) mehr Reserven.

Starten Sie mit einem Mac Mini M4 für Ihre CircleCI-Pipelines

Setzen Sie einen dedizierten Mac Mini M4 als Ihren CircleCI Self-Hosted Runner ein. Unbegrenzte Build-Minuten ab $85/Monat.

Preise von My Remote Mac in USD, exkl. Steuern.

Mehr Details gesucht?

Durchsuchen Sie die vollständige Dokumentation für Schritt-für-Schritt-Anleitungen, Konfigurationsreferenzen und Fehlerbehebung.

Dokumentation öffnen →