Saltar al contenido

Cómo Configurar un CircleCI Self-Hosted Runner en Mac Mini M4

Guía completa paso a paso para instalar y configurar un CircleCI self-hosted machine runner en un Mac mini M4 dedicado. Rendimiento nativo de Apple Silicon, caché persistente y hasta un 90% más económico que los recursos macOS en la nube de CircleCI.

CI/CD 35 min de lectura Actualizado en octubre de 2026

¿Por qué usar un Self-Hosted CircleCI Runner en Mac?

CircleCI ofrece entornos de ejecución macOS en la nube, pero conllevan costes y limitaciones significativos. CircleCI factura los jobs de macOS en créditos: la resource class m4pro.medium consume 200 créditos por minuto (unos $0.12) y m4pro.large 400 (unos $0.24), a octubre de 2026. Para equipos que ejecutan compilaciones iOS frecuentes, esto puede sumar rápidamente $300-$500 por mes o más.

Un self-hosted runner en un Mac Mini M4 dedicado de MyRemoteMac elimina por completo la facturación por minuto. Obtiene una máquina Apple Silicon dedicada con almacenamiento persistente, cachés precargadas y acceso root completo por una tarifa mensual fija desde $85/mes. Aquí tiene una comparación detallada:

¿Por qué usar un Self-Hosted CircleCI Runner en Mac?
MyRemoteMac Self-Hosted CircleCI Cloud macOS
Modelo de costes $85/mes tarifa fija (minutos ilimitados) 200 créditos/min en m4pro.medium (~$0.12/min)
Arquitectura Mac Apple M4 físico, asignado 1:1 Máquina virtual M4 Pro (6 vCPU, 28 GB)
Velocidad de compilación ~5 min (mismo proyecto) ~14 min (proyecto iOS mediano)
Persistencia de caché Persistente en disco (instantáneo) Efímero (debe restaurar en cada job)
Tiempo de espera en cola 0s (hardware dedicado) 30s - 5min (varía según el plan)
Privacidad / Control de datos Máquina dedicada, control total Infraestructura compartida
Software personalizado Acceso root completo, cualquier software Solo imagen preinstalada

Precios de My Remote Mac en USD, sin impuestos.

Beneficio clave: Con un self-hosted runner persistente, DerivedData, las cachés de Swift Package Manager y CocoaPods se preservan entre compilaciones. Esto por sí solo puede reducir los tiempos de compilación en un 50-70% comparado con los entornos macOS efímeros en la nube de CircleCI que comienzan desde cero cada vez. Combinado con el rendimiento superior de single-thread del chip M4, sus compilaciones iOS serán drásticamente más rápidas.

Requisitos previos

Antes de comenzar, asegúrese de tener lo siguiente:

  • Un servidor de build Mac mini M4 dedicado de My Remote Mac (desde $85/mes, USD, sin impuestos)
  • Una organización de CircleCI en la que seas administrador (los self-hosted runners están disponibles en todos los planes, incluido Free, que permite 5 tareas self-hosted simultáneas a octubre de 2026)
  • Acceso SSH a su Mac Mini (incluido con su suscripción de MyRemoteMac)
  • Una cuenta de Apple Developer (para la firma de código y perfiles de aprovisionamiento)
  • Familiaridad básica con YAML, configuración de CircleCI y comandos de terminal

Paso 1: Comprobar Xcode e instalar dependencias

Primero, conéctese a su Mac Mini M4 por SSH con las credenciales que recibió al configurar su servidor MyRemoteMac. Xcode, sus Command Line Tools y Homebrew ya están instalados, así que solo tiene que añadir las herramientas de compilación que necesita su pipeline iOS antes de configurar el runner de CircleCI.

Conectarse por SSH

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

# Verify you're on Apple Silicon
uname -m
# Expected output: arm64

# Show the macOS version
sw_vers

Comprobar Homebrew y Xcode Command Line Tools

# Homebrew comes preinstalled: put it on your PATH for your zsh sessions
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version

# Add Homebrew to PATH for CircleCI job steps
# (CircleCI runs macOS steps in a bash login shell)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile

# 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

Comprobar Xcode y añadir otras versiones

Para compilaciones iOS, necesita la aplicación Xcode completa. Desde el 28 de abril de 2026, App Store Connect solo acepta compilaciones hechas con Xcode 26 o posterior, y el Xcode preinstalado en su servidor cumple esa regla. Instale otra versión en paralelo con xcodes solo si su proyecto la necesita:

# Check the preinstalled Xcode
xcodebuild -version
# Xcode 27.2

# Optional: add other Xcode releases side by side with the xcodes CLI
brew install xcodes
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 default Xcode (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

Instalar simuladores iOS y herramientas de compilación

# Install the current iOS simulator runtime
xcodebuild -downloadPlatform iOS

# Verify simulator availability
xcrun simctl list runtimes

# Install additional build tools
brew install xcbeautify fastlane swiftlint

Paso 2: Instalar el agente CircleCI Runner

El machine runner 3 de CircleCI conecta su Mac mini a CircleCI: recibe los jobs y los ejecuta directamente en su host macOS. En macOS, CircleCI recomienda instalarlo con su paquete de Homebrew. Esto es diferente del container runner (que solo funciona en Linux).

Elegir el usuario que ejecuta sus jobs

El machine runner 3 ejecuta cada job como el usuario de macOS que lo inicia, con el Homebrew, el llavero y el Xcode de ese usuario. Instálelo e inícielo con su usuario administrador, el propietario de Homebrew, no como root: Homebrew se niega a ejecutarse como root.

# Run the steps below as the user that will run CI jobs, not with sudo
whoami

# Homebrew must work for this user (prints /opt/homebrew)
brew --prefix

Instalar el machine runner 3 con Homebrew

# Add CircleCI's Homebrew tap and install machine runner 3
brew tap circleci-public/circleci
brew install circleci-runner

# Check that macOS accepts the binary notarized by CircleCI
spctl -a -vvv -t install "$(brew --prefix)/bin/circleci-runner"
# Expected: accepted, source=Notarized Developer ID,
# origin=Developer ID Application: Circle Internet Services Inc.

# Remove the quarantine attribute (asks for your macOS password)
sudo xattr -r -d com.apple.quarantine "$(brew --prefix)/bin/circleci-runner"

Configurar el agente Runner

El paquete de Homebrew crea el archivo de configuración. Necesitará su token de autenticación del runner de la aplicación web de CircleCI (cubierto en el Paso 3). Por ahora, defina el nombre del runner y deje un marcador para el token:

# Open the configuration file created by the Homebrew package
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

# Contents (the token comes in Step 3):
runner:
  name: "mac-mini-m4-runner"
  working_directory: "/Users/$USER/Library/com.circleci.runner/workdir"
  cleanup_working_directory: true
api:
  auth_token: "YOUR_RUNNER_TOKEN_HERE"

# The file will hold a secret: make it readable by you only
chmod 600 "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

Preparar el servicio launchd para un Mac headless

El paquete de Homebrew también instala un agente launchd, com.circleci.runner. Un agente normalmente arranca cuando su usuario inicia sesión; en un Mac al que solo accede por SSH, la configuración headless de CircleCI lo mueve a /Library/LaunchAgents para que se cargue tras un reinicio. Inícielo en el Paso 3, cuando el token esté en su sitio:

# The launchd agent installed by the Homebrew package
ls ~/Library/LaunchAgents/com.circleci.runner.plist

# Headless Mac reached over SSH only: move it to the per-user agents
# folder so it loads after a reboot (CircleCI's headless setup)
sudo mv ~/Library/LaunchAgents/com.circleci.runner.plist /Library/LaunchAgents/

Importante: El runner no se conectará hasta que config.yaml contenga un token de autenticación válido. Genérelo en el Paso 3, añádalo al archivo y luego inicie el servicio.

Paso 3: Configurar el Runner en el panel de CircleCI

Ahora necesita registrar su runner en la interfaz web de CircleCI y generar un token de autenticación. Esto conecta su Mac Mini a su organización de CircleCI.

Crear una Resource Class

En CircleCI, los self-hosted runners se organizan por resource classes. Una resource class es una etiqueta que mapea su .circleci/config.yml a un conjunto específico de runners.

  1. En la aplicación web de CircleCI, abra Runners en la barra lateral (debe ser administrador de la organización)
  2. Haga clic en "Create Resource Class"
  3. Establezca el Namespace con el nombre de su organización (p. ej., your-org)
  4. Establezca el nombre de la Resource Class con algo descriptivo (p. ej., mac-runner)
  5. Esto crea un identificador de resource class: your-org/mac-runner

Generar un token de autenticación del Runner

  1. Haga clic en "Save and continue": CircleCI crea la resource class y muestra su token de autenticación
  2. Copie el token inmediatamente y guárdelo en un lugar seguro: solo se muestra una vez
  3. ¿Lo perdió? Cree uno nuevo con el CLI de CircleCI: circleci runner token create your-org/mac-runner mac-mini-m4

Añadir su token e iniciar el runner

# SSH back into your Mac mini
ssh admin@your-server-ip

# Replace YOUR_RUNNER_TOKEN_HERE with the resource class token
nano "$HOME/Library/Preferences/com.circleci.runner/config.yaml"

# Start the service. Headless Mac (plist moved to /Library/LaunchAgents):
launchctl bootstrap user/$(id -u) /Library/LaunchAgents/com.circleci.runner.plist
launchctl enable user/$(id -u)/com.circleci.runner
launchctl kickstart -k user/$(id -u)/com.circleci.runner

# Or, from a desktop session (VNC), with the plist left in ~/Library/LaunchAgents:
# launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.circleci.runner.plist
# launchctl enable gui/$(id -u)/com.circleci.runner
# launchctl kickstart -k gui/$(id -u)/com.circleci.runner

# Verify the service, then read the runner log
launchctl print user/$(id -u)/com.circleci.runner
tail -20 "$HOME/Library/Logs/com.circleci.runner/runner.log"

Una vez conectado, el runner aparece en Runners en la aplicación web de CircleCI, y circleci runner instance list your-org/mac-runner también lo muestra. Si no aparece en 60 segundos, verifique el archivo de log en busca de mensajes de error.

Usar el CLI de CircleCI (Alternativa)

También puede gestionar runners mediante el CLI de CircleCI:

# Install the CircleCI CLI
brew install circleci

# Authenticate with CircleCI
circleci setup

# Create the namespace (once per organization)
circleci namespace create your-org --org-id YOUR_ORGANIZATION_ID

# Create the resource class and print its token
circleci runner resource-class create your-org/mac-runner \
  "Mac mini M4 runner" --generate-token

# List the runners connected to this resource class
circleci runner instance list your-org/mac-runner

Paso 4: Crear su .circleci/config.yml para compilaciones iOS

Cree un archivo .circleci/config.yml en la raíz de su repositorio. La diferencia clave con una configuración estándar de CircleCI es usar machine: true con su resource_class personalizado para apuntar a su self-hosted runner.

version: 2.1

jobs:
  build-and-test:
    machine: true
    resource_class: your-org/mac-runner

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

    steps:
      - checkout

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

      # Caches live in $HOME, outside the job's working directory,
      # so they survive cleanup_working_directory between jobs
      - run:
          name: Resolve Swift Package Dependencies
          command: |
            xcodebuild -resolvePackageDependencies \
              -scheme "$SCHEME" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache"

      - run:
          name: Build the app
          command: |
            xcodebuild build \
              -scheme "$SCHEME" \
              -destination "generic/platform=iOS Simulator" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache" \
              -derivedDataPath "$HOME/DerivedData/$SCHEME" \
              | xcbeautify

      # store_test_results needs JUnit XML: xcbeautify writes test-results/junit.xml
      - run:
          name: Run unit tests
          command: |
            xcodebuild test \
              -scheme "$SCHEME" \
              -destination "$DESTINATION" \
              -clonedSourcePackagesDirPath "$HOME/spm-cache" \
              -derivedDataPath "$HOME/DerivedData/$SCHEME" \
              -resultBundlePath TestResults.xcresult \
              | xcbeautify --report junit --report-path test-results

      - store_test_results:
          path: test-results

      - store_artifacts:
          path: TestResults.xcresult
          destination: test-results

workflows:
  ios-pipeline:
    jobs:
      - build-and-test:
          filters:
            branches:
              only:
                - main
                - develop

Nota: El valor resource_class: your-org/mac-runner debe coincidir exactamente con la resource class que creó en el panel de CircleCI. Si no coincide, los jobs permanecerán en cola indefinidamente.

Paso 5: Optimizar con caché y paralelismo

Una de las mayores ventajas de un self-hosted runner es la caché persistente. Debido a que el sistema de archivos del runner es persistente, no necesita cargar y descargar cachés como lo hace con los recursos en la nube de CircleCI. Sin embargo, hay optimizaciones adicionales para maximizar la velocidad de compilación.

Aprovechar DerivedData persistente

Como el disco del runner persiste entre compilaciones, DerivedData ya está cacheado automáticamente. Use una ruta consistente:

# In your config.yml steps, always use a consistent DerivedData path:
- run:
    name: Build with persistent cache
    command: |
      xcodebuild build \
        -scheme "$SCHEME" \
        -destination "$DESTINATION" \
        -derivedDataPath ~/DerivedData/"$SCHEME" \
        -clonedSourcePackagesDirPath ~/spm-cache \
        | xcbeautify

# Periodically clean old DerivedData on the runner (cron job):
# 0 3 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +

Persistencia de Workspace entre jobs

Use los workspaces de CircleCI para pasar los productos compilados a un job de pruebas, que puede ejecutarse en otro Mac de la misma resource class:

jobs:
  build:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Build for testing
          command: |
            xcodebuild build-for-testing \
              -scheme "MyApp" \
              -destination "generic/platform=iOS Simulator" \
              -derivedDataPath DerivedData \
              | xcbeautify
      # Pass only the built products, not the whole DerivedData
      - persist_to_workspace:
          root: .
          paths:
            - DerivedData/Build/Products

  test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Run the tests built by the previous job
          command: |
            xcodebuild test-without-building \
              -xctestrun "$(ls DerivedData/Build/Products/*.xctestrun | head -n 1)" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results

workflows:
  build-test:
    jobs:
      - build
      - test:
          requires:
            - build

Ejecución paralela de pruebas

- run:
    name: Run tests in parallel
    command: |
      # Xcode clones the simulator and runs test classes on up to 4 clones
      xcodebuild test \
        -scheme "MyApp" \
        -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
        -parallel-testing-enabled YES \
        -maximum-parallel-testing-workers 4 \
        -derivedDataPath ~/DerivedData/MyApp \
        | xcbeautify

División de pruebas de CircleCI

Para suites de pruebas grandes, la división de pruebas de CircleCI reparte las clases de prueba entre tareas paralelas. Cada tarea necesita su propio runner, así que parallelism: 3 requiere tres Mac en la resource class; en un solo Mac, las tareas se ejecutan una tras otra:

jobs:
  test:
    machine: true
    resource_class: your-org/mac-runner
    # One task per runner: 3 tasks need 3 Macs in this resource class
    parallelism: 3
    steps:
      - checkout
      - run:
          name: Split test classes and run this task's share
          command: |
            # One XCTest class per file, named like the file (LoginTests.swift)
            CLASSES=$(circleci tests glob "MyAppTests/**/*Tests.swift" \
              | xargs -n1 basename | sed 's/\.swift$//' \
              | circleci tests split)

            # -only-testing takes Target/Class identifiers, not file paths
            ONLY_TESTING=""
            for CLASS in $CLASSES; do
              ONLY_TESTING="$ONLY_TESTING -only-testing:MyAppTests/$CLASS"
            done

            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              $ONLY_TESTING \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results

Ejemplos de Workflows

Aquí tiene ejemplos de workflows completos y listos para producción para escenarios comunes de CI/CD de iOS.

Pipeline completo de compilación, pruebas y despliegue iOS

version: 2.1

jobs:
  lint:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Run SwiftLint
          command: swiftlint lint --reporter json > swiftlint-results.json || true
      - store_artifacts:
          path: swiftlint-results.json

  build-and-test:
    machine: true
    resource_class: your-org/mac-runner
    environment:
      # Xcode for this job, without sudo
      # (preinstalled Xcode; for another version, use the path from `xcodes installed`)
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
    steps:
      - checkout
      - run:
          name: Resolve dependencies
          command: |
            xcodebuild -resolvePackageDependencies \
              -scheme "MyApp" \
              -clonedSourcePackagesDirPath ~/spm-cache
      - run:
          name: Build and test
          command: |
            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
              -clonedSourcePackagesDirPath ~/spm-cache \
              -derivedDataPath ~/DerivedData/MyApp \
              -resultBundlePath TestResults.xcresult \
              -parallel-testing-enabled YES \
              | xcbeautify --report junit --report-path test-results
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: TestResults.xcresult

  deploy-testflight:
    machine: true
    resource_class: your-org/mac-runner
    environment:
      DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      # MATCH_PASSWORD and the App Store Connect API key variables
      # (ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_CONTENT) come from a CircleCI
      # context or the project's environment variables
      - run:
          name: Build and upload to TestFlight
          command: bundle exec fastlane beta

workflows:
  ios-pipeline:
    jobs:
      - lint
      - build-and-test:
          requires:
            - lint
      - deploy-testflight:
          requires:
            - build-and-test
          filters:
            branches:
              only: main

Ejemplo de integración con Fastlane

Si usa Fastlane para la automatización de compilaciones, aquí le mostramos cómo integrarlo con su CircleCI self-hosted runner:

# Fastfile (fastlane/Fastfile)
default_platform(:ios)

platform :ios do
  desc "Run tests"
  lane :test do
    scan(
      scheme: "MyApp",
      device: "iPhone 17",
      derived_data_path: File.expand_path("~/DerivedData/MyApp"),
      result_bundle: true,
      output_directory: "./test_output",
      # store_test_results reads JUnit XML
      output_types: "junit",
      output_files: "junit.xml"
    )
  end

  desc "Build and push to TestFlight"
  lane :beta do
    # App Store Connect API key: no Apple ID password or 2FA on the runner
    app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_content: ENV["ASC_KEY_CONTENT"]
    )
    match(type: "appstore", readonly: true)
    increment_build_number(
      build_number: ENV["CIRCLE_BUILD_NUM"]
    )
    gym(
      scheme: "MyApp",
      export_method: "app-store",
      derived_data_path: File.expand_path("~/DerivedData/MyApp")
    )
    pilot(skip_waiting_for_build_processing: true)
  end
end
# .circleci/config.yml using Fastlane
version: 2.1

jobs:
  fastlane-test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Run Fastlane tests
          command: bundle exec fastlane test
      - store_test_results:
          path: ./test_output
      - store_artifacts:
          path: ./test_output

  fastlane-deploy:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Deploy to TestFlight
          command: bundle exec fastlane beta

workflows:
  ios-workflow:
    jobs:
      - fastlane-test
      - fastlane-deploy:
          requires:
            - fastlane-test
          filters:
            branches:
              only: main

Comparación de rendimiento

Aquí tiene una comparación detallada de rendimiento y costes entre los recursos macOS en la nube de CircleCI y un Mac Mini M4 self-hosted de MyRemoteMac:

Benchmarks de tiempo de compilación

Benchmarks de tiempo de compilación
Self-Hosted Mac Mini M4 CircleCI Cloud macOS Mejora
Compilación limpia (app mediana) 5 min 14 min 2.8x más rápido
Compilación incremental 1.5 min 14 min (sin caché) 9.3x más rápido
Resolución de dependencias SPM 5 seg (cacheado en disco) 3-5 min (descarga cada vez) ~60x más rápido
Suite de pruebas unitarias (500 pruebas) 2.5 min 8 min 3.2x más rápido
Tiempo de espera en cola 0 seg 30s - 5 min Instantáneo

Análisis de costes mensuales

Análisis de costes mensuales
Tamaño del equipo Coste MyRemoteMac Compilaciones/Mes Coste CircleCI Cloud Ahorro mensual
Desarrollador individual $85/mes 100 compilaciones (10 min promedio) $120/mes $35/mes
Equipo pequeño (5) $85/mes 500 compilaciones (10 min promedio) $600/mes $515/mes
Equipo mediano (15) $229/mes (M4 Pro) 1500 compilaciones (10 min promedio) $1,800/mes $1,571/mes
Empresa (50+) $458/mes (2x M4 Pro) 5000+ compilaciones $6,000+/mes $5,542+/mes

Precios de My Remote Mac en USD, sin impuestos.

Conclusión: Con la tarifa de CircleCI para la clase m4pro.medium (200 créditos, unos $0.12 por minuto, a octubre de 2026), una compilación de 10 minutos cuesta unos $1.20, así que un Mac mini M4 dedicado a $85/mes (USD, sin impuestos) sale más barato a partir de unas 71 compilaciones al mes. Las cachés precargadas de un Mac persistente también reducen el tiempo que su equipo espera en cada compilación.

Solución de problemas comunes

El Runner se desconecta o aparece como "Offline"

El runner puede perder la conexión tras un problema de red, un fallo o un reinicio. Si se inició en el dominio gui, solo vuelve cuando su usuario inicia sesión; la configuración headless del Paso 2 lo evita. Revise el servicio y su log:

# Check the service (use gui/ instead of user/ if you started it
# from a desktop session)
launchctl print user/$(id -u)/com.circleci.runner

# View the runner log
tail -50 "$HOME/Library/Logs/com.circleci.runner/runner.log"

# Restart the service
launchctl kickstart -k user/$(id -u)/com.circleci.runner

# If the token was revoked, create a new one, put it in
# ~/Library/Preferences/com.circleci.runner/config.yaml and restart
circleci runner token create your-org/mac-runner mac-mini-m4

resource_class no encontrada o jobs atascados en cola

Si los jobs se quedan en cola con "No matching runner found", la resource class en su configuración no coincide con el panel:

# Verify the exact resource class name in the CircleCI web app:
# Runners (sidebar) lists your resource classes

# The resource_class in .circleci/config.yml must match exactly:
# resource_class: your-org/mac-runner  (case-sensitive!)

# Check your runner is online:
circleci runner instance list your-org/mac-runner

# Common mistakes:
# - Wrong namespace (org name vs personal namespace)
# - Typo in resource class name
# - Runner is offline or token is invalid
# - Using 'docker' executor instead of 'machine: true'

Errores de firma de código en Xcode

La firma de código en una máquina CI requiere una gestión cuidadosa del keychain. El proceso del runner puede no tener acceso al keychain de inicio de sesión:

# Option 1: Use Fastlane Match (recommended)
# In your Fastfile:
match(type: "appstore", readonly: true)

# Option 2: Manual keychain management in your job steps
- run:
    name: Setup code signing
    command: |
      # Decode and import the certificate
      echo "$BUILD_CERTIFICATE_BASE64" | base64 --decode > /tmp/cert.p12

      # Create a temporary keychain
      security create-keychain -p "ci" /tmp/ci.keychain
      security set-keychain-settings -lut 21600 /tmp/ci.keychain
      security unlock-keychain -p "ci" /tmp/ci.keychain

      # Import the certificate
      security import /tmp/cert.p12 -P "$P12_PASSWORD" \
        -A -t cert -f pkcs12 -k /tmp/ci.keychain
      # Let codesign use the key without a GUI prompt
      security set-key-partition-list -S apple-tool:,apple:,codesign: \
        -s -k "ci" /tmp/ci.keychain
      security list-keychain -d user -s /tmp/ci.keychain

      # Install the provisioning profile (Xcode 16 and later location)
      PROFILES=~/Library/Developer/Xcode/UserData/Provisioning\ Profiles
      mkdir -p "$PROFILES"
      echo "$PROVISIONING_PROFILE_BASE64" | base64 --decode \
        > "$PROFILES/profile.mobileprovision"

El simulador no arranca o se agota el tiempo de espera

Los simuladores pueden quedar en mal estado en máquinas CI de larga ejecución. Reinícielos entre compilaciones:

# Add a pre-build step to clean simulators
- run:
    name: Reset simulators
    command: |
      xcrun simctl shutdown all 2>/dev/null || true
      xcrun simctl erase all 2>/dev/null || true

# If a specific runtime is missing, reinstall it:
xcodebuild -downloadPlatform iOS

# List available simulators
xcrun simctl list devices available

Espacio en disco insuficiente

Las compilaciones de Xcode generan cantidades significativas de datos. Configure una limpieza automática en su runner:

# Check available disk space
df -h /

# Clean DerivedData folders unused for a week
find ~/DerivedData ~/Library/Developer/Xcode/DerivedData \
  -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} +

# Delete simulators the current Xcode no longer supports
xcrun simctl delete unavailable

# List simulator runtimes, then delete the ones you no longer test on
xcrun simctl runtime list
# xcrun simctl runtime delete <runtime-identifier>

# Clean Homebrew cache
brew cleanup --prune=7

# Set up a weekly cron job for automatic cleanup
(crontab -l 2>/dev/null; echo "0 4 * * 0 find ~/DerivedData -mindepth 1 -maxdepth 1 -mtime +7 -exec rm -rf {} + ; /opt/homebrew/bin/brew cleanup --prune=7") | crontab -

Preguntas frecuentes

¿Cuánto cuesta un CircleCI self-hosted runner en Mac Mini M4?
Un Mac mini M4 dedicado de My Remote Mac comienza en $85/mes (USD, sin impuestos) con minutos de compilación ilimitados, y CircleCI no cobra por minuto de compilación en los self-hosted runners. Los jobs macOS en la nube de CircleCI cuestan unos $0.12 por minuto en la clase m4pro.medium (200 créditos a $0.0006 cada uno, a octubre de 2026), aproximadamente $300-500/mes para equipos activos. Con su propio runner, los costes siguen siendo predecibles sea cual sea el volumen de compilaciones.
¿Puedo usar un CircleCI self-hosted runner para compilaciones iOS y macOS?
Sí. Un self-hosted runner en un Mac Mini M4 puede ejecutar cualquier carga de trabajo macOS, incluyendo compilaciones iOS, compilaciones de apps macOS, pruebas de paquetes Swift, pruebas de interfaz XCUITest y automatización con Fastlane. Como se ejecuta de forma nativa en Apple Silicon, las compilaciones son más rápidas que en runners en la nube emulados o basados en Intel.
¿Cuál es la diferencia entre CircleCI machine runner y container runner?
CircleCI machine runner ejecuta los jobs directamente en el sistema operativo de la máquina host, lo cual es necesario para compilaciones macOS/iOS que requieren Xcode, simuladores y frameworks de Apple. Container runner ejecuta jobs dentro de contenedores Docker y solo está disponible en Linux. Para compilaciones Mac, debe usar el machine runner.
¿Cómo mantengo actualizado mi CircleCI self-hosted runner?
El machine runner 3 no se actualiza solo: con el paquete de Homebrew, usted decide cuándo actualizar ejecutando brew upgrade circleci-runner y luego reinicia el servicio. Revise el changelog del runner cada mes y mantenga también Xcode y macOS actualizados.
¿Es un self-hosted runner más rápido que CircleCI cloud macOS?
Sí, típicamente 2-3x más rápido para compilaciones limpias y hasta 9x más rápido para compilaciones incrementales. CircleCI ejecuta cada job macOS en la nube en una máquina virtual M4 Pro nueva, así que DerivedData y las cachés de paquetes deben restaurarse cada vez. Un Mac mini M4 self-hosted es una máquina física dedicada a usted, con cachés persistentes de DerivedData y SPM y sin esperar a que arranque una máquina en la nube.
¿Puedo ejecutar múltiples jobs de CircleCI simultáneamente en un Mac Mini?
No con un solo runner. CircleCI admite un único machine runner por máquina y cada runner procesa un job a la vez, así que los jobs enviados a la misma resource class esperan a que el Mac quede libre. Para ejecutar jobs en paralelo, añada un Mac por cada job simultáneo adicional y regístrelo en la misma resource class: CircleCI envía cada job en cola a un runner libre, dentro del límite de tareas self-hosted simultáneas de su plan (5 en Free, 20 en Performance, a octubre de 2026). Dentro de un job, Xcode puede seguir ejecutando pruebas en paralelo en varios simuladores. Para jobs más pesados, el Mac mini M4 Pro (CPU de 12 núcleos, 24 GB, desde $229/mes, USD, sin impuestos) ofrece más margen.

Comience con un Mac Mini M4 para sus pipelines de CircleCI

Despliegue un Mac Mini M4 dedicado como su CircleCI self-hosted runner. Minutos de compilación ilimitados 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 →