9 min de lectura

Flutter con GitHub Actions: compila y publica en Google Play y TestFlight

Guía ES-CO para automatizar Flutter con GitHub Actions sin fastlane: un solo release.yml que prueba, firma y sube el AAB a prueba interna de Google Play y el IPA a TestFlight, con secretos, caché, artefactos y errores comunes.

Portada: Flutter con GitHub Actions, Android e iOS con un solo workflow; tarjeta Workflow de release con release.yml, AAB a Play en prueba interna, IPA a TestFlight y caché de Flutter

Ya tienes tu app lista, pero cada versión significa compilar el AAB, firmarlo, abrir Play Console, generar el IPA en tu Mac y subirlo a TestFlight a mano. Con Flutter y GitHub Actions puedes convertir todo eso en un solo workflow: haces push de una etiqueta y GitHub compila, firma y entrega tu app a Google Play y a TestFlight mientras tú sigues programando. En esta guía armamos el archivo YAML completo, sin fastlane, con los secretos de firma de Android e iOS, caché y artefactos descargables.

Qué necesitas antes de empezar

  • Un repositorio en GitHub con tu proyecto Flutter.
  • Para Android: tu keystore de carga (si aún no lo tienes, sigue la guía para generar el keystore en Android) y la firma configurada en android/app/build.gradle.kts con el archivo key.properties, como indica la documentación de Flutter.
  • Una cuenta de servicio de Google Cloud con acceso a tu app en Play Console. Te explicamos cómo crearla en la guía de la API de Google Play Console.
  • La app ya creada en Play Console y una primera versión subida a mano: la API de Google Play no puede crear la app por ti.
  • Para iOS: un certificado de distribución exportado como .p12, un perfil de aprovisionamiento de tipo App Store y una API key de App Store Connect (archivo .p8, Key ID e Issuer ID).

No necesitas una Mac propia para el job de iOS, porque corre en un runner macOS de GitHub. Eso sí, exportar el certificado y el perfil la primera vez es más fácil desde una Mac.

Paso 1: guarda los secretos en GitHub

En tu repositorio ve a Settings > Secrets and variables > Actions > New repository secret. Los archivos binarios se guardan en base64:

base64 -i upload-keystore.jks | pbcopy        # macOS
base64 -w 0 upload-keystore.jks               # Linux

Crea estos secretos (los nombres son una propuesta; usa los que quieras, pero los mismos en el YAML):

SecretoContenido
ANDROID_KEYSTORE_BASE64El .jks en base64
ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, ANDROID_KEY_PASSWORDDatos de tu keystore
PLAY_SERVICE_ACCOUNT_JSONEl JSON de la cuenta de servicio, en texto plano
IOS_P12_BASE64, IOS_P12_PASSWORDCertificado de distribución y su contraseña
IOS_PROFILE_BASE64Perfil .mobileprovision en base64
KEYCHAIN_PASSWORDCualquier cadena aleatoria
ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_P8_BASE64Datos de la API key de App Store Connect

GitHub oculta los secretos en los logs, pero no hagas echo de ellos. Además, los workflows que se disparan desde un pull request de un fork no reciben tus secretos, así que nadie externo puede firmar con tus claves.

Paso 2: prepara la firma de iOS en el proyecto

En CI no hay sesión de Apple iniciada en Xcode, por eso la firma automática no sirve. Abre ios/Runner.xcworkspace, ve a Runner > Signing & Capabilities, y en la configuración Release desactiva Automatically manage signing y elige tu perfil App Store.

Luego crea ios/ExportOptions.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key><string>app-store-connect</string>
  <key>teamID</key><string>TU_TEAM_ID</string>
  <key>signingStyle</key><string>manual</string>
  <key>provisioningProfiles</key>
  <dict>
    <key>com.tuempresa.tuapp</key><string>Nombre de tu perfil</string>
  </dict>
</dict>
</plist>

En versiones de Xcode anteriores a la 15.3 el método se llama app-store. Compílalo una vez en local con flutter build ipa --export-options-plist=ios/ExportOptions.plist para confirmar que funciona antes de llevarlo a CI.

El workflow de Flutter con GitHub Actions paso a paso

Crea .github/workflows/release.yml. Tiene tres jobs: pruebas en Linux, Android en Linux e iOS en macOS. Los dos últimos solo arrancan si pasan las pruebas.

name: Release

on:
  push:
    tags: ['v*']
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          channel: stable
          cache: true
      - run: flutter pub get
      - run: flutter analyze
      - run: flutter test

  android:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
      - uses: subosito/flutter-action@v2
        with:
          channel: stable
          cache: true
      - name: Restaurar keystore
        env:
          KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
        run: |
          echo "$KEYSTORE_BASE64" | base64 --decode > android/app/upload-keystore.jks
          cat > android/key.properties <<'PROPS'
          storePassword=${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
          keyPassword=${{ secrets.ANDROID_KEY_PASSWORD }}
          keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}
          storeFile=upload-keystore.jks
          PROPS
      - run: flutter build appbundle --release --build-number=${{ github.run_number }}
      - uses: actions/upload-artifact@v4
        with:
          name: android-aab
          path: build/app/outputs/bundle/release/app-release.aab
          retention-days: 14
      - uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
          packageName: com.tuempresa.tuapp
          releaseFiles: build/app/outputs/bundle/release/app-release.aab
          tracks: internal
          status: completed

  ios:
    needs: test
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          channel: stable
          cache: true
      - name: Instalar certificado y perfil
        env:
          P12_BASE64: ${{ secrets.IOS_P12_BASE64 }}
          P12_PASSWORD: ${{ secrets.IOS_P12_PASSWORD }}
          PROFILE_BASE64: ${{ secrets.IOS_PROFILE_BASE64 }}
          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
        run: |
          CERT=$RUNNER_TEMP/cert.p12
          PP=$RUNNER_TEMP/profile.mobileprovision
          KC=$RUNNER_TEMP/app-signing.keychain-db
          echo -n "$P12_BASE64" | base64 --decode -o $CERT
          echo -n "$PROFILE_BASE64" | base64 --decode -o $PP
          security create-keychain -p "$KEYCHAIN_PASSWORD" $KC
          security set-keychain-settings -lut 21600 $KC
          security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KC
          security import $CERT -P "$P12_PASSWORD" -A -t cert -f pkcs12 -k $KC
          security set-key-partition-list -S apple-tool:,apple: -k "$KEYCHAIN_PASSWORD" $KC
          security list-keychain -d user -s $KC
          mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
          cp $PP ~/Library/MobileDevice/Provisioning\ Profiles
      - run: flutter build ipa --release --build-number=${{ github.run_number }} --export-options-plist=ios/ExportOptions.plist
      - uses: actions/upload-artifact@v4
        with:
          name: ios-ipa
          path: build/ios/ipa/*.ipa
          retention-days: 14
      - name: Subir a TestFlight
        env:
          ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
          ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
          ASC_KEY_P8_BASE64: ${{ secrets.ASC_KEY_P8_BASE64 }}
        run: |
          mkdir -p ~/.appstoreconnect/private_keys
          echo -n "$ASC_KEY_P8_BASE64" | base64 --decode -o ~/.appstoreconnect/private_keys/AuthKey_$ASC_KEY_ID.p8
          xcrun altool --upload-app --type ios -f build/ios/ipa/*.ipa --apiKey "$ASC_KEY_ID" --apiIssuer "$ASC_ISSUER_ID"

Cambia com.tuempresa.tuapp por tu package name y el nombre del perfil por el tuyo.

Qué hace cada parte

  • Disparador: el workflow corre cuando haces push de una etiqueta como v1.4.0 (git tag v1.4.0 && git push origin v1.4.0) o cuando lo lanzas a mano desde la pestaña Actions con workflow_dispatch. Así no publicas en cada commit.
  • Instalación de Flutter: subosito/flutter-action instala el SDK. Para builds reproducibles, cambia channel: stable por flutter-version-file: pubspec.yaml o fija la versión exacta que usa tu equipo.
  • Número de build: --build-number=${{ github.run_number }} asigna un número que sube solo en cada ejecución. Google Play rechaza un versionCode repetido y App Store Connect también exige un número de build nuevo. Si ya publicaste versiones con números altos, súmale un margen al valor.
  • Firma de Android: el keystore se reconstruye desde base64 y key.properties se escribe en el runner; ninguno de los dos va al repositorio. Agrega ambos a tu .gitignore.
  • Subida a Google Play: r0adkll/upload-google-play es una acción de la comunidad (no de Google) que usa la Google Play Developer API con tu cuenta de servicio. Con tracks: internal la versión llega a prueba interna.
  • Firma de iOS: es el procedimiento de la documentación de GitHub: llavero temporal, importar el .p12 y copiar el perfil. En los runners alojados por GitHub la máquina se destruye al terminar.
  • Subida a TestFlight: el comando xcrun altool --upload-app es el que recomienda la documentación de Flutter, autenticado con la API key. altool busca el .p8 en ~/.appstoreconnect/private_keys.

Caché y artefactos

Con cache: true, la acción guarda el SDK de Flutter y, por compatibilidad, también las dependencias de pub; desde la segunda ejecución te ahorras esa descarga. actions/upload-artifact deja el AAB y el IPA en la página de la ejecución para que puedas descargarlos o probarlos aunque la subida a la tienda falle. retention-days limita cuánto tiempo se guardan.

Lleva la versión a producción

El workflow sube el AAB a prueba interna y el IPA a TestFlight. Es el punto de partida más seguro: pruebas con tu equipo y luego promueves la versión desde Play Console o envías a revisión desde App Store Connect. Si quieres publicar directo en otra pista, cambia tracks por alpha, beta o production. Con status: inProgress y el parámetro userFraction de la acción puedes hacer un lanzamiento por fases.

Errores comunes con Flutter y GitHub Actions

  • «Package not found» al subir a Play: la app no existe en Play Console o nunca subiste una versión manual. Sube la primera a mano.
  • La cuenta de servicio no tiene permiso: invítala en Play Console, en Usuarios y permisos, con permiso para publicar versiones en tu app.
  • «No signing certificate iOS Distribution found»: el .p12 no incluye la clave privada o la contraseña no coincide. Expórtalo de nuevo desde Acceso a Llaveros con el certificado y su clave.
  • «Provisioning profile doesn't match»: el bundle ID del perfil, del proyecto y del ExportOptions.plist deben ser idénticos.
  • Build rechazado por número repetido: ajusta el margen del --build-number.
  • El job de iOS tarda o cuesta más de lo esperado: en repositorios privados, los minutos de macOS consumen tu cuota de GitHub mucho más rápido que los de Linux. Ejecuta iOS solo en etiquetas, no en cada pull request.

Preguntas frecuentes

¿Necesito fastlane para usar GitHub Actions con Flutter?

No. Este workflow usa solo comandos de Flutter, de Xcode y una acción para Play. Fastlane en Flutter suma ventajas si quieres manejar la ficha, las capturas o los certificados con match, y se puede llamar desde el mismo workflow.

¿Puedo compilar Flutter para iOS en GitHub Actions sin Mac?

Sí. El job corre en macos-latest, una máquina macOS de GitHub con Xcode. Solo necesitas una Mac (o alguien con una) para exportar el certificado la primera vez.

¿Cómo genero solo un APK con GitHub Actions?

Cambia el comando por flutter build apk --release y la ruta del artefacto por build/app/outputs/flutter-apk/app-release.apk. Para Google Play usa siempre el AAB.

¿Puedo distribuir con Firebase App Distribution?

Sí. En lugar de subir a Play o TestFlight, agrega un paso que use la CLI de Firebase (firebase appdistribution:distribute) con el APK o el IPA y tus grupos de testers.

¿Cómo hago que las pruebas corran en cada pull request?

Crea un segundo workflow solo con el job test y el disparador pull_request. Así revisas cada cambio sin gastar minutos de macOS.

Publica más rápido con AppConsol

El workflow automatiza la subida, pero cada tienda sigue pidiendo una ficha completa, capturas y una política de privacidad válida. Prueba AppConsol: crea tu cuenta gratis y deja lista la publicación de tu app en Google Play y App Store desde un solo lugar.

Sigue aprendiendo