Vai al contenuto

Come configurare un GitHub Actions Self-Hosted Runner su Mac Mini M4

Guida passo passo per configurare un GitHub Actions self-hosted runner su un Mac Mini M4 dedicato. Build iOS più veloci, native su Apple Silicon e fino a 6,7 volte più economiche dei runner macOS ospitati da GitHub.

CI/CD 30 min di lettura Aggiornato a ottobre 2026

Perché usare un Mac Runner self-hosted?

I runner macOS ospitati da GitHub sono comodi, ma si pagano al minuto, quindi il costo cresce con il volume di build. A 0,062 $ al minuto (tariffa del runner macOS standard di GitHub a ottobre 2026), un team che esegue 75 ore di build al mese paga circa 279 $. GitHub non fattura i minuti dei runner self-hosted, quindi un Mac mini M4 dedicato di My Remote Mac costa una tariffa fissa di 85 $/mese (USD, tasse escluse), senza fatturazione al minuto, offrendoti lo stesso hardware (o migliore) a una frazione del costo.

Perché usare un Mac Runner self-hosted?
My Remote Mac Self-Hosted Runner ospitato da GitHub
Costo 85 $/mese (nessuna fatturazione al minuto) 0,062 $/min (~279 $/mese per 75 h)
Architettura Apple M4, Mac fisico assegnato 1:1 VM Apple M1, 3 core, 7 GB di RAM (runner standard)
Velocità di build ~4 min (stesso progetto) ~12 min (progetto medio)
Cache persistente Sì (disco persistente) No (effimera)
Software personalizzato Accesso root completo Limitato
Job simultanei 1 job per runner; aggiungi runner o Mac per scalare 5 (Free, Pro, Team) / 50 (Enterprise)

Prezzi My Remote Mac in USD, tasse escluse. Dati GitHub: runner macOS standard a 0,062 $ al minuto, secondo la documentazione dei prezzi di GitHub, a ottobre 2026.

Vantaggio chiave: Poiché il runner è persistente, DerivedData, cache SPM e CocoaPods vengono conservati tra le build. Solo questo può ridurre i tempi di build del 50-70% rispetto ai runner effimeri ospitati da GitHub che ripartono da zero ogni volta.

Prerequisiti

Prima di iniziare, assicurati di avere quanto segue:

  • Un build server Mac mini M4 dedicato di My Remote Mac (da 85 $/mese, USD, tasse escluse)
  • Un account GitHub con accesso admin al tuo repository o alla tua organizzazione
  • Accesso SSH al tuo Mac Mini (incluso nel tuo abbonamento My Remote Mac)
  • Un account Apple Developer (per la firma del codice e i profili di provisioning)
  • Familiarità di base con YAML e comandi da terminale

Passo 1: Connettiti al tuo Mac Mini via SSH e verifica Xcode

Per prima cosa, connettiti al tuo Mac Mini M4 via SSH. Hai ricevuto le tue credenziali quando hai configurato il tuo server My Remote Mac.

Connettiti via SSH

# 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

Verifica gli Xcode Command Line Tools

# 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

Verifica Xcode e aggiungi altre versioni

Xcode, i suoi Command Line Tools e Homebrew sono preinstallati su ogni server My Remote Mac. Verifica la versione attiva e, se il tuo progetto ne ha bisogno, installa altre versioni in parallelo con 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

Installa i simulatori iOS

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

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

Passo 2: Installa il GitHub Actions Runner

Ora scarichiamo e configuriamo l'agente GitHub Actions runner. Vai al tuo repository su GitHub, apri Settings > Actions > Runners > New self-hosted runner e seleziona macOS + ARM64.

Scarica e configura

# 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

Installa come servizio launchd persistente

Eseguire l'agente in modo interattivo va bene per i test, ma in produzione deve avviarsi automaticamente e riavviarsi in caso di crash. GitHub fornisce uno script integrato di installazione del servizio per macOS:

# 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

Ora il servizio si avvia a ogni login dell'utente del runner e riavvia il runner se il processo si interrompe. Un LaunchAgent non parte da solo all'avvio del Mac: su un Mac headless, abilita il login automatico per quell'utente (Impostazioni di Sistema > Utenti e Gruppi; non disponibile mentre FileVault è attivo) così il runner torna online dopo un riavvio. Puoi verificare che il runner appaia come "Idle" nella pagina Settings > Actions > Runners del tuo repository GitHub.

Configura il runner per più repository (a livello di organizzazione)

# 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

Passo 3: Crea il tuo workflow di build iOS

Crea un file di workflow nel tuo repository in .github/workflows/ios-build.yml. Questo workflow verrà eseguito sul tuo 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

Aggiungi la firma del codice per le build di release

Per i deployment su TestFlight o App Store, aggiungi i passaggi di firma del codice. Salva i tuoi certificati e profili di provisioning come 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

Passo 4: Ottimizza le prestazioni

Uno dei maggiori vantaggi di un self-hosted runner è il caching persistente. Ecco le ottimizzazioni chiave per sfruttare al massimo il tuo Mac Mini M4.

Abilita il caching di DerivedData

Poiché il runner è persistente, DerivedData viene conservato tra le build. Usa un percorso DerivedData coerente:

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

Metti in cache i pacchetti SPM

# 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

Esecuzione dei test in parallelo

# 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

Installa xcbeautify per log migliori

# 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

Risoluzione dei problemi comuni

Il runner appare "Offline" in GitHub

Di solito significa che il servizio launchd non è in esecuzione. Controlla lo stato del servizio e i log:

# 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

La firma del codice fallisce con "No signing certificate"

Il servizio launchd viene eseguito in un contesto utente diverso. Assicurati che il portachiavi sia accessibile:

# 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

Il simulatore non si avvia

A volte i simulatori si bloccano. Reimpostali tra una build e l'altra:

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

Spazio su disco in esaurimento

Le build di Xcode generano molti dati. Configura una pulizia automatica:

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

Analisi dei costi

Ecco un confronto dettagliato dei costi per diverse dimensioni di team e volumi di build:

Analisi dei costi
Dimensione del team Costo My Remote Mac Build/mese Costo ospitato da GitHub Risparmio mensile
Sviluppatore singolo 85 $/mese 100 build (10 min medi) 62 $/mese Nessuno (costa 23 $/mese in più)
Piccolo team (5) 85 $/mese 500 build (10 min medi) 310 $/mese 225 $/mese
Team medio (15) 229 $/mese (M4 Pro) 1500 build (10 min medi) 930 $/mese 701 $/mese
Enterprise (50+) 458 $/mese (2x M4 Pro) 5000+ build 3.100+ $/mese 2.642+ $/mese

Prezzi My Remote Mac in USD, tasse escluse. Dati GitHub: runner macOS standard a 0,062 $ al minuto, secondo la documentazione dei prezzi di GitHub, a ottobre 2026.

In sintesi: Per i team che eseguono più di ~140 build al mese, un Mac Mini M4 self-hosted si ripaga immediatamente. E poiché le build sono più veloci su hardware persistente con cache calde, il tuo team risparmia anche tempo di sviluppo. Con 100 build al mese, come nella riga Sviluppatore singolo, i runner ospitati da GitHub costano 23 $/mese in meno; uno sviluppatore singolo può comunque preferire un Mac dedicato per le cache persistenti, le build più veloci e l'assenza di fatturazione al minuto. Se pubblichi solo di tanto in tanto, il piano giornaliero ti dà un Mac per il giorno del rilascio da 14 $ per 24 ore (USD, tasse escluse): disattiva il rinnovo automatico al deploy e si ferma dopo 24 ore, oppure passa al mensile sullo stesso Mac.

Pronto ad accelerare le tue build iOS?

Distribuisci un Mac Mini M4 dedicato come tuo GitHub Actions runner. A partire da 85 $/mese.

Prezzi My Remote Mac in USD, tasse escluse.

Cerchi maggiori dettagli?

Consulta la documentazione completa per guide passo passo, riferimenti di configurazione e risoluzione dei problemi.

Apri la documentazione →