9 min de lectura

Fastlane en Flutter: publica en Google Play y TestFlight paso a paso

Guía ES-CO de fastlane en Flutter: instalación con Bundler, cuenta de servicio de Google Play y API key de App Store Connect, lanes listos para subir el AAB a prueba interna y el IPA a TestFlight, notas de la versión desde el repositorio, paso a CI y errores comunes.

Portada: Fastlane en Flutter, con tarjeta Lanes de publicación que muestra prueba interna con AAB, TestFlight con IPA, notas de versión 42.txt y CI automático

Compilar el AAB, abrir Play Console, subirlo, escribir las notas, repetir todo en Xcode y esperar a que la build llegue a TestFlight: si publicas seguido, ese ritual se come horas. Fastlane en Flutter resuelve justo eso. Es una herramienta de código abierto que automatiza la subida de tus builds y metadatos a Google Play y App Store Connect con un solo comando, en tu máquina o en un servidor de CI. En esta guía verás cómo configurar fastlane flutter para Android e iOS, qué credenciales necesita cada tienda, los lanes mínimos y los errores más comunes al empezar.

Qué es fastlane y por qué usarlo con Flutter

Fastlane es un conjunto de herramientas escritas en Ruby que hablan con las APIs de las tiendas. Tú defines "lanes" (carriles) en un archivo llamado Fastfile, y cada lane es una receta: por ejemplo, "sube este AAB a prueba interna" o "sube este IPA a TestFlight". Las acciones más usadas son:

  • upload_to_play_store (alias supply): sube AAB o APK, notas de la versión, textos de la ficha, íconos y capturas a Google Play.
  • upload_to_testflight (alias pilot): sube el IPA a App Store Connect y lo reparte a tus testers.
  • build_app (alias gym): archiva y exporta la app iOS.
  • match: sincroniza certificados y perfiles de aprovisionamiento entre máquinas.

Flutter no trae un comando propio para publicar, así que la documentación oficial de Flutter propone un esquema sencillo: Flutter compila (flutter build appbundle y flutter build ipa) y fastlane sube el resultado. Ese es el flujo que vas a montar aquí.

Requisitos antes de empezar

  1. Un proyecto Flutter que ya compile en release. Comprueba que flutter build appbundle y flutter build ipa terminan sin errores. Si es tu primera vez, sigue antes la guía para publicar una app Flutter en Play Store.
  2. La app ya creada en las dos consolas. En Google Play, la documentación de fastlane pide subir al menos una build a mano antes de poder usar supply. En App Store Connect, la app y su Bundle ID deben existir.
  3. Ruby y fastlane. La documentación de fastlane indica que soporta Ruby 3.2 o superior y prefiere 3.3 o más. En macOS puedes instalarlo con brew install fastlane; lo recomendado es usar Bundler con un Gemfile.
  4. Una Mac para la parte de iOS. La firma y el archivado de iOS requieren Xcode. Android puede automatizarse desde Linux o Windows.

Cómo configurar fastlane en Flutter paso a paso

Paso 1: instala fastlane con Bundler

En las carpetas android/ e ios/ de tu proyecto crea un Gemfile:

source "https://rubygems.org"

gem "fastlane"

Ejecuta bundle update en cada carpeta y versiona Gemfile y Gemfile.lock. A partir de ahí usa siempre bundle exec fastlane <lane>: así tu equipo y tu CI usan exactamente la misma versión.

Para iOS, la guía de Flutter pide además definir la variable de entorno FLUTTER_ROOT apuntando a la carpeta de tu SDK de Flutter.

Paso 2: inicializa fastlane en cada plataforma

Entra en android/ y ejecuta fastlane init; luego haz lo mismo en ios/. Se crea una carpeta fastlane/ con dos archivos clave:

  • Appfile: identifica tu app. En Android revisa que package_name coincida con tu applicationId; en iOS, que app_identifier coincida con el Bundle ID de tu Info.plist.
  • Fastfile: aquí escribirás tus lanes.

Paso 3: crea las credenciales de cada tienda

Google Play usa una cuenta de servicio de Google Cloud con la Google Play Developer API habilitada. Descargas su clave JSON e invitas el correo de la cuenta de servicio en Usuarios y permisos de Play Console. Tenemos el proceso completo en la guía de la API de Google Play Console. Antes de seguir, prueba la conexión:

bundle exec fastlane run validate_play_store_json_key json_key:/ruta/clave.json

App Store Connect funciona mejor con una API key (archivo .p8, Key ID e Issuer ID) que con tu Apple ID y contraseña: no depende de la verificación en dos pasos y sirve en CI. Si aún no la tienes, sigue la guía para crear la API key de App Store Connect.

Trata ambos archivos como contraseñas: nunca los subas a un repositorio público.

Paso 4: escribe el lane de Android

En android/fastlane/Fastfile:

default_platform(:android)

platform :android do
  desc "Sube el AAB a prueba interna"
  lane :interna do
    upload_to_play_store(
      track: "internal",
      aab: "../build/app/outputs/bundle/release/app-release.aab",
      json_key: ENV["PLAY_JSON_KEY_PATH"],
      skip_upload_metadata: true,
      skip_upload_images: true,
      skip_upload_screenshots: true
    )
  end
end

La ruta ../build/app/outputs/bundle/release/app-release.aab es la que propone la documentación de Flutter para reutilizar el AAB que ya generó flutter build. Opciones útiles:

  • track: internal, alpha, beta o production.
  • release_status: "draft": deja la versión como borrador para revisarla en Play Console antes de lanzarla.
  • rollout: "0.1": lanzamiento gradual (en este ejemplo, al 10 % de los usuarios).
  • validate_only: true: valida los cambios con Google Play sin publicar nada; ideal para tu primera prueba.

Paso 5: escribe el lane de iOS

En ios/fastlane/Fastfile:

default_platform(:ios)

platform :ios do
  desc "Sube la build a TestFlight"
  lane :beta do
    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"]
    )
    build_app(
      skip_build_archive: true,
      archive_path: "../build/ios/archive/Runner.xcarchive"
    )
    upload_to_testflight(
      api_key: api_key,
      skip_waiting_for_build_processing: true
    )
  end
end

skip_build_archive y archive_path evitan volver a compilar: fastlane solo exporta el archivo que ya generó flutter build ipa. Con skip_waiting_for_build_processing fastlane no se queda esperando a que Apple procese la build (útil en CI, donde pagas por minutos), pero en ese caso no reparte la build a testers externos.

Paso 6: ejecútalo en local

flutter build appbundle --build-number=42
cd android && bundle exec fastlane interna

flutter build ipa --build-number=42
cd ios && bundle exec fastlane beta

Cada subida necesita un número de build mayor que el anterior. Puedes aumentarlo en el version de tu pubspec.yaml (la parte después del +) o pasarlo con --build-number, como en el ejemplo.

Notas de la versión, ficha y capturas desde el repositorio

Si ejecutas fastlane supply init, fastlane descarga la ficha de Google Play a fastlane/metadata/android/<idioma>/: título, descripciones, imágenes y una carpeta changelogs/. Allí puedes crear un archivo por versión con el nombre exacto del versionCode (por ejemplo 42.txt) o un default.txt. Revisa los límites y buenas prácticas en nuestra guía de notas de la versión en Google Play.

Ojo con las capturas: según la documentación de supply, las imágenes que subes reemplazan las actuales de la ficha, no se suman. Si no quieres tocarlas, deja skip_upload_screenshots: true.

Pásalo a CI: GitHub Actions, Codemagic o Bitrise

Cuando funcione en local, muévelo a tu CI. La documentación de Flutter da tres reglas:

  1. Credenciales como secretos. En Android, guarda el contenido del JSON en una variable cifrada y léelo con json_key_data: ENV["..."]. El keystore de carga se guarda en base64 y se decodifica en el paso de instalación.
  2. Certificados iOS con match. Las máquinas de CI son efímeras; match guarda tus certificados y perfiles cifrados y los instala en cada ejecución.
  3. Sin imprimir secretos. No hagas echo de esas variables en los logs.

Ejecuta los trabajos de Android en Linux y los de iOS en macOS. En iOS, compila con flutter build ios --release --no-codesign --config-only y deja que fastlane firme y exporte.

Errores comunes con fastlane en Flutter

  • Google Play dice que la app no existe o el paquete no se encuentra: no subiste la primera build a mano, o el package_name del Appfile no coincide.
  • Error de permisos con la cuenta de servicio: el correo de la cuenta de servicio no está invitado en Play Console o no tiene permisos de versiones para esa app.
  • El código de versión ya se usó: olvidaste subir el número de build.
  • TestFlight pide verificación en dos pasos en CI: estás usando Apple ID en vez de API key.
  • No encuentra el certificado de firma: el certificado de distribución no está en la máquina; usa match o instálalo en el llavero antes de exportar.
  • Rutas que no existen: los lanes se ejecutan desde android/ o ios/, por eso las rutas al build empiezan con ../build/.

Preguntas frecuentes

¿Fastlane es gratis?

Sí. Es de código abierto. Lo que puede costar es el servicio de CI donde lo ejecutes.

¿Necesito una Mac para usar fastlane con Flutter?

Para Android, no. Para firmar y subir builds de iOS, sí necesitas macOS, ya sea tu propia Mac o una máquina macOS en tu CI.

¿Fastlane o Codemagic?

No son excluyentes. Codemagic y Bitrise son servicios de CI con soporte integrado para Flutter. Fastlane es la herramienta que sube a las tiendas y puede correr dentro de cualquier CI, incluido Codemagic.

¿Puedo publicar directo a producción con fastlane?

Sí, con track: "production". Aun así, conviene empezar por prueba interna o TestFlight y promover la versión cuando esté validada.

¿Cómo uso fastlane con GitHub Actions?

Instala Flutter y Ruby en el workflow, restaura tus secretos (JSON de Play, clave .p8, contraseña de match), compila y ejecuta bundle exec fastlane <lane> dentro de android/ o ios/.

Automatiza la subida y deja lista la ficha

Fastlane se encarga de mover tus builds, pero cada versión también necesita una ficha cuidada, capturas al día y políticas en regla. Prueba AppConsol: crea tu cuenta gratis y gestiona la publicación de tu app en Google Play y App Store desde un solo lugar.

Sigue aprendiendo