Cómo ejecutar un agente de Buildkite en un Mac

Lo que necesitas antes

• Un cluster de Buildkite y permiso para gestionar sus tokens de agente y sus colas. Tienes que ser administrador de la organización o maintainer del cluster.
• Un Mac con macOS 11 o posterior. Es el mínimo que indica Buildkite. Apple silicon, Homebrew, Xcode y acceso de administrador.
• Una clave SSH que el agente pueda usar para clonar tus repositorios.

1. Crea una cola y un token de agente

En Buildkite, selecciona Agents para ir a la página Clusters y elige tu cluster. En la página Queues, selecciona New Queue. Dale la clave macos y elige Self hosted. Luego abre Agent Tokens, selecciona New Token, añade una descripción y créalo. Copia el valor. Buildkite solo lo muestra una vez.

El formulario del token tiene un campo Allowed IP Addresses. Déjalo vacío en MacRun. Nuestros Macs no tienen una IP pública fija, así que una regla CIDR dejaría fuera al agente.

2. Instala el agente con Homebrew

brew tap buildkite/buildkite
brew trust buildkite/buildkite
brew install buildkite/buildkite/buildkite-agent

Homebrew 7.0.7, la versión de nuestro Mac en octubre de 2026, rechaza las fórmulas de un tap de terceros hasta que confías en él. Para eso es la línea del medio. La fórmula se llama ahora buildkite-agent@3, y el nombre antiguo de la documentación de Buildkite sigue apuntando a ella.

En Apple silicon, los archivos quedan en /opt/homebrew:

• Configuración: /opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• Hooks: /opt/homebrew/etc/buildkite-agent/hooks
• Log: /opt/homebrew/var/log/buildkite-agent.log

Ejecuta brew info buildkite-agent para ver las rutas exactas en tu máquina.

3. Añade el token y la etiqueta de cola

La documentación de Buildkite usa sed para cambiar el token de ejemplo. Sustituye el texto en mayúsculas por tu token.

sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
cat "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg | grep token

Luego abre el mismo archivo y define la línea de tags, para que el agente se una a tu cola:

tags="queue=macos"

Un agente pertenece a una sola cola self-hosted dentro de un cluster. Sin etiqueta de cola, se une a la cola por defecto. Si el cluster no tiene una cola self-hosted por defecto, Buildkite dice que el agente no consigue conectarse.

4. Pruébalo y luego ejecútalo como servicio

Arráncalo una vez en primer plano. Debería aparecer en la lista de agentes del cluster.

buildkite-agent start

Páralo con Control C. La fórmula de Homebrew trae una definición de servicio. Ejecuta buildkite-agent start con la configuración de arriba, se reinicia si falla y escribe en el mismo log. Arráncalo desde Terminal en el escritorio del Mac:

brew services start buildkite/buildkite/buildkite-agent@3
brew services list | grep buildkite

En macOS, el agente se ejecuta con el usuario que arrancó el servicio de launchd. Arráncalo con la cuenta que tiene Xcode y tus claves de firma.

Empieza con un agente por Mac. Buildkite documenta un ajuste spawn en el archivo de configuración, y un flag --spawn, para ejecutar varios agentes desde un servicio. Dos builds de Xcode a la vez compiten por los mismos núcleos y la misma memoria. En una máquina de 16 GB, mide primero un solo agente y luego prueba con dos.

5. Haz que sobreviva a un reinicio

Las propias notas de instalación de la fórmula dicen que configures el Mac para iniciar sesión automáticamente con este usuario. El README del tap de Buildkite explica el precio. Un LaunchAgent necesita una sesión iniciada, pero permite que los tests usen herramientas gráficas como el simulador de iOS. Activa el inicio de sesión automático en Ajustes del Sistema, en Usuarios y grupos. Luego desactiva el reposo, reinicia y revisa la lista de agentes.

sudo pmset -a sleep 0
sudo shutdown -r now

Deja el plist en la carpeta LaunchAgents de tu carpeta de inicio, que es donde lo pone Homebrew. En macOS 27 vimos que un plist en /Library/LaunchAgents rompía el inicio de sesión automático. Consulta inicio de sesión automático en un Mac sin pantalla.

6. Un paso de pipeline para el Mac

steps:
  - label: ":xcode: iOS tests"
    agents:
      queue: "macos"
    commands:
      - "rm -rf build/TestResults.xcresult"
      - "xcodebuild test -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' -resultBundlePath build/TestResults.xcresult"
      - "ditto -c -k --keepParent build/TestResults.xcresult build/TestResults.xcresult.zip"
    artifact_paths:
      - "build/TestResults.xcresult.zip"
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

El reintento con exit_status: -1 sale del ejemplo de command step de Buildkite. Reintenta un job cuando se perdió el propio agente, no cuando falló un test.

Errores comunes y soluciones

• launchctl dice Could not find domain for. Buildkite dice que tiene que haber un usuario con la sesión iniciada en el Mac. Inicia sesión en el escritorio y vuelve a cargar el servicio.
• Refusing to load formula ... from untrusted tap. Ejecuta brew trust buildkite/buildkite y vuelve a instalar.
• El agente no se conecta. El token está mal, o la clave de cola de tags no existe en este cluster.
• El agente no puede clonar. Pon la clave en ~/.ssh del usuario que ejecuta el agente.
• xcodebuild: error: Existing file at -resultBundlePath. Los builds reutilizan el checkout. Borra antes el bundle, como arriba.

Para actualizar más adelante, ejecuta brew update && brew upgrade buildkite/buildkite/buildkite-agent@3.

Por qué ayuda un Mac dedicado

Buildkite está pensado para tus propias máquinas, y un Mac persistente conserva sus cachés. En nuestro benchmark con la app de Wikipedia para iOS y Xcode 26.6, un job tras un cambio pequeño tardó 27 segundos en un M6 en caliente. Un runner macos-26 recién creado de GitHub tardó 269 segundos.

Cuándo bastan los agentes alojados de Buildkite

Buildkite también ofrece agentes de macOS alojados. Los eliges al crear una cola alojada, según su documentación leída en octubre de 2026. Si no quieres cuidar de ninguna máquina, es el camino más sencillo. MacRun tampoco es buena opción si necesitas un SLA, una IP fija para las reglas del token o más de una región.

Para la parte de MacRun, consulta otros sistemas de CI. Para saber qué ejecutar en los pasos, consulta la guía del pipeline de CI/CD para iOS.