Saltar al contenido

GitLab CI/CD Runner en Mac Mini M4: Guía completa

Instale y configure un GitLab CI/CD runner en un Mac Mini M4 dedicado. Compile apps iOS de forma nativa en Apple Silicon, ejecute pruebas en simuladores reales y despliegue en TestFlight, todo desde su pipeline de GitLab.

CI/CD 30 min de lectura Actualizado en noviembre de 2026

¿Por qué Self-Hosted GitLab Runners en Mac?

GitLab ofrece runners compartidos en Linux, pero compilar apps iOS requiere macOS ejecutándose en hardware Apple. Los runners compartidos macOS de GitLab son limitados y costosos. Un Mac Mini M4 self-hosted runner le ofrece:

  • Minutos CI/CD ilimitados

    El plan gratuito de GitLab incluye 400 minutos CI/CD en runners compartidos. En self-hosted, no hay límite.

  • Apple Silicon nativo

    Compile en el mismo chip M4 que ejecutan los dispositivos de sus usuarios. Sin sobrecarga de traducción Rosetta.

  • Control total del entorno

    Instale cualquier versión de Xcode, simuladores, herramientas y dependencias que necesite.

  • Cachés persistentes

    Las cachés de DerivedData, paquetes SPM y CocoaPods sobreviven entre ejecuciones del pipeline.

Instalar GitLab Runner

Conéctese por SSH a su servidor de build Mac mini M4 dedicado e instale el GitLab Runner, junto con xcbeautify para obtener logs de compilación legibles, 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

Instalar como un servicio 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

Registrar el Runner

Abra su proyecto de GitLab, vaya a Settings > CI/CD > Runners y seleccione Create project runner (para un grupo: Build > Runners > Create group runner). En Tags, escriba macos y m4 (el pipeline de abajo apunta a esas etiquetas), cree el runner y copie su token de autenticación, que empieza por glrt-. Con un token de autenticación, el comando register no acepta las etiquetas ni las demás opciones del runner: se configuran aquí, en GitLab. Para automatizar este paso, cree el runner con la API (ejemplo más abajo).

Registrar con un token de autenticación de 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

Método antiguo: registrar con un token de registro

Los tokens de registro están obsoletos desde GitLab 15.6, y GitLab prevé eliminarlos en GitLab 20.0. Desde GitLab 17.0 solo funcionan si un administrador (o, en GitLab.com, el propietario del grupo de nivel superior) los ha vuelto a activar. Use este método solo en una instancia que todavía lo requiera.

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

Verificar la configuración 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

Edite ~/.gitlab-runner/config.toml para ajustar la concurrencia:

# 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

El runner debería aparecer ahora como Online en su proyecto de GitLab bajo Settings > CI/CD > Runners.

Crear .gitlab-ci.yml para iOS

Cree un archivo .gitlab-ci.yml en la raíz de su repositorio. Este pipeline completo compila, prueba y despliega su 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}

Añadir variables CI/CD en GitLab

Navegue a Settings > CI/CD > Variables en su proyecto de GitLab y añada estas variables como "Masked" y "Protected":

  • MATCH_PASSWORD: Contraseña para el cifrado de Fastlane Match
  • APP_STORE_KEY_ID: ID de clave API de App Store Connect
  • APP_STORE_ISSUER_ID: ID de emisor de App Store Connect
  • APP_STORE_KEY_CONTENT: Contenido del archivo de clave .p8

Optimizar el rendimiento

Configuración de caché de GitLab

En un Mac persistente, la caché más rápida es la que GitLab no tiene que mover: el pipeline de arriba guarda DerivedData fuera del checkout, así que se mantiene caliente entre jobs. Con el ejecutor shell, la caché de GitLab se comprime y descomprime en cada job, así que resérvela para carpetas pequeñas como 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

Usar artefactos para datos entre etapas

# 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

Ejecución paralela de pruebas

# 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

Limpieza programada de caché

# 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

Solución de problemas

El Runner aparece "offline" en GitLab

El runner se ejecuta como LaunchAgent, así que arranca cuando se inicia su sesión de usuario: tras un reinicio queda fuera de línea hasta que ese usuario inicia sesión. En un Mac headless, active el inicio de sesión automático para ese usuario (Ajustes del Sistema > Usuarios y grupos; no disponible mientras FileVault esté activado). Después verifique el estado del servicio del runner y los logs:

# 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

Errores de permisos denegados durante las compilaciones

El runner puede necesitar acceso al directorio de desarrollador de 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 caché no se restaura

Asegúrese de que las claves de caché sean consistentes y que las rutas existan:

# 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 compilación de Xcode se cuelga o agota el tiempo

Esto suele ser causado por solicitudes de acceso al keychain o problemas con el simulador:

# 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

Preguntas frecuentes

¿Puedo usar un ejecutor Docker en macOS?
Docker en macOS ejecuta contenedores Linux en una VM, que no puede acceder a APIs de macOS, Xcode ni simuladores iOS. Para compilaciones iOS, debe usar el ejecutor shell. Docker es adecuado para Swift del lado del servidor u otras tareas basadas en Linux ejecutándose junto a su Mac runner.
¿Cómo registro el runner para un grupo de GitLab?
Abra su grupo de GitLab, vaya a Build > Runners y seleccione Create group runner (necesita el rol Owner en el grupo). Registre el Mac con el token de autenticación de ese runner de grupo. El runner queda entonces disponible para todos los proyectos del grupo.
¿Debo usar el ejecutor shell o el ejecutor SSH?
Use el ejecutor shell. Ejecuta comandos directamente en el Mac, lo que da acceso completo a Xcode, simuladores y el keychain. El ejecutor SSH es para máquinas remotas, lo cual es innecesario cuando el runner ya está en el Mac.
¿Puedo ejecutar tanto GitLab como GitHub Actions runners en el mismo Mac?
Sí. Ambos runners son ligeros y pueden coexistir en el mismo Mac Mini M4. Solo asegúrese de tener en cuenta el uso combinado de recursos al establecer los niveles de concurrencia de cada runner.
¿Cómo actualizo el GitLab Runner?
# Update via Homebrew
brew upgrade gitlab-runner

# Restart the service
brew services restart gitlab-runner

# Verify the new version
gitlab-runner --version
¿Buscas un GitLab Runner completamente gestionado? Prueba Cloud-Runner Sáltate toda la configuración. Cloud-Runner ofrece GitLab Runners dedicados y preconfigurados en hardware Mac, sin instalación ni mantenimiento.

¿Listo para potenciar sus pipelines de GitLab?

Obtenga un Mac Mini M4 dedicado para su GitLab CI/CD runner. Compilaciones ilimitadas desde $85/mes.

Precios de My Remote Mac en USD, sin impuestos.

¿Buscas más detalles?

Explora la documentación completa: guías paso a paso, referencias de configuración y resolución de problemas.

Abrir la documentación →