Configurar fastlane en un servidor de build Mac dedicado

Lo que necesitas antes

• Un Mac con Xcode, acceso de administrador y Homebrew.
• Un agente de CI en ese Mac: GitHub Actions, GitLab, Buildkite, Jenkins o CircleCI.
• Una cuenta de App Store Connect con permiso para crear API keys.
• Un repo Git privado para match, o un bucket de Google Cloud o S3.

1. Instala fastlane

La documentación de fastlane, leída en octubre de 2026, prefiere Bundler. Soporta Ruby 3.2 o posterior y recomienda 3.3 o posterior. Desaconseja el Ruby del sistema de macOS. Instala un Ruby actual con un gestor de versiones como rbenv. Luego añade un Gemfile al proyecto:

source "https://rubygems.org"

gem "fastlane"

gem install bundler
bundle update
git add Gemfile Gemfile.lock

Bundler fija la versión de fastlane en Gemfile.lock. Todas las máquinas y todas las ejecuciones de CI usan la misma. Ejecútalo como bundle exec fastlane.

En un solo servidor de build, el camino más sencillo es Homebrew. Trae su propio Ruby:

brew install fastlane

Elige un camino por proyecto. Si los mezclas, acabas con dos versiones de fastlane en la misma máquina.

2. Crea una API key de App Store Connect

fastlane recomienda las API keys en lugar de iniciar sesión con un Apple ID: sin aviso de doble factor, más rapidez y más fiabilidad. En App Store Connect, abre Users and Access, luego Integrations, luego App Store Connect API. Crea una Team Key. fastlane indica que las llamadas de aprovisionamiento necesitan una team key. Dale el rol mínimo que funcione. Apunta el Issuer ID y el Key ID. Descarga el archivo .p8 en el momento, porque Apple solo te deja descargarlo una vez.

mkdir -p ~/.appstoreconnect
mv ~/Downloads/AuthKey_ABC123XYZ.p8 ~/.appstoreconnect/
chmod 600 ~/.appstoreconnect/AuthKey_ABC123XYZ.p8

Guarda la clave en el Mac de build o en el almacén de secrets de tu CI. Nunca la subas al repositorio.

3. Configura match una vez, desde una máquina de desarrollo

bundle exec fastlane match init
bundle exec fastlane match development
bundle exec fastlane match appstore

match init pregunta dónde guardar los certificados y escribe un Matchfile. Los dos comandos siguientes crean certificados y perfiles y los guardan, cifrados, en ese almacenamiento. Elige una frase de contraseña robusta. El CI la lee de la variable MATCH_PASSWORD.

fastlane recomienda el modo readonly en todos los sistemas de CI. Así el CI solo descarga lo que existe y nunca crea ni revoca nada.

4. Escribe los lanes

default_platform(:ios)

platform :ios do
  lane :test do
    run_tests(
      scheme: "MyApp",
      devices: ["iPhone 17"],
      result_bundle: true
    )
  end

  lane :beta do
    setup_ci
    api_key = app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_filepath: ENV["ASC_KEY_PATH"]
    )
    match(type: "appstore", readonly: is_ci, api_key: api_key)
    increment_build_number(
      build_number: latest_testflight_build_number(api_key: api_key) + 1
    )
    build_app(scheme: "MyApp")
    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: true)
  end
end

setup_ci crea un llavero temporal, pone match en modo readonly y prepara las rutas de logs y de resultados de tests. Solo actúa cuando fastlane detecta que está en CI. Si no detecta el tuyo, pasa force: true. Saltarse el procesamiento del build termina antes el job, pero fastlane avisa de que también se salta la distribución a testers externos.

5. Llámalo desde el CI

Todos los sistemas de CI ejecutan las mismas líneas de shell. Guarda los secrets en tu CI, no en el repositorio.

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
bundle install
bundle exec fastlane beta
# needs MATCH_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID and ASC_KEY_PATH set as CI secrets

En GitHub Actions, estas líneas van en un step run, con los secrets pasados como env. Un Mac de MacRun trae ya instalado el software del runner de GitHub Actions. Nuestra guía de configuración de iOS en GitHub Actions muestra un workflow completo. En GitLab, Buildkite o CircleCI, pon las mismas líneas en el script del job. En Jenkins, usa un step sh.

Cómo sobrevive a los reinicios

fastlane no es un servicio. Se ejecuta dentro del job de tu agente de CI. Lo que tiene que sobrevivir a un reinicio es el agente y su sesión. Configura el agente como LaunchAgent con inicio de sesión automático, como en nuestras guías de GitLab Runner y Buildkite. El llavero temporal de setup_ci se crea de nuevo en cada ejecución. Un llavero de inicio de sesión bloqueado tras un reinicio no puede atascarlo.

Errores comunes y soluciones

Están documentados por fastlane.

• Errores raros de codificación o cierres inesperados en CI. fastlane necesita un locale UTF-8. Pon LANG y LC_ALL a en_US.UTF-8.
• El job se cuelga en un aviso de doble factor. Usa la API key. Con un Apple ID, define SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA para que falle rápido.
• match intenta crear certificados nuevos en CI. Usa readonly, o llama antes a setup_ci.
• match no puede clonar su repositorio. GitHub no acepta la misma deploy key en dos repos. Usa una cuenta de máquina de solo lectura, o git_private_key, o MATCH_GIT_BASIC_AUTHORIZATION.
• Los perfiles están instalados pero Xcode no los ve. Xcode 16 cambió de sitio la carpeta de perfiles. fastlane sigue el Xcode seleccionado, así que ejecuta xcode_select antes de match en máquinas con dos Xcode.

Por qué ayuda un Mac dedicado

build_app y run_tests son builds de Xcode. En una máquina que conserva DerivedData y las gems instaladas, van mucho más rápido. En nuestro benchmark con la app de Wikipedia para iOS y Xcode 26.6, un build limpio tardó 86 segundos en un M6. Tardó 183 segundos en un runner macos-26 alojado en GitHub. Un job tras un cambio pequeño tardó 27 segundos en caliente, frente a 269 desde cero.

Cuándo no necesitas un servidor de build

Si publicas en TestFlight una vez por semana, un runner alojado o Xcode Cloud dan menos trabajo. Consulta nuestra guía de alternativas a Xcode Cloud para esa decisión. Ten en cuenta también lo que MacRun no hace. No gestionamos la firma de código por ti. Ejecutas match tú mismo, como en esta página. Tampoco ofrecemos SLA.

¿Listo para un servidor de build? En precios tienes todos los modelos, y la documentación de configuración explica cómo conectarte.