Build automático de Capacitor para Android con GitHub actions

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 Build de Capgo con Capgo CLI para builds nativos de Capacitor. Esta guía de Fastlane es para equipos que mantienen pipelines de GitHub Actions existentes; sin embargo, para nuevos builds de Android se recomienda usar Capgo CLI para evitar gestionar manualmente Fastlane, runners de Gradle, keystores y scripts de upload.

Requisitos

Antes de empezar, necesitarás configurar:

• Una cuenta de GitHub con acceso de admin
• Tu app ya publicada en Google Play Store con la firma correcta
• Claves de firma y archivos keystore de Android
• Un proyecto de Google Cloud Console con API de Play Store habilitado
• Una service account con los permisos adecuados
• Conocimientos de workflows de GitHub Actions
• Conocimientos de configuración de Fastlane
• Tiempo para mantener y debuguear 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/minuto. Un build típico tarda entre 3 y 5 minutos.

Pasos de configuración manual

1. Crear el Android Keystore
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 solicitará:

• 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 (ej., my-release-key.keystore)
  • Alias de la clave (ej., my-key-alias) - la necesitarás como KEYSTORE_KEY_ALIAS
  • Contraseña del Keystore - la necesitarás como KEYSTORE_STORE_PASSWORD
  • Contraseña clave: la necesitarás para KEYSTORE_KEY_PASSWORD

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

• Mantén la privacidad: Nunca subas el archivo keystore a git

• Guárdalo de forma segura: Mantén varios backups en sitios seguros

Alternativa: Usar un Keystore existente

Si ya publicaste tu app, debes usar el mismo keystore que usaste inicialmente. Puedes encontrarlo aquí:

• En tu máquina local donde hiciste el primer build de la app
• En tu Play Console → Setup → App signing (si usas Google Play App Signing)

2. Configura la Google Play Service Account

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

Paso 2.1: Crear proyecto en Google Cloud

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

Paso 2.2: Habilitar 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 GitHub Actions para subir 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 la 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: Dar 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 la pestaña Permisos de la app de tu app, añádela
5. En la pestaña Permisos de la cuenta tab, otorga estos permisos:
   • Ver info de la app y descargar reportes masivos (solo lectura)
   • Crear, editar y eliminar borradores de apps
   • Lanzar apps a canales de prueba
   • Lanzar apps a 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": "..."
}

Lo convertirás a base64 en el paso de configuración de secretos de GitHub.

3. Configurar Fastlane

Crea una 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. Configurar los Secrets de GitHub

Ahora que tienes tu keystore y el JSON de la service account, debes guardarlos de forma segura en GitHub.

Paso 4.1: Acceder a los Secrets de GitHub

1. Ve a tu repositorio en GitHub
2. Haz clic Configuración → Secrets y variables → Actions
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 (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 generarlo

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 un tag de Git para activar el workflow
2. GitHub Actions compila tu app
3. Fastlane la 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

Sigue avanzando con el Capacitor Android build automático con GitHub actions

Si estás usando Capacitor Android build automático con GitHub actions 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.