Automatic Capacitor Android build with GitHub actions

Setting up CI/CD for Capacitor apps can be complex and time-consuming. Here’s what you need to know:

Recommended for New Builds: Use Capgo Build

Ahora recomendamos utilizar Capgo Build with the Capgo CLI para compilaciones nativas Capacitor. Esta guía de Fastlane se mantiene para equipos que mantienen pipelines de acciones GitHub existentes, pero los nuevos compilados de Android deben utilizar el Capgo CLI para que no deban mantener Fastlane, ejecutores de Gradle, archivos de keystore y scripts de carga por sí mismos.

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 firmas adecuadas
• Clave de firma y archivos de keystore de Android
• Proyecto de Google Cloud Console con API de Play Store habilitado
• Cuenta de servicio con permisos adecuados
• Entendimiento de los flujos de trabajo de GitHub Actions
• Conocimiento de la configuración de Fastlane
• Tiempo para mantener y depurar la pipeline

Capgo Construye para CI/CD por Capgo

No necesitas mantener Fastlane, Gradle runner, keystore y script de carga. Capgo Construye ejecuta compilaciones nativas Android firmadas a partir de tu pipeline de CI/CD existente:

• Funciona con tu pipeline: Dispara Capgo Construye 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 Android, alias de clave, contraseñas y servicio de cuenta de Play Console en tus propios secretos de CI.
• No mantenimiento de ejecutor nativo: Capgo Construye proporciona entornos de compilación Android mantenidos, por lo que no tienes que administrar SDK imágenes, problemas de caché de Gradle o rutas de Fastlane.
• Artículos y envío: Descarga artículos firmados para QA o envía compilaciones de lanzamiento a través de la Capgo CLI.

Tarifas

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

Configura Capgo Build en CI/CD

Guía de configuración manual

Aquí está lo que debes hacer:

GitHub Acciones de Precios

GitHub Acciones ofrece minutos gratuitos basados en el tipo de repositorio de tu cuenta:

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

Para proyectos privados, los costos son aproximadamente $0.008/minuto. Un build típico toma 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 Actions

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 setup 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

Te pedirán:

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

Notas importantes

• Almacena estos valores de manera segura:

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

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

• Mantén el secreto: Nunca comitas el archivo del keystore a git

• Almacénalo a salvo: Mantén múltiples copias de seguridad en ubicaciones seguras

Alternativa: Utiliza 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 → Firmado de aplicaciones (si estás utilizando la firma de aplicaciones de Google Play)

2. Configura la cuenta de servicio de Google Play

To permit GitHub Actions to upload builds to Google Play, you need a service account.

Paso 2.1: Crear proyecto de Google Cloud

1. Vaya a Consola de Google Cloud
2. Crear un nuevo proyecto o seleccionar uno existente
3. Tenga en cuenta el ID del proyecto

Paso 2.2: Habilitar el desarrollador de Android de Google Play API

1. En la Consola de Google Cloud, vaya a APIs & Services → Biblioteca
2. Busque “Desarrollador de Android de Google Play API”
3. Haga clic Habilitar

Paso 2.3: Crear cuenta de servicio

1. Vaya a IAM & Administración → Cuentas de servicio
2. Haga clic Crear cuenta de servicio
3. Introduzca 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 rol por ahora (haga clic Siga adelante, luego Listo)

Paso 2.4: Cree la clave de la 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 → Cree una nueva clave
4. Elija formato JSON formato
5. Haga clic Crear
6. Se descargará un archivo JSON - guárdelo de manera seguralo necesitarás más tarde

Paso 2.5: Otorgar acceso en la consola de Play

1. Vaya a Consola de Google Play
2. Vaya a Configuración → API acceso
3. Bajo Contas de servicio, haz clic Otorga acceso para tu cuenta de servicio
4. En la Permisos de la aplicación página, agrega tu aplicación
5. En la Permisos de la cuenta pulsa, concede 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. Pulsa Invitar a usuario
7. Pulsa Enviar invitación

Paso 2.6: Verificar la clave JSON

El archivo JSON descargado debería parecerse a esto:

{
  "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 GitHub.

3. Configura Fastlane

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

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

Paso 4.1: Acceder a GitHub Secrets

1. Ve a tu repositorio en GitHub
2. Haz clic en Ajustes → Secretos y variables → Acciones
3. Haz clic Nuevo secreto de repositorio

Paso 4.2: Agregar secretos requeridos

Agrega cada uno de estos secretos por separado:

PLAY_CONFIG_JSON

1. Obtén 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. Crear un nuevo secreto llamado PLAY_CONFIG_JSON y pega 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 con el nombre ANDROID_KEYSTORE_FILE y pegue la cadena base64

ALIAS_DE_LA_CLAVE_DEL_ALMACÉN

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

CONTRASEÑA_DE_LA_CLAVE_DEL_ALMACÉN

Cree un nuevo secreto con la contraseña de la clave que configuró cuando generó el almacén

CONTRASEÑA_DEL_ALMACÉN

Cree un nuevo secreto con la contraseña del almacén que configuró cuando generó el almacén

NOMBRE_DEL_PAQUETE_DEL_DESARROLLADOR

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

Puedes encontrar el nombre de paquete en android/app/build.gradle bajo applicationId

Paso 4.3: Verificar todos los secretos

Asegúrate de tener configurados estos 6 secretos:

• ✅ PLAY_CONFIG_JSON
• ✅ ANDROID_KEYSTORE_FILE
• ✅ KEYSTORE_KEY_ALIAS
• ✅ KEYSTORE_KEY_PASSWORD
• ✅ KEYSTORE_STORE_PASSWORD
• ✅ NOMBRE_DE_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 un etiqueta Git para desencadenar el flujo de trabajo
2. GitHub Acciones compila tu aplicación
3. Fastlane la sube a Google Play beta
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 compilación
• Gratis para proyectos de código abierto

Artículos relacionados

Guías de configuración CI/CD

• Automatic Capacitor iOS Build con GitHub Acciones - Configuración completa de CI/CD para iOS
• Automatic Build y Lanzamiento con GitHub Acciones - Tutorial completo de pipeline de CI/CD
• Gestione Builds de Desarrollo y Producción con GitHub Acciones - Gestión de entornos

Plataformas de CI/CD Alternativas

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

Actualizaciones en vivo y despliegue

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

Recursos

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

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

Si estás utilizando La construcción automática de Android de Capacitor con acciones de GitHub 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 Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas, Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones, Integración CI/CD para el detalle de implementación en Integración CI/CD, y GitHub Integración de Acciones para el detalle de implementación en GitHub Integración de Acciones.