Automatic Capacitor Android build with GitHub actions

Configurando CI/CD para aplicaciones Capacitor puede ser complejo y tiempo consumidor. Aquí está lo que necesitas saber:

Recomendado para Nuevas Construcciones: Utilice Capgo Construcción

Ahora recomendamos utilizar Capgo Construcción con el Capgo CLI para construcciones nativas Capacitor. Esta guía de Fastlane se mantiene para equipos que mantienen pipelines de acciones existentes GitHub, pero nuevos builds de Android deben utilizar el Capgo CLI para que no tengas que mantener Fastlane, ejecutores de Gradle, archivos de keystore y scripts de carga.

Requisitos previos

Antes de empezar, necesitarás configurar:

• Una cuenta de GitHub con acceso administrativo
• Tu aplicación ya publicada en Google Play Store con firmado correctamente
• Clave de firma y archivos de keystore de Android
• Proyecto de Google Cloud Console con API de Play Store habilitado
• Servicio de cuenta con permisos adecuados
• Comprensión de los flujos de trabajo de GitHub
• Conocimiento de la configuración de Fastlane
• Tiempo para mantener y depurar la canalización

Capgo Build para CI/CD por Capgo

Saltarse la configuración de Fastlane, el ejecutor de Gradle, el keystore y el script de carga. Capgo Build Ejecuta compilaciones nativas firmadas de Android desde tu propia canalización de CI/CD:

• Funciona con tu canalización: Inicia Capgo Build desde GitHub Actions, GitLab CI, Jenkins o scripts locales después de tu compilación web y npx cap sync.
• Autenticación desde secretos de CI: Mantén los keystore de Android, alias de clave, contraseñas y servicio de cuenta de la consola de Play en tus propios secretos de CI.
• No mantenimiento del ejecutor nativo: Capgo Build proporciona entornos de compilación de Android mantenidos, por lo que no tiene que gestionar SDK imágenes, problemas de caché de Gradle o rutas de Fastlane.
• Artículos y presentación: Descargar artefactos firmados para QA o presentar versiones de lanzamiento a través de la Capgo CLI.

Precios

• Capgo planes comienzan en $12/mes
• Incluye actualizaciones OTA y aproximadamente 15 compilaciones nativas por mes
• Los minutos adicionales de compilación se facturan por minuto a través de créditos

Configurar Capgo Build en CI/CD

Guía de configuración manual

Aquí está lo que necesita hacer:

GitHub Acciones Precios

GitHub Acciones ofrece minutos gratuitos según el tipo de repositorio:

• Repositorios públicos: 2,000 minutos/mes
• Repositorios privados: 2,000 minutos/mes (ejecutores de Linux)

Para proyectos privados, los costos son aproximadamente $0.008/minuto. Un build típico dura 3-5 minutos.

Pasos de configuración manual

1. Crear Keystore de Android
2. Configurar cuenta de servicio de Google Play
3. Configurar Fastlane
4. Configurar secretos de GitHub
5. Crear flujo de trabajo de GitHub Acciones

1. Crear Keystore de Android

Antes de que puedas firmar y publicar tu aplicación Android, debes crear un archivo de keystore. Este es un proceso de configuración de una sola vez.

Generar 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á:

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

Notas importantes

• Almacena estos valores de manera segura:

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

• Realice una copia de seguridad del archivo de keystore: Si lo pierdes, no podrás actualizar tu aplicación publicada

• Guárdelo en secreto: Nunca comitas el archivo de keystore en git

• Almacénelo a salvo: Mantenga múltiples copias de seguridad en ubicaciones seguras

Opción alternativa: Utilice un Keystore existente

Si ya publicaste tu aplicación, debes utilizar el mismo keystore que utilizaste inicialmente. Puedes encontrarlo:

• En tu máquina local donde construiste la aplicación por primera vez
• En tu Consola de Play → Configuración → Firma de la aplicación (si estás utilizando la firma de la aplicación de Google Play)

2. Configura la cuenta de servicio de Google Play

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

Paso 2.1: Crea proyecto de Google Cloud

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

Paso 2.2: Habilita el desarrollador de Google Play API

1. En la Consola de Google Cloud, ve a Servicios & APIs → Biblioteca
2. Buscar por “Desarrollador de Android de Google Play API”
3. Hacer clic Habilitar

Paso 2.3: Crear cuenta de servicio

1. Ir a IAM & Administración → Cuentas de servicio
2. Hacer clic Crear cuenta de servicio
3. Introducir detalles:
   • Nombre: github-actions-uploader
   • Descripción: “Cuenta de servicio para GitHub Acciones para subir compilaciones”
4. Haga clic Crear y Continuar
5. Saltar la asignación de roles por ahora (haga clic Continuar, luego Listo)

Paso 2.4: Crear Clave de Cuenta de Servicio

1. Haga clic en la cuenta de servicio recién creada
2. Vaya a Claves pestaña
3. Haga clic Agregar clave → Crear nueva clave
4. Elige formato JSON formato
5. Haga clic Crear
6. Descargará un archivo JSON - guárdelo de manera segura, lo necesitarás más tarde

Paso 2.5: Otorgar Acceso en Play Console

1. Vaya a Consola de Play de Google
2. Vaya a Configuración → API acceso
3. Bajo Cuentas de servicio, haga clic Otorgar acceso para su cuenta de servicio
4. En el Permisos de la aplicación pestaña, agregar tu aplicación
5. En el Permisos de la cuenta pestaña, otorgar estos permisos:
   • Ver información de la aplicación y descargar informes en bloque (solo lectura)
   • Crear, editar y eliminar aplicaciones de borrador
   • Publicar aplicaciones en pistas de prueba
   • Publicar aplicaciones en producción, excluir y otras pistas
6. Haga clic Invitar a usuario
7. Haga 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

Crear un fastlane carpeta en la raíz de tu proyecto y agregar 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 GitHub Secrets

Ahora que tienes tu keystore y archivo JSON de servicio, necesitas almacenarlos de manera segura en GitHub.

Paso 4.1: Acceder a GitHub Secrets

1. Ir a tu repositorio en GitHub
2. Haga clic Configuración → Secretos y variables → Acciones
3. Haga clic Nuevo secreto de repositorio

Paso 4.2: Agregar secretos requeridos

Agregue cada uno de estos secretos uno por uno:

PLAY_CONFIG_JSON

1. Tome el archivo JSON de la cuenta de servicio que descargó en el paso 2.4
2. Convirtalo 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. Cree un nuevo secreto llamado PLAY_CONFIG_JSON y pegue la cadena base64

ANDROID_KEYSTORE_FILE

1. Convierta su 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. Cree un nuevo secreto llamado ANDROID_KEYSTORE_FILE y pegue la cadena base64

KEYSTORE_KEY_ALIAS

Cree un nuevo secreto con el alias de clave que utilizó cuando generó el keystore (por ejemplo, my-key-alias)

KEYSTORE_KEY_PASSWORD

Crea un nuevo secreto con la clave de contraseña que estableciste al generar el almacén de claves

__CAPGO_KEEP_0__

Crea un nuevo secreto con la contraseña del almacén de claves que estableciste al generar el almacén de claves

__CAPGO_KEEP_0__

Crea un nuevo secreto con el nombre de paquete de tu aplicación (por ejemplo, com.example.app)

Puedes encontrar tu nombre de paquete en android/app/build.gradle debajo applicationId

Paso 4.3: Verifica todos los secretos

Asegúrate de tener configurados estos 6 secretos:

• ✅ CONFIGURACIÓN DE JUEGO DE JSON
• ✅ ARCHIVO DE CLAVE DE ANDROID
• ✅ ALINEACIÓN DE CLAVE DEL ALMACÉN DE CLAVES
• ✅ CONTRASEÑA DE LA LLAVE DEL ALMACÉN
• ✅ CONTRASEÑA DEL ALMACÉN DE LA APLICACIÓN
• ✅ NOMBRE DEL PAQUETE DEL DESARROLLADOR

5. Crea GitHub flujo de trabajo de Acciones

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. Crear una etiqueta Git para desencadenar el flujo de trabajo
2. GitHub Acciones compila tu aplicación
3. Fastlane la sube a Google Play beta canal
4. Tu aplicación se actualiza automáticamente

Tiempo de Compilación y Costos

• Tiempo de compilación: 3-5 minutos
• Costo para repositorios privados: ~$0.04 por construcción
• Gratis para proyectos de código abierto

Artículos relacionados

Guías de configuración de CI/CD

• Construcción automática de iOS con Capacitor y GitHub Actions - Configuración completa de CI/CD de iOS
• Construcción y liberación automáticas con GitHub Actions - Tutorial completo de pipeline de CI/CD
• Gestión de construcciones de Dev y Prod con GitHub Actions - Gestión de entornos

Plataformas de CI/CD alternativas

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

Actualizaciones en vivo y despliegue

• Capgo Documentación de Actualizaciones en vivo - Agrega actualizaciones OTA a tu aplicación
• Integración CI/CD con Capgo - Integra actualizaciones en vivo en tu pipeline

Recursos

• GitHub Documentación de Acciones
• Documentación de Fastlane

Sigue adelante desde la construcción automática de Android de Capacitor con GitHub acciones

Si estás utilizando Automático Capacitor construcción de Android con GitHub acciones para planificar la automatización de CI/CD, conecta con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD, Capgo Construcciones nativas para el flujo de trabajo del producto en Capgo Construcciones nativas, Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones, Integración de CI/CD para el detalle de implementación en Integración de CI/CD, y GitHub Integración de acciones para los detalles de implementación en GitHub Acciones de Integración.