Vai al contenuto

GitLab CI/CD Runner su Mac Mini M4: guida completa

Installa e configura un GitLab CI/CD runner su un Mac Mini M4 dedicato. Compila app iOS nativamente su Apple Silicon, esegui test su simulatori reali e distribuisci su TestFlight, tutto dalla tua pipeline GitLab.

CI/CD 30 min di lettura Aggiornato a novembre 2026

Perché GitLab Runner self-hosted su Mac?

GitLab offre runner condivisi su Linux, ma compilare app iOS richiede macOS in esecuzione su hardware Apple. I runner macOS condivisi di GitLab sono limitati e costosi. Un Mac Mini M4 runner self-hosted ti offre:

  • Minuti CI/CD illimitati

    Il piano gratuito di GitLab include 400 minuti CI/CD sui runner condivisi. Su self-hosted non c'è alcun limite.

  • Apple Silicon nativo

    Compila sullo stesso chip M4 su cui girano i dispositivi dei tuoi utenti. Nessun overhead di traduzione Rosetta.

  • Controllo completo dell'ambiente

    Installa qualsiasi versione di Xcode, simulatori, strumenti e dipendenze di cui hai bisogno.

  • Cache persistenti

    Le cache di DerivedData, pacchetti SPM e CocoaPods sopravvivono tra un'esecuzione della pipeline e l'altra.

Installa GitLab Runner

Connettiti via SSH al tuo build server Mac mini M4 dedicato e installa GitLab Runner, insieme a xcbeautify per log di build leggibili, usando Homebrew:

# Connect to your Mac Mini M4
ssh admin@your-server-ip

# Put the preinstalled Homebrew on your PATH (once per account)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Install GitLab Runner with Homebrew, plus xcbeautify for the pipeline's build logs
brew install gitlab-runner xcbeautify

# Verify installation (prints the version and OS/Arch: darwin/arm64)
gitlab-runner --version

Installa come servizio macOS

# Run the runner as a launchd service. It is a LaunchAgent: it starts when
# your user session starts, so on a headless Mac enable automatic login for
# this user (System Settings > Users & Groups) to bring it back after a reboot
brew services start gitlab-runner

# Verify the service is running
brew services list | grep gitlab-runner
# gitlab-runner started admin ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner.plist

Registra il Runner

Apri il tuo progetto GitLab, vai su Settings > CI/CD > Runners e seleziona Create project runner (per un gruppo: Build > Runners > Create group runner). In Tags, inserisci macos e m4 (la pipeline qui sotto usa questi tag), crea il runner, poi copia il suo token di autenticazione, che inizia con glrt-. Con un token di autenticazione, il comando register non accetta i tag né le altre opzioni del runner: li imposti qui in GitLab. Per automatizzare questo passaggio, crea il runner tramite API (esempio qui sotto).

Registrazione con un token di autenticazione del runner

# Optional: create the runner with the API instead of the GitLab UI.
# Needs an access token with the create_runner scope; the "token"
# field of the response is the runner authentication token (glrt-...)
curl --request POST \
  --header "PRIVATE-TOKEN: YOUR_ACCESS_TOKEN" \
  --url "https://gitlab.com/api/v4/user/runners" \
  --data "runner_type=project_type" \
  --data "project_id=YOUR_PROJECT_ID" \
  --data "tag_list=macos,m4" \
  --data "run_untagged=false"

# Register the runner with its authentication token (starts with glrt-).
# Tags, untagged jobs and locking come from the runner you created in GitLab:
# do not pass --tag-list or --run-untagged with an authentication token
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "YOUR_RUNNER_AUTHENTICATION_TOKEN" \
  --executor "shell" \
  --name "mac-mini-m4-runner"

# Confirm the runner can reach GitLab
gitlab-runner verify

Vecchio metodo: registrazione con un token di registrazione

I token di registrazione sono deprecati da GitLab 15.6, e GitLab prevede di rimuoverli in GitLab 20.0. Da GitLab 17.0 funzionano solo se un amministratore (o, su GitLab.com, il proprietario del gruppo di primo livello) li ha riattivati. Usa questo metodo solo su un'istanza che lo richieda ancora.

# Legacy: registration token (deprecated since GitLab 15.6,
# removal scheduled for GitLab 20.0). On GitLab 17.0 and later,
# it works only where registration tokens were enabled again.
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --registration-token "YOUR_REGISTRATION_TOKEN" \
  --executor "shell" \
  --description "mac-mini-m4-runner" \
  --tag-list "macos,apple-silicon,m4,ios,xcode" \
  --run-untagged="false"

Verifica la configurazione del Runner

# View the runner config file
cat ~/.gitlab-runner/config.toml

# Expected output:
# concurrent = 2
# check_interval = 0
#
# [session_server]
#   session_timeout = 1800
#
# [[runners]]
#   name = "mac-mini-m4-runner"
#   url = "https://gitlab.com/"
#   token = "..."
#   executor = "shell"
#   [runners.cache]
#     MaxUploadedArchiveSize = 0

# Adjust concurrency based on your hardware:
# Mac Mini M4 (16GB): concurrent = 2
# Mac Mini M4 Pro (24GB): concurrent = 3
# Mac Mini M4 Pro (48GB): concurrent = 4

Modifica ~/.gitlab-runner/config.toml per regolare la concorrenza:

# Edit the config
nano ~/.gitlab-runner/config.toml

# Set concurrent to match your hardware capacity
concurrent = 2

# Restart the service to apply changes
brew services restart gitlab-runner

Il runner ora dovrebbe apparire come Online nel tuo progetto GitLab sotto Settings > CI/CD > Runners.

Crea .gitlab-ci.yml per iOS

Crea un file .gitlab-ci.yml nella radice del tuo repository. Questa pipeline completa compila, testa e distribuisce la tua app iOS:

# .gitlab-ci.yml

stages:
  - build
  - test
  - deploy

variables:
  SCHEME: "MyApp"
  WORKSPACE: "MyApp.xcworkspace"
  # Any device listed by: xcrun simctl list devices available
  DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"
  # Pick the Xcode for every job without sudo
  # (preinstalled Xcode; for another version, use the path from xcodes installed)
  DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"

# Only run on our Mac runner
default:
  tags:
    - macos
    - m4
  before_script:
    # The runner cleans the checkout (git clean -ffdx) before each job, so keep
    # DerivedData outside it: one warm folder per project and concurrent job slot
    - export DERIVED_DATA="${CI_BUILDS_DIR}/DerivedData/${CI_PROJECT_PATH_SLUG}-${CI_CONCURRENT_PROJECT_ID}"
    - xcodebuild -version
    # Pods/ is removed with the rest of the checkout's untracked files: reinstall it
    - |
      if [ -f "Podfile" ]; then
        pod install
      fi

# ---- BUILD ----

build:
  stage: build
  script:
    - |
      xcodebuild build \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        CODE_SIGNING_ALLOWED=NO \
        | xcbeautify

# ---- TEST ----

unit_tests:
  stage: test
  needs: ["build"]
  script:
    - |
      xcodebuild test \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        -resultBundlePath "TestResults.xcresult" \
        -parallel-testing-enabled YES \
        | xcbeautify --report junit --report-path build/reports
  artifacts:
    when: always
    paths:
      - TestResults.xcresult/
    reports:
      junit: build/reports/junit.xml
    expire_in: 7 days
  after_script:
    - xcrun simctl shutdown all 2>/dev/null || true

# ---- DEPLOY ----

deploy_testflight:
  stage: deploy
  needs: ["unit_tests"]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - |
      # Install or update Fastlane
      which fastlane || brew install fastlane

      # Run Fastlane beta lane
      fastlane beta
  environment:
    name: testflight
  variables:
    MATCH_PASSWORD: ${MATCH_PASSWORD}
    # Names read by fastlane's app_store_connect_api_key action (call it in your lane)
    APP_STORE_CONNECT_API_KEY_KEY_ID: ${APP_STORE_KEY_ID}
    APP_STORE_CONNECT_API_KEY_ISSUER_ID: ${APP_STORE_ISSUER_ID}
    APP_STORE_CONNECT_API_KEY_KEY: ${APP_STORE_KEY_CONTENT}

Aggiungi variabili CI/CD in GitLab

Vai su Settings > CI/CD > Variables nel tuo progetto GitLab e aggiungi queste variabili come "Masked" e "Protected":

  • MATCH_PASSWORD: Password per la crittografia di Fastlane Match
  • APP_STORE_KEY_ID: App Store Connect API Key ID
  • APP_STORE_ISSUER_ID: App Store Connect Issuer ID
  • APP_STORE_KEY_CONTENT: Il contenuto del file di chiave .p8

Ottimizza le prestazioni

Configurazione della cache di GitLab

Su un Mac persistente, la cache più veloce è quella che GitLab non deve spostare: la pipeline qui sopra tiene DerivedData fuori dal checkout, così resta calda tra un job e l'altro. Con l'executor shell, la cache di GitLab viene compressa e decompressa a ogni job, quindi usala per cartelle piccole come Pods/:

# DerivedData already stays on disk outside the checkout (DERIVED_DATA above).
# Use GitLab's cache for small folders, keyed on the lockfile:
build:
  cache:
    key:
      files:
        - Podfile.lock
    paths:
      - Pods/
    policy: pull-push

# For test jobs that don't modify the cache, use pull-only:
unit_tests:
  cache:
    key:
      files:
        - Podfile.lock
    paths:
      - Pods/
    policy: pull

Usa gli artefatti per i dati tra fasi

# Useful when the build and test jobs can run on different Macs.
# build-for-testing compiles the app and its test bundles once; artifacts must
# sit inside the project folder, so this job builds there
build:
  script:
    - |
      xcodebuild build-for-testing \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath build/DerivedData \
        | xcbeautify
  artifacts:
    paths:
      - build/DerivedData/Build/Products/
    expire_in: 2 hours

# The test stage receives the built products and runs them without rebuilding
unit_tests:
  needs: ["build"]  # downloads the build job's artifacts
  script:
    - |
      xcodebuild test-without-building \
        -xctestrun build/DerivedData/Build/Products/*.xctestrun \
        -destination "${DESTINATION}" \
        | xcbeautify

Esecuzione dei test in parallelo

# On one Mac, let xcodebuild split the test classes across simulator clones.
# (GitLab's parallel: keyword only helps if each copy runs a different part of
# the suite, using CI_NODE_INDEX and CI_NODE_TOTAL; otherwise it repeats it.)
unit_tests:
  stage: test
  script:
    - |
      xcodebuild test \
        -workspace "${WORKSPACE}" \
        -scheme "${SCHEME}" \
        -destination "${DESTINATION}" \
        -derivedDataPath "${DERIVED_DATA}" \
        -parallel-testing-enabled YES \
        -maximum-parallel-testing-workers 4 \
        | xcbeautify

Pulizia programmata della cache

# On the Mac Mini, set up a weekly cleanup cron job
crontab -e

# Add these lines:
# Every Sunday at 3 AM, remove DerivedData folders not used for 7 days
# (the pipeline keeps them in ~/builds/DerivedData, one per project and slot)
0 3 * * 0 find ~/builds/DerivedData -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} + 2>/dev/null

# Checkouts in ~/builds are reused by the next job (git fetch): no need to delete them

# Clean Homebrew cache monthly
0 5 1 * * /opt/homebrew/bin/brew cleanup --prune=30 2>/dev/null

Risoluzione dei problemi

Il runner appare "offline" in GitLab

Il runner gira come LaunchAgent, quindi si avvia con la tua sessione utente: dopo un riavvio resta offline finché quell'utente non effettua il login. Su un Mac headless, abilita il login automatico per quell'utente (Impostazioni di Sistema > Utenti e Gruppi; non disponibile mentre FileVault è attivo). Poi controlla lo stato e i log del servizio runner:

# Check service status
brew services list | grep gitlab-runner

# View logs
cat /opt/homebrew/var/log/gitlab-runner.log

# Restart the service
brew services restart gitlab-runner

# Verify connectivity to GitLab
gitlab-runner verify

Errori "Permission denied" durante le build

Il runner potrebbe aver bisogno dell'accesso alla directory dello sviluppatore Xcode:

# Ensure the runner user has Xcode access (run once, in your SSH session)
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

# If using simulators, ensure the user can access them
xcrun simctl list devices

La cache non viene ripristinata

Assicurati che le chiavi della cache siano coerenti e che i percorsi esistano:

# Check cache directory permissions
ls -la ~/builds/

# The shell executor stores caches locally by default
# Verify the cache directory in config.toml:
cat ~/.gitlab-runner/config.toml

# Ensure [runners.cache] section has the right settings
# For local caching (most efficient for persistent runners):
# [runners.cache]
#   Type = ""  # empty = local cache

La build di Xcode si blocca o va in timeout

Questo è spesso causato da richieste di accesso al portachiavi o da problemi con i simulatori:

# Unlock the keychain before builds
security unlock-keychain -p "YOUR_PASSWORD" ~/Library/Keychains/login.keychain-db

# Kill stuck simulators
xcrun simctl shutdown all
killall -9 com.apple.CoreSimulator.CoreSimulatorService 2>/dev/null || true

# Set a build timeout in .gitlab-ci.yml
build:
  timeout: 30 minutes

FAQ

Posso usare un executor Docker su macOS?
Docker su macOS esegue container Linux in una VM, che non può accedere alle API di macOS, a Xcode o ai simulatori iOS. Per le build iOS devi usare l'executor shell. Docker va bene per Swift lato server o altre attività basate su Linux eseguite insieme al tuo runner Mac.
Come registro il runner per un gruppo GitLab?
Apri il tuo gruppo GitLab, vai su Build > Runners e seleziona Create group runner (serve il ruolo Owner sul gruppo). Registra il Mac con il token di autenticazione di quel runner di gruppo. Il runner diventa così disponibile per tutti i progetti del gruppo.
Dovrei usare l'executor shell o l'executor SSH?
Usa l'executor shell. Esegue i comandi direttamente sul Mac, garantendo accesso completo a Xcode, ai simulatori e al portachiavi. L'executor SSH è pensato per macchine remote, cosa non necessaria quando il runner è già sul Mac.
Posso eseguire runner GitLab e GitHub Actions sullo stesso Mac?
Sì. Entrambi i runner sono leggeri e possono coesistere sullo stesso Mac Mini M4. Assicurati solo di considerare l'utilizzo combinato delle risorse quando imposti i livelli di concorrenza per ciascun runner.
Come aggiorno GitLab Runner?
# Update via Homebrew
brew upgrade gitlab-runner

# Restart the service
brew services restart gitlab-runner

# Verify the new version
gitlab-runner --version
Cerchi un GitLab Runner completamente gestito? Prova Cloud-Runner Salta del tutto la configurazione. Cloud-Runner fornisce GitLab Runner dedicati e preconfigurati su hardware Mac, nessuna installazione o manutenzione richiesta.

Pronto a potenziare le tue pipeline GitLab?

Ottieni un Mac Mini M4 dedicato per il tuo GitLab CI/CD runner. Build illimitate 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 →