Fastfile: qué es, estructura y configuración de la automatización en el desarrollo móvil

Qué es Fastfile y por qué lo necesitas

Fastfile es el archivo de configuración principal de Fastlane, escrito en Ruby y ubicado en el directorio fastlane en la raíz del proyecto. Define todos los escenarios de automatización (lanes) para compilar, probar, firmar código y distribuir la aplicación. Fastfile reemplaza docenas de scripts bash, Makefiles e instrucciones manuales con una única descripción declarativa del pipeline CI/CD.

La necesidad de Fastfile surge cuando un proyecto requiere compilaciones repetibles en diferentes máquinas de desarrolladores y servidores CI/CD. En lugar de que cada desarrollador configure el entorno manualmente, Fastfile captura todos los pasos en código que se puede versionar en Git, revisar y reutilizar entre proyectos. Un único Fastfile garantiza que la compilación en la máquina del desarrollador sea idéntica a la del servidor CI/CD.

Fastfile admite plataformas mediante la directiva default_platform. En un único Fastfile se pueden describir escenarios para iOS, Android y macOS, agrupándolos en bloques platform :ios y platform :android. Esto es especialmente útil para proyectos multiplataforma donde las compilaciones de iOS y Android comparten lógica de despliegue común pero usan diferentes herramientas de compilación.

Estructura de Fastfile: lanes, actions y parámetros

Fastfile consta de tres elementos principales: declaración de plataforma (default_platform), definición de lanes y configuración de funciones auxiliares. Cada lane comienza con la palabra clave lane, seguida del nombre del escenario (símbolo Ruby), el cuerpo con una secuencia de acciones y bloques de manejo de errores: error, success o ensure.

Las actions en Fastfile son llamadas a funciones integradas de Fastlane con parámetros en forma de Hash. Por ejemplo, gym(scheme: 'App', export_method: 'app-store') ejecuta una compilación de iOS con los parámetros especificados. Cada action devuelve un resultado que se puede guardar en una variable y usar en actions posteriores — esto permite lógica condicional dentro de un lane.

Fastfile admite variables de entorno mediante el mecanismo estándar ENV de Ruby. Los datos confidenciales (contraseñas, tokens, claves) no deben almacenarse en Fastfile — use variables de entorno del sistema CI/CD o un archivo .env añadido a .gitignore. Fastlane carga automáticamente los archivos .env del directorio fastlane al iniciar.

Appfile y Matchfile

Junto con Fastfile, en el directorio fastlane se encuentran archivos de configuración adicionales. Appfile contiene identificadores de aplicación (app_identifier), Apple ID y Team ID — estos datos se sustituyen automáticamente en todas las actions, eliminando la repetición en cada lane. Matchfile almacena la configuración de match: la URL del repositorio Git, el tipo de perfiles y la clave de cifrado.

Dividir la configuración en varios archivos facilita el mantenimiento de proyectos con diferentes entornos. Por ejemplo, para staging y producción, se pueden crear ramas separadas en el repositorio de Matchfile o sobrescribir parámetros mediante variables de entorno en el sistema CI/CD.

# Estructura básica de Fastfile
default_platform(:ios)

lane :build_and_test do
  cocoapods
  scan(scheme: 'App', devices: ['iPhone 15'])
  gym(scheme: 'App')
end

lane :deploy do
  match(type: 'appstore')
  build_and_test
  pilot(skip_waiting_for_build_processing: true)
end

Sintaxis de Fastfile: cómo escribir lanes

La sintaxis de Fastfile se basa en Ruby DSL (Domain Specific Language), diseñado específicamente para la legibilidad de escenarios de automatización. Un lane se declara mediante la construcción lane :name do ... end, donde name es un símbolo Ruby que se convierte en el comando fastlane name para ejecutar desde el terminal o sistema CI/CD.

Dentro de un lane se pueden usar operadores condicionales de Ruby: if, unless, case para ramificar la lógica. También están disponibles los bucles each y while para procesar arrays de valores. Fastlane proporciona métodos especiales before_all, after_all y bloques error para manejar eventos del ciclo de vida del lane.

Los parámetros de lane se pasan a través del hash options. Al ejecutar fastlane build --option_name value, el valor se coloca en options[:option_name] dentro del lane. Se pueden establecer valores predeterminados mediante optional: true y validación de tipo para controlar los tipos de parámetros pasados.

# Lane con parámetros y lógica condicional
lane :build do |options|
  scheme = options[:scheme] || 'App'
  export_method = options[:export_method] || 'development'

  match(type: export_method)

  if export_method == 'appstore'
    gym(scheme: scheme, export_method: 'app-store')
    pilot(skip_waiting_for_build_processing: true)
  else
    gym(scheme: scheme, export_method: export_method)
  end
end

Ejemplo de Fastfile para distribución en iOS

Un Fastfile completo para un proyecto iOS incluye lanes para instalación de dependencias, pruebas, compilación y despliegue en TestFlight y App Store. Veamos un ejemplo que cubre un proceso CI/CD típico desde el commit hasta la publicación en TestFlight para pruebas internas.

# Fastfile para distribución CI/CD en iOS
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  setup_travis if ENV['TRAVIS']
end

lane :tests do
  scan(
    scheme: 'App',
    devices: ['iPhone 15', 'iPad Pro 12.9'],
    output_directory: './test_reports'
  )
end

lane :build_appstore do
  match(type: 'appstore', readonly: true)
  gym(
    scheme: 'App',
    export_method: 'app-store',
    include_bitcode: true
  )
end

lane :deploy_testflight do
  build_appstore
  pilot(
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
  slack(
    message: 'Compilación subida a TestFlight para pruebas internas'
  )
end

En este ejemplo, el bloque before_all se ejecuta antes de cada lane e instala las dependencias. El lane tests ejecuta pruebas de UI y Unit en dos dispositivos. El lane build_appstore firma el código mediante match y compila el IPA con bitcode. El lane deploy_testflight combina todos los pasos para la distribución completa.

Despliegue con múltiples objetivos

Los proyectos con múltiples objetivos (aplicación principal, watchOS, widget, Notification Service Extension) requieren lanes separados para cada objetivo. En Fastfile se puede crear un lane universal :deploy_target que acepte el nombre del esquema y la ruta de compilación como parámetros. Esto permite ejecutar el despliegue para todas las extensiones mediante fastlane deploy_target scheme:Widget.

Para organizar múltiples objetivos, use un array de esquemas y un bucle each dentro del lane. Fastlane admite la compilación paralela de múltiples esquemas mediante el flag parallel: true, lo que reduce el tiempo total del pipeline CI/CD para aplicaciones con extensiones.

Ejemplo de Fastfile para compilación en Android

El Fastfile para proyectos Android usa la acción gradle para ejecutar tareas de Gradle y la acción supply para publicar en Google Play. A diferencia de iOS, Android no requiere match, pero usa un Keystore para la firma, que se almacena fuera del repositorio y se pasa mediante variables de entorno.

# Fastfile para compilación CI/CD en Android
default_platform(:android)

lane :build_release do
  gradle(task: 'clean')
  gradle(task: 'bundleRelease')
  gradle(task: 'assembleRelease')
end

lane :deploy_internal do
  build_release
  supply(
    track: 'internal',
    aab: 'app/build/outputs/bundle/release/app-release.aab',
    release_status: 'completed'
  )
end

Para la firma de Android, configure signingConfigs en build.gradle y pase los parámetros del Keystore mediante variables de entorno: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS y ANDROID_KEY_PASSWORD. Fastlane usa automáticamente el apksigner del sistema para firmar el AAB o APK compilado.

Firma de Android en Fastfile

Para configurar la firma de Android en Fastfile, use la acción sign_android o confíe en signingConfigs en build.gradle. Fastlane se integra con apksigner a través de Gradle — pasar el flag SIGNING_CONFIG en la tarea gradle activa la firma con parámetros de variables de entorno. Esto permite firmar archivos AAB antes de subirlos a Google Play Console.

Para el almacenamiento seguro del Keystore en CI/CD, use codificación Base64 y variables de entorno. Fastlane admite la acción setup_keystore, que decodifica el Keystore desde una variable y lo guarda en un archivo temporal durante la etapa before_all. Al finalizar el lane, el archivo temporal se elimina automáticamente para evitar la fuga de certificados.

Uso de private lanes y grupos

Los private lanes (escenarios privados) son lanes que no se pueden invocar directamente desde la línea de comandos, pero están disponibles para ser llamados desde otros lanes dentro de Fastfile. Un private lane se declara mediante la construcción private_lane :name do ... end y se usa para encapsular pasos repetitivos que no tienen sentido como escenarios independientes.

Los private lanes son ideales para agrupar lógica repetitiva: instalación de dependencias, configuración del entorno, envío de notificaciones. Por ejemplo, se puede crear un private lane :setup_signing que se llame desde varios lanes de despliegue, pero que no esté disponible para ejecución directa por parte del desarrollador para evitar errores.

# Private lane y agrupación
default_platform(:ios)

private_lane :setup_signing do |options|
  match(
    type: options[:type],
    readonly: true,
    verbose: false
  )
end

lane :beta do
  setup_signing(type: 'adhoc')
  gym(export_method: 'ad-hoc')
  pilot(distribute_external: true)
end

lane :release do
  setup_signing(type: 'appstore')
  gym(export_method: 'app-store')
  deliver(
    force: true,
    submit_for_review: true
  )
end

La agrupación de lanes mediante bloques platform permite separar escenarios de iOS y Android en un mismo Fastfile. La construcción platform :ios do ... end y platform :android do ... end aísla los lanes de la plataforma correspondiente, mientras que los private lanes comunes se pueden colocar fuera de los bloques de plataforma para su reutilización.

Paso de parámetros a lanes

El mecanismo de parámetros de Fastfile permite que los lanes sean flexibles y reutilizables. Los parámetros se pasan durante la ejecución a través de la línea de comandos: fastlane build scheme:App export_method:appstore. Dentro del lane, los valores son accesibles mediante el hash options, que se pasa al bloque del lane como argumento.

Fastlane admite parámetros tipados con validación mediante OptionalHash. Se puede especificar el tipo de valor (String, Boolean, Integer), un valor predeterminado y una descripción para la autogeneración de documentación. Las variables de entorno también están disponibles como forma alternativa de pasar parámetros, lo que resulta útil para sistemas CI/CD.

# Parámetros con validación de tipos
lane :build do |options|
  gym(
    scheme: options[:scheme],
    export_method: options[:export_method] || 'development',
    include_bitcode: options[:include_bitcode] || false,
    output_name: options[:output_name]
  )
  slack(message: "Compilación de #{options[:scheme]} finalizada")
end

# Ejecución: fastlane build scheme:MyApp export_method:appstore

Se recomienda usar valores predeterminados para todos los parámetros opcionales, de modo que un lane se pueda ejecutar sin especificar explícitamente cada argumento. Para los parámetros obligatorios, verifique su presencia al inicio del lane y detenga la ejecución con un mensaje de error claro mediante UI.user_error!.