Build automático de Android de Capacitor con acciones de GitHub

Configurar CI/CD para apps de Capacitor puede ser complejo y llevar mucho tiempo. Esto es lo que necesitas saber:

Recomendado para nuevos builds: Usa Capgo Build

Ahora recomendamos usar Capgo Build con el Capgo CLI para builds nativos de Capacitor. Esta guía de Fastlane se mantiene para equipos que gestionan pipelines existentes de GitHub Actions, pero las nuevas compilaciones de Android deben usar Capgo CLI para que no tengas que mantener tú mismo Fastlane, runners de Gradle, keystores y scripts de upload.

Requisitos

Antes de empezar, necesitarás configurar:

• Una cuenta de GitHub con acceso de administrador
• Tu app ya publicada en Google Play Store con la firma adecuada
• Clave de firma de Android y archivos keystore
• Proyecto en Google Cloud Console con la API de Play Store habilitada
• Cuenta de servicio con los permisos adecuados
• Conocimiento de los workflows de GitHub Actions
• Conocimiento de la configuración de Fastlane
• Tiempo para mantener y depurar el pipeline

Capgo Build para CI/CD por Capgo

Olvídate de mantener Fastlane, el runner de Gradle, el keystore y los scripts de upload. Build de Capgo ejecuta builds nativos de Android firmados desde tu pipeline de CI/CD actual:

• Funciona con tu pipeline: Dispara Capgo Build desde GitHub Actions, GitLab CI, Jenkins o scripts locales tras tu web build y npx cap sync.
• Firma mediante secretos de CI: Mantén los keystores de Android, alias de claves, contraseñas y el JSON de la cuenta de servicio de Play Console en tus propios secretos de CI.
• Sin mantenimiento de runners nativos: Capgo Build ofrece entornos de build para Android mantenidos, para que no tengas que gestionar imágenes SDK, problemas de caché de Gradle o lanes de Fastlane.
• Artifacts y envío: Descarga artifacts firmados para QA o envía builds de release mediante Capgo CLI.

Precios

• Los planes de Capgo desde $12/mes
• Incluye actualizaciones OTA y unos 15 Native Build al mes
• Los minutos de build extra se cobran por minuto mediante créditos

Configura Capgo Build en tu CI/CD

Guía de configuración manual

Esto es lo que tienes que hacer:

Precios de GitHub Actions

GitHub Actions ofrece minutos gratis según tu tipo de repo:

• Repositorios públicos: 2000 minutos/mes
• Repositorios privados: 2000 minutos/mes (runners Linux)

Para proyectos privados, el coste es de unos $0.008/min. Un build típico tarda 3-5 minutos.

Pasos de configuración manual

1. Crear un keystore de Android
2. Configurar la cuenta de servicio de Google Play
3. Configurar Fastlane
4. Configurar los secrets de GitHub
5. Crear el workflow de GitHub Actions

1. Crear el Android Keystore

Antes de firmar y publicar tu app de Android, debes crear un archivo keystore. Esto solo se hace una vez.

Generar el Keystore con keytool

Ejecuta este comando en tu terminal:

keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Se te pedirá lo siguiente:

• Contraseña del keystore: Elige una contraseña segura (la necesitarás como KEYSTORE_STORE_PASSWORD)
• Contraseña de la clave: Elige una contraseña segura (la necesitarás como KEYSTORE_KEY_PASSWORD)
• Tu nombre, organización, etc.: Completa tus datos

Notas importantes

• Guarda estos valores de forma segura:

  • Ubicación del archivo keystore (p. ej., my-release-key.keystore)
  • Alias de clave (p. ej., my-key-alias) - necesitarás esto como KEYSTORE_KEY_ALIAS
  • Contraseña del keystore - necesitarás esto como KEYSTORE_STORE_PASSWORD
  • Contraseña de la clave: la necesitarás para KEYSTORE_KEY_PASSWORD

• Haz un backup del archivo keystore: Si la pierdes, no podrás actualizar tu app publicada

• Mantenlo en secreto: Nunca hagas commit del archivo keystore a git

• Guárdalo de forma segura: Mantén varios backups en ubicaciones seguras

Alternativa: usar un keystore existente

Si ya publicaste tu app, debes usar el mismo keystore que usaste al principio. Puedes encontrarlo:

• En tu máquina local donde hiciste el primer build
• En tu Play Console → Configuración → Firma de apps (si usas Google Play App Signing)

2. Configurar la cuenta de servicio de Google Play

Para permitir que las acciones de GitHub suban builds a Google Play, necesitas una cuenta de servicio.

Paso 2.1: Crear proyecto de Google Cloud

1. Ve a Consola de Google Cloud
2. Crea un nuevo proyecto o selecciona uno existente
3. Anota el ID del proyecto

Paso 2.2: Habilitar la API de Google Play Developer

1. En Google Cloud Console, ve a APIs y servicios → Biblioteca
2. Busca “Google Play Android Developer API”
3. Haz clic Activar

Paso 2.3: Crear cuenta de servicio

1. Ve a IAM y administración → Cuentas de servicio
2. Haz clic Crear cuenta de servicio
3. Introduce los detalles:
   • Nombre: github-actions-uploader
   • Descripción: “Cuenta de servicio para que GitHub Actions suba builds”
4. Haz clic Crear y continuar
5. Omitir la asignación de roles por ahora (haz clic Continuar, luego Listo)

Paso 2.4: Crear clave de la cuenta de servicio

1. Haz clic en la cuenta de servicio recién creada
2. Ve a Claves pestaña
3. Haz clic Añadir clave → Crear nueva clave
4. Elige JSON formato
5. Haz clic Crear
6. Se descargará un archivo JSON - guárdalo de forma segura, lo necesitarás más tarde

Paso 2.5: Conceder acceso en Play Console

1. Ve a Google Play Console
2. Ve a Configuración → Acceso a API
3. En Cuentas de servicio, haz clic en Otorgar acceso para tu cuenta de servicio
4. En el Permisos de la app pestaña, añade tu app
5. En el Permisos de la cuenta tab, otorga estos permisos:
   • Ver información de la app y descargar informes masivos (solo lectura)
   • Crear, editar y eliminar apps en borrador
   • Publicar apps en canales de prueba
   • Publicar apps en producción, excluir y otros canales
6. Haz clic Invitar usuario
7. Haz clic Enviar invitación

Paso 2.6: Verificar la clave JSON

El archivo JSON descargado debería verse así:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "github-actions-uploader@your-project-id.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

Convertirás esto a base64 en el paso de configuración de secretos de GitHub.

3. Configurar Fastlane

Crea un fastlane carpeta en la raíz de tu proyecto y añade un Fastfile con este contenido:

default_platform(:android)

KEYSTORE_KEY_ALIAS = ENV["KEYSTORE_KEY_ALIAS"]
KEYSTORE_KEY_PASSWORD = ENV["KEYSTORE_KEY_PASSWORD"]
KEYSTORE_STORE_PASSWORD = ENV["KEYSTORE_STORE_PASSWORD"]

platform :android do
    desc "Deploy a beta version to the Google Play"
    private_lane :verify_changelog_exists do |version_code: |
      changelog_path = "android/metadata/en-US/changelogs/#{version_code}.txt"
      UI.user_error!("Missing changelog file at #{changelog_path}") unless File.exist?(changelog_path)
      UI.message("Changelog exists for version code #{version_code}")
    end

    private_lane :verify_upload_to_staging do |version_name: |
      UI.message "Skipping staging verification step"
    end
    
    lane :beta do
        keystore_path = "#{Dir.tmpdir}/build_keystore.keystore"
        File.write(keystore_path, Base64.decode64(ENV['ANDROID_KEYSTORE_FILE']))
        json_key_data = Base64.decode64(ENV['PLAY_CONFIG_JSON'])
        
        # Get previous build number and increment
        previous_build_number = google_play_track_version_codes(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            track: "internal",
            json_key_data: json_key_data,
        )[0]
        current_build_number = previous_build_number + 1
        sh("export NEW_BUILD_NUMBER=#{current_build_number}")
        
        # Build the app
        gradle(
          task: "clean bundleRelease",
          project_dir: 'android/',
          print_command: false,
          properties: {
            "android.injected.signing.store.file" => "#{keystore_path}",
            "android.injected.signing.store.password" => "#{KEYSTORE_STORE_PASSWORD}",
            "android.injected.signing.key.alias" => "#{KEYSTORE_KEY_ALIAS}",
            "android.injected.signing.key.password" => "#{KEYSTORE_KEY_PASSWORD}",
            'versionCode' => current_build_number
          })
        
        # Upload to Play Store
        upload_to_play_store(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            json_key_data: json_key_data,
            track: 'internal',
            release_status: 'completed',
            skip_upload_metadata: true,
            skip_upload_changelogs: true,
            skip_upload_images: true,
            skip_upload_screenshots: true,
        )
    end
end

4. Configura los Secrets de GitHub

Ahora que tienes tu keystore y el JSON de la cuenta de servicio, necesitas almacenarlos de forma segura en GitHub.

Paso 4.1: Accede a los Secrets de GitHub

1. Ve a tu repositorio en GitHub
2. Haz clic Configuración → Secrets y variables → Acciones
3. Haz clic Nuevo secreto de repositorio

Paso 4.2: Añadir los secretos necesarios

Añade cada uno de estos secretos uno a uno:

PLAY_CONFIG_JSON

1. Toma el archivo JSON de la cuenta de servicio que descargaste en el Paso 2.4
2. Conviértelo a base64:

En macOS/Linux:

base64 service_account_key.json | pbcopy

En Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard

3. Crea un nuevo secreto llamado PLAY_CONFIG_JSON y pega la cadena base64

ANDROID_KEYSTORE_FILE

1. Convierte tu keystore a base64:

En macOS/Linux:

base64 my-release-key.keystore | pbcopy

En Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("my-release-key.keystore")) | Set-Clipboard

2. Crea un nuevo secreto llamado ANDROID_KEYSTORE_FILE y pega la cadena base64

KEYSTORE_KEY_ALIAS

Crea un nuevo secret con el alias de la clave que usaste al generar el keystore (p. ej., my-key-alias)

KEYSTORE_KEY_PASSWORD

Crea un nuevo secret con la contraseña de la clave que configuraste al generar el keystore

KEYSTORE_STORE_PASSWORD

Crea un nuevo secret con la contraseña del keystore que configuraste al generar el keystore

NOMBRE_DEL_PAQUETE_DEL_DESARROLLADOR

Crea un nuevo secret con el package name de tu app (ej: com.example.app)

Puedes encontrar tu package name en android/app/build.gradle en applicationId

Paso 4.3: Verificar todos los secretos

Asegúrate de tener configurados estos 6 secrets:

• ✅ PLAY_CONFIG_JSON
• ✅ ANDROID_KEYSTORE_FILE
• ✅ KEYSTORE_KEY_ALIAS
• ✅ KEYSTORE_KEY_PASSWORD
• ✅ KEYSTORE_STORE_PASSWORD
• ✅ DEVELOPER_PACKAGE_NAME

5. Crear el workflow de GitHub Actions

Crear .github/workflows/build-upload-android.yml:

name: Build and Deploy Android App

on:
  push:
    tags:
      - '*'

jobs:
  build_android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          
      - name: Install dependencies
        run: npm ci
        
      - name: Cache Gradle
        uses: actions/cache@v5
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            ${{ runner.os }}-gradle-
            
      - name: Build app
        run: npm run build
        
      - name: Sync Capacitor
        run: npx cap sync
        
      - name: Setup Java
        uses: actions/setup-node@v5
        with:
            distribution: 'zulu'
            java-version: '17'
            
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.0'
          bundler-cache: true
          
      - name: Run Fastlane
        uses: maierj/fastlane-action@v3.1.0
        env:
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          DEVELOPER_PACKAGE_NAME: ${{ secrets.DEVELOPER_PACKAGE_NAME }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        with:
          lane: android beta
          
      - name: Upload artifact
        uses: actions/upload-artifact@v2
        with:
          name: android-release
          path: ./android/app/build/outputs/bundle/release/app-release.aab
          retention-days: 10

Cómo funciona

1. Crea una etiqueta Git para activar el workflow
2. GitHub Actions compila tu app
3. Fastlane lo sube al canal beta de Google Play
4. Tu app se actualiza automáticamente

Tiempo de build y costes

• Tiempo de build: 3-5 minutos
• Costo para repos privados: ~$0.04 por build
• Gratis para proyectos open-source

Artículos relacionados

Guías de configuración CI/CD

• Build automático de Capacitor iOS con GitHub Actions - Configuración completa de CI/CD para iOS
• Build y release automáticos con GitHub Actions - Tutorial de pipeline CI/CD completo
• Gestiona builds de Dev y Prod con GitHub Actions - Gestión de entornos

Plataformas CI/CD alternativas

• Build con GitLab CI - Alternativa a GitLab para Android
• Build con CodeMagic - Guía de configuración de CodeMagic

Live Updates y despliegue

• Documentación de Capgo Live Updates - Añade actualizaciones OTA a tu app
• Integración CI/CD con Capgo - Integra Live Updates en tu pipeline

Recursos

• Documentación de GitHub Actions
• Documentación de Fastlane

Continúa desde la compilación automática de Capacitor para Android con GitHub Actions

Si estás usando Build automático de Android de Capacitor con acciones de GitHub para planificar la automatización de CI/CD, conéctalo con CI/CD de Capgo para el flujo de trabajo del producto en Capgo CI/CD, Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds, Integraciones de Capgo para el flujo de trabajo del producto en Capgo Integraciones, Integración CI/CD para los detalles de implementación de CI/CD Integration, y Integración con GitHub Actions para los detalles de implementación de GitHub Actions Integration.