¿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 MatchAPP_STORE_KEY_ID: ID de clave API de App Store ConnectAPP_STORE_ISSUER_ID: ID de emisor de App Store ConnectAPP_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?
¿Cómo registro el runner para un grupo de GitLab?
¿Debo usar el ejecutor shell o el ejecutor SSH?
¿Puedo ejecutar tanto GitLab como GitHub Actions runners en el mismo Mac?
¿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