Zum Inhalt springen

GitHub Actions Self-Hosted Runner auf Mac Mini M4 einrichten

Schritt-für-Schritt-Anleitung zur Einrichtung eines GitHub Actions Self-Hosted Runners auf einem dedizierten Mac Mini M4. Schnellere iOS-Builds, nativ auf Apple Silicon und bis zu 6,7x günstiger als GitHub-gehostete macOS-Runner.

CI/CD 30 Min. Lesezeit Aktualisiert im Oktober 2026

Warum einen Self-Hosted Mac Runner verwenden?

GitHub-gehostete macOS-Runner sind praktisch, werden aber pro Minute abgerechnet, sodass die Kosten mit Ihrem Build-Volumen steigen. Bei 0,062 $ pro Minute (Preis des Standard-macOS-Runners von GitHub, Stand Oktober 2026) zahlt ein Team, das 75 Stunden Builds pro Monat ausführt, rund 279 $. Minuten auf Self-Hosted Runnern berechnet GitHub nicht, daher kostet ein dedizierter Mac mini M4 von My Remote Mac pauschal 85 $/Monat (USD, exkl. Steuern) ohne Abrechnung pro Minute und bietet Ihnen die gleiche (oder bessere) Hardware zu einem Bruchteil der Kosten.

Warum einen Self-Hosted Mac Runner verwenden?
My Remote Mac Self-Hosted GitHub-gehosteter Runner
Kosten 85 $/Monat (keine Abrechnung pro Minute) 0,062 $/Min. (~279 $/Monat für 75 Std.)
Architektur Apple M4, physischer Mac, 1:1 zugewiesen Apple-M1-VM, 3 Kerne, 7 GB RAM (Standard-Runner)
Build-Geschwindigkeit ~4 Min. (gleiches Projekt) ~12 Min. (mittleres Projekt)
Persistenter Cache Ja (persistente Festplatte) Nein (flüchtig)
Individuelle Software Voller Root-Zugriff Eingeschränkt
Gleichzeitige Jobs 1 Job pro Runner; für mehr Kapazität Runner oder Macs hinzufügen 5 (Free, Pro, Team) / 50 (Enterprise)

Preise von My Remote Mac in USD, exkl. Steuern. GitHub-Angaben: Standard-macOS-Runner zu 0,062 $ pro Minute laut GitHub-Preisdokumentation, Stand Oktober 2026.

Wichtigster Vorteil: Da der Runner persistent ist, bleiben DerivedData, SPM-Caches und CocoaPods zwischen Builds erhalten. Allein das kann die Build-Zeiten um 50-70 % gegenüber flüchtigen GitHub-gehosteten Runnern verkürzen, die jedes Mal von vorn beginnen.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

  • Einen dedizierten Mac mini M4 Build Server von My Remote Mac (ab 85 $/Monat, USD, exkl. Steuern)
  • Ein GitHub-Konto mit Admin-Zugriff auf Ihr Repository oder Ihre Organisation
  • SSH-Zugriff auf Ihren Mac Mini (im My-Remote-Mac-Abonnement enthalten)
  • Ein Apple Developer-Konto (für Code-Signierung und Provisioning-Profile)
  • Grundkenntnisse in YAML und Terminal-Befehlen

Schritt 1: Per SSH mit Ihrem Mac Mini verbinden und Xcode prüfen

Verbinden Sie sich zunächst per SSH mit Ihrem Mac Mini M4. Sie haben Ihre Zugangsdaten bei der Einrichtung Ihres My-Remote-Mac-Servers erhalten.

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

# Check the macOS version
sw_vers

Xcode Command Line Tools prüfen

# 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

# Homebrew is preinstalled too (used below to add xcodes):
# put it on your PATH once per account
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version

Xcode prüfen und weitere Versionen hinzufügen

Xcode, seine Command Line Tools und Homebrew sind auf jedem My-Remote-Mac-Server vorinstalliert. Prüfen Sie die aktive Version und installieren Sie bei Bedarf weitere Versionen parallel mit xcodes:

# Check the preinstalled Xcode
xcodebuild -version
# Xcode 27.2

# Optional: add other Xcode releases side by side with the xcodes CLI
brew install xcodes

# List available Xcode versions
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 active Xcode (interactive SSH session: 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 installieren

# Install the iOS simulator runtime that matches your Xcode
xcodebuild -downloadPlatform iOS

# Verify simulator availability
xcrun simctl list runtimes
xcrun simctl list devices available

Schritt 2: Den GitHub Actions Runner installieren

Laden wir nun den GitHub Actions Runner-Agenten herunter und konfigurieren ihn. Navigieren Sie zu Ihrem Repository auf GitHub, gehen Sie zu Settings > Actions > Runners > New self-hosted runner und wählen Sie macOS + ARM64.

Herunterladen und konfigurieren

# Create a directory for the runner
mkdir -p ~/actions-runner && cd ~/actions-runner

# Download the latest runner package (macOS ARM64). The same commands, with the
# current version and its checksum, are shown on Settings > Actions > Runners >
# New self-hosted runner
RUNNER_VERSION=$(curl -fsSL https://api.github.com/repos/actions/runner/releases/latest \
  | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
curl -o "actions-runner-osx-arm64-${RUNNER_VERSION}.tar.gz" -L \
  "https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-osx-arm64-${RUNNER_VERSION}.tar.gz"

# Extract the package
tar xzf "actions-runner-osx-arm64-${RUNNER_VERSION}.tar.gz"

# Configure the runner
# Replace YOUR_TOKEN with the token from GitHub Settings
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO \
  --token YOUR_TOKEN \
  --name "mac-mini-m4-runner" \
  --labels "self-hosted,macOS,ARM64,M4" \
  --work "_work"

# Test the runner interactively first
./run.sh

Als persistenten launchd-Dienst installieren

Den Agenten interaktiv auszuführen, ist zum Testen in Ordnung, aber für den Produktivbetrieb muss er automatisch starten und nach einem Absturz neu starten. GitHub stellt ein integriertes Dienst-Installationsskript für macOS bereit:

# Install as a launchd service (a LaunchAgent; no sudo on macOS)
cd ~/actions-runner
./svc.sh install

# Start the service
./svc.sh start

# Check the service status
./svc.sh status

# View the launchd plist (for reference)
cat ~/Library/LaunchAgents/actions.runner.*.plist

Der Dienst startet jetzt bei jeder Anmeldung des Runner-Benutzers und startet den Runner neu, wenn der Prozess abstürzt. Ein LaunchAgent startet nicht von selbst beim Booten: Aktivieren Sie auf einem headless Mac die automatische Anmeldung für diesen Benutzer (Systemeinstellungen > Benutzer & Gruppen; nicht verfügbar, solange FileVault aktiv ist), damit der Runner nach einem Neustart wieder online ist. Sie können überprüfen, ob der Runner als "Idle" auf der Seite Settings > Actions > Runners Ihres GitHub-Repositorys erscheint.

Runner für mehrere Repositories konfigurieren (Organisationsebene)

# For an organization-level runner, use the organization URL:
./config.sh --url https://github.com/YOUR_ORG \
  --token YOUR_ORG_TOKEN \
  --name "mac-mini-m4-org-runner" \
  --labels "self-hosted,macOS,ARM64,M4" \
  --runnergroup "Default" \
  --work "_work"

# This allows ALL repositories in your organization to use this runner

Schritt 3: Ihren iOS-Build-Workflow erstellen

Erstellen Sie eine Workflow-Datei in Ihrem Repository unter .github/workflows/ios-build.yml. Dieser Workflow läuft auf Ihrem Self-Hosted Mac Mini M4 Runner.

name: iOS Build & Test

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64, M4]

    # bash -eo pipefail: a failing xcodebuild fails the step even when piped to xcbeautify
    defaults:
      run:
        shell: bash

    env:
      SCHEME: "MyApp"
      # Any device listed by: xcrun simctl list devices available
      DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"
      # Pick the Xcode for this job without sudo
      # (preinstalled Xcode; for another version, use the path from xcodes installed)
      DEVELOPER_DIR: /Applications/Xcode.app/Contents/Developer
      # Caches sit next to the checkout: actions/checkout cleans the checkout
      # (git clean -ffdx) on every run, but not its parent folder
      DERIVED_DATA: ${{ github.workspace }}/../DerivedData
      SPM_CACHE: ${{ github.workspace }}/../SourcePackages

    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Show the selected Xcode
        run: xcodebuild -version

      - name: Resolve Swift Package Dependencies
        run: |
          xcodebuild -resolvePackageDependencies \
            -scheme "$SCHEME" \
            -clonedSourcePackagesDirPath "$SPM_CACHE"

      - name: Install xcbeautify
        run: command -v xcbeautify >/dev/null || brew install xcbeautify

      - name: Build the app
        run: |
          xcodebuild build \
            -scheme "$SCHEME" \
            -destination "$DESTINATION" \
            -clonedSourcePackagesDirPath "$SPM_CACHE" \
            -derivedDataPath "$DERIVED_DATA" \
            | xcbeautify

      - name: Run unit tests
        run: |
          xcodebuild test \
            -scheme "$SCHEME" \
            -destination "$DESTINATION" \
            -clonedSourcePackagesDirPath "$SPM_CACHE" \
            -derivedDataPath "$DERIVED_DATA" \
            -resultBundlePath TestResults.xcresult \
            | xcbeautify

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: test-results
          path: TestResults.xcresult

Code-Signierung für Release-Builds hinzufügen

Für TestFlight- oder App-Store-Deployments fügen Sie Schritte zur Code-Signierung hinzu. Speichern Sie Ihre Zertifikate und Provisioning-Profile als GitHub Secrets:

  deploy:
    needs: build
    runs-on: [self-hosted, macOS, ARM64, M4]
    if: github.ref == 'refs/heads/main'

    env:
      # Same Xcode as the build job (App Store Connect requires Xcode 26 or later)
      DEVELOPER_DIR: /Applications/Xcode.app/Contents/Developer

    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Install certificate and provisioning profile
        env:
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}
          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
        run: |
          # Create a temporary keychain
          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
          security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
          security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
          security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH

          # Import certificate
          CERTIFICATE_PATH=$RUNNER_TEMP/build_certificate.p12
          echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $CERTIFICATE_PATH
          security import $CERTIFICATE_PATH -P "$P12_PASSWORD" \
            -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
          security list-keychain -d user -s $KEYCHAIN_PATH

          # Install provisioning profile (the folder Xcode 16 and later read)
          PP_PATH=$RUNNER_TEMP/build_pp.mobileprovision
          echo -n "$BUILD_PROVISION_PROFILE_BASE64" | base64 --decode -o $PP_PATH
          mkdir -p ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles
          cp $PP_PATH ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles

      - name: Build for distribution
        run: |
          xcodebuild archive \
            -scheme "MyApp" \
            -archivePath DerivedData/MyApp.xcarchive \
            -destination "generic/platform=iOS" \
            CODE_SIGN_STYLE=Manual

      - name: Export IPA
        run: |
          xcodebuild -exportArchive \
            -archivePath DerivedData/MyApp.xcarchive \
            -exportOptionsPlist ExportOptions.plist \
            -exportPath DerivedData/Export

      - name: Upload to TestFlight
        env:
          APP_STORE_CONNECT_API_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
          APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
        run: |
          # altool reads the key from ~/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8
          xcrun altool --upload-app \
            -f DerivedData/Export/MyApp.ipa \
            -t ios \
            --apiKey $APP_STORE_CONNECT_API_KEY \
            --apiIssuer $APP_STORE_CONNECT_ISSUER_ID

      # The runner is persistent: remove the signing files at the end of every job
      - name: Clean up keychain and provisioning profile
        if: ${{ always() }}
        run: |
          security delete-keychain $RUNNER_TEMP/app-signing.keychain-db || true
          rm -f ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles/build_pp.mobileprovision

Schritt 4: Performance optimieren

Einer der größten Vorteile eines Self-Hosted Runners ist persistentes Caching. Hier sind die wichtigsten Optimierungen, um das Maximum aus Ihrem Mac Mini M4 herauszuholen.

DerivedData-Caching aktivieren

Da der Runner persistent ist, bleibt DerivedData zwischen Builds erhalten. Verwenden Sie einen konsistenten DerivedData-Pfad:

# In your workflow, keep DerivedData next to the checkout (job env, as above):
#   DERIVED_DATA: ${{ github.workspace }}/../DerivedData
#   ... -derivedDataPath "$DERIVED_DATA"
# Each repository then gets ~/actions-runner/_work/<repo>/DerivedData

# On the runner, remove the DerivedData of repositories not built for 7 days
# (cron job every Sunday at 03:00, keeps your existing crontab entries)
(crontab -l 2>/dev/null; echo '0 3 * * 0 find "$HOME"/actions-runner/_work/*/DerivedData -maxdepth 0 -type d -mtime +7 -exec rm -rf {} +') \
  | crontab -

SPM-Pakete cachen

# Use clonedSourcePackagesDirPath to keep SPM packages on disk
# (SPM_CACHE points outside the checkout, as in the workflow above)
xcodebuild build \
  -scheme "MyApp" \
  -clonedSourcePackagesDirPath "$SPM_CACHE" \
  -derivedDataPath "$DERIVED_DATA"

# This avoids re-downloading packages on every build

Parallele Testausführung

# Run tests in parallel across multiple simulators
# (devices from: xcrun simctl list devices available)
set -o pipefail
xcodebuild test \
  -scheme "MyApp" \
  -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
  -destination "platform=iOS Simulator,name=iPhone 18 Pro,OS=latest" \
  -parallel-testing-enabled YES \
  -maximum-parallel-testing-workers 4 \
  -derivedDataPath "$DERIVED_DATA" \
  | xcbeautify

xcbeautify für bessere Logs installieren

# xcbeautify formats Xcode output for CI environments
brew install xcbeautify

# Use it by piping xcodebuild output (pipefail keeps xcodebuild's exit status):
set -o pipefail && xcodebuild build -scheme "MyApp" | xcbeautify

Häufige Probleme beheben

Runner wird in GitHub als "Offline" angezeigt

Das bedeutet in der Regel, dass der launchd-Dienst nicht läuft. Überprüfen Sie den Dienststatus und die Logs:

# Check service status
./svc.sh status

# View logs
cat ~/actions-runner/_diag/Runner_*.log | tail -50

# Restart the service
./svc.sh stop
./svc.sh start

Code-Signierung schlägt fehl mit "No signing certificate"

Der launchd-Dienst läuft unter einem anderen Benutzerkontext. Stellen Sie sicher, dass der Schlüsselbund zugänglich ist:

# Ensure the login keychain is unlocked for the runner user
security unlock-keychain -p "YOUR_PASSWORD" ~/Library/Keychains/login.keychain-db

# Or use a dedicated keychain in your workflow (recommended)
security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
security default-keychain -s build.keychain
security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain

Simulator startet nicht

Simulatoren bleiben manchmal hängen. Setzen Sie sie zwischen Builds zurück:

# Shutdown all running simulators
xcrun simctl shutdown all

# Erase all simulator data (nuclear option)
xcrun simctl erase all

# Boot a specific simulator
xcrun simctl boot "iPhone 17"

Speicherplatz wird knapp

Xcode-Builds erzeugen viele Daten. Richten Sie eine automatische Bereinigung ein:

# Clean old DerivedData
rm -rf ~/Library/Developer/Xcode/DerivedData/*

# Remove simulators whose runtime is no longer installed
xcrun simctl delete unavailable

# Clean Homebrew cache
brew cleanup --prune=7

# Remove old Xcode archives
rm -rf ~/Library/Developer/Xcode/Archives/*

Kostenanalyse

Hier ist ein detaillierter Kostenvergleich für verschiedene Teamgrößen und Build-Volumina:

Kostenanalyse
Teamgröße Kosten bei My Remote Mac Builds/Monat GitHub-gehostete Kosten Monatliche Ersparnis
Einzelentwickler 85 $/Monat 100 Builds (Ø 10 Min.) 62 $/Monat Keine (kostet 23 $/Monat mehr)
Kleines Team (5) 85 $/Monat 500 Builds (Ø 10 Min.) 310 $/Monat 225 $/Monat
Mittleres Team (15) 229 $/Monat (M4 Pro) 1500 Builds (Ø 10 Min.) 930 $/Monat 701 $/Monat
Enterprise (50+) 458 $/Monat (2x M4 Pro) 5000+ Builds 3.100+ $/Monat 2.642+ $/Monat

Preise von My Remote Mac in USD, exkl. Steuern. GitHub-Angaben: Standard-macOS-Runner zu 0,062 $ pro Minute laut GitHub-Preisdokumentation, Stand Oktober 2026.

Fazit: Für Teams, die mehr als ~140 Builds pro Monat ausführen, amortisiert sich ein Self-Hosted Mac Mini M4 sofort. Und weil Builds auf persistenter Hardware mit warmen Caches schneller sind, spart Ihr Team auch Entwicklerzeit. Bei 100 Builds pro Monat, wie in der Zeile Einzelentwickler, kosten GitHub-gehostete Runner 23 $/Monat weniger; dennoch kann ein Einzelentwickler einen dedizierten Mac vorziehen, wegen der persistenten Caches, der schnelleren Builds und der fehlenden Abrechnung pro Minute. Wenn Sie nur gelegentlich veröffentlichen, bekommen Sie mit dem Tagestarif einen Mac für den Release-Tag ab 14 $ pro 24 Stunden (USD, exkl. Steuern): Schalten Sie bei der Bereitstellung die automatische Verlängerung aus, dann endet er nach 24 Stunden, oder wechseln Sie auf demselben Mac zum Monatstarif.

Bereit, Ihre iOS-Builds zu beschleunigen?

Setzen Sie einen dedizierten Mac Mini M4 als Ihren GitHub Actions Runner ein. 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 →