Costruzione automatica di Capacitor per Android con GitHub azioni

Impostare il CI/CD per le app Capacitor può essere complesso e richiede molto tempo. Ecco cosa devi sapere:

Consigliato per Nuove Costruzioni: Utilizza la costruzione Capgo

Adesso consigliamo di utilizzare Capgo Costruzione con il Capgo CLI per costruzioni native Capacitor. Questa guida Fastlane è conservata per le squadre che mantengono pipeline di azioni GitHub esistenti, ma le nuove costruzioni Android dovrebbero utilizzare il Capgo CLI in modo da non dover mantenere Fastlane, esecutori Gradle, chiavi e script di caricamento da soli.

Requisiti

Prima di iniziare, avrai bisogno di configurare:

Un account GitHub con accesso amministrativo
L'app già pubblicata su Google Play Store con firma corretta
Chiave di firma Android e file keystore
Progetto di Google Cloud Console con API Play Store abilitato
Account di servizio con autorizzazioni corrette
Comprensione dei flussi di lavoro di GitHub Actions
Conoscenza della configurazione di Fastlane
Tempo per mantenere e debuggare la pipeline

Capgo Build per CI/CD da Capgo

Saltare la manutenzione di Fastlane, Gradle runner, keystore e upload-script. Capgo Build __CAPGO_KEEP_0__ Build esegue costruzioni native Android firmate a partire dal proprio flusso di lavoro CI/CD:

Funziona con il proprio flusso di lavoro: Attiva Capgo Build da GitHub Actions, GitLab CI, Jenkins o script locali dopo la costruzione web e npx cap sync.
Firma da segreti CI: Mantieni le chiavi Android, gli alias chiave, le password e il file JSON del servizio account Play Console nei propri segreti CI.
Nessuna manutenzione del runner nativo: Capgo Build fornisce ambienti di costruzione Android mantenuti, quindi non devi gestire SDK immagini, problemi di cache Gradle o lane Fastlane.
Articoli e sottoscrizione: Scarica gli articoli firmati per la QA o invia le costruzioni di rilascio attraverso il Capgo CLI.

Pianificazione dei prezzi

Capgo piani iniziano da 12 dollari al mese
Includono aggiornamenti OTA e circa 15 costruzioni native al mese
Minuti di costruzione aggiuntivi sono fatturati per minuto attraverso crediti

Configura Capgo Build in CI/CD

Guida di configurazione manuale

Ecco cosa devi fare:

Pianificazione dei prezzi GitHub

Prezzo dell'azione GitHub

Pianificazione delle azioni GitHub offre minuti gratuiti in base al tipo di repository:

Repository pubblici: 2.000 minuti al mese
Repository privati: 2.000 minuti al mese (esecutori Linux)

Per progetti privati, i costi sono di circa $0,008/minuto. Una costruzione tipica richiede 3-5 minuti.

Passaggi di configurazione manuale

Crea Keystore Android
Configura account di servizio Google Play
Configura Fastlane
Configura segreti GitHub
Crea workflow GitHub Actions

1. Crea Keystore Android

Prima di poter firmare e pubblicare il tuo app Android, devi creare un file di keystore. Questo è un setup una volta per tutte.

Genera Keystore con keytool

Esegui questo comando nel tuo terminale:

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

Ti verrà chiesto:

Parola di chiave del keystore: Scegli una password forte (avrai bisogno di questa come KEYSTORE_STORE_PASSWORD)
Parola di chiave: Scegli una password forte (avrai bisogno di questa come KEYSTORE_KEY_PASSWORD)
Nome, organizzazione, ecc.: Inserisci i tuoi dati

Note importanti

Salva questi valori in modo sicuro:
- Posizione del file del keystore (ad es. my-release-key.keystore)
- Alias della chiave (ad es. my-key-alias) - avrai bisogno di questa come KEYSTORE_KEY_ALIAS
- Parola di chiave del keystore - avrai bisogno di questa come KEYSTORE_STORE_PASSWORD
- La chiave di accesso - avrai bisogno di questo come KEYSTORE_KEY_PASSWORD
Backup il file del keystore: Se lo perdi, non potrai aggiornare il tuo app pubblicato
Tienilo segreto: Non commettere mai il file del keystore a git
Conservalo in un luogo sicuro: Conserva più backup in luoghi sicuri

Alternativa: Utilizza Esistente Keystore

Se hai già pubblicato il tuo app, devi utilizzare lo stesso keystore che hai utilizzato inizialmente. Puoi trovarlo:

In macchina locale dove hai costruito l'app per la prima volta
Nella tua console di Play → Impostazioni → App firmata (se utilizzi la firma di Google Play App Signing)

2. Configura il Servizio di Google Play Account

Per consentire agli GitHub Actions di caricare le build su Google Play, è necessario un account di servizio.

Passo 2.1: Creare un progetto di Google Cloud

Vai a Console di Google Cloud
Crea un nuovo progetto o seleziona uno esistente
Nota l'ID del progetto

Passo 2.2: Abilita il servizio di sviluppatore di Google Play API

In Console di Google Cloud, vai a APIs & Servizi → Biblioteca
Cerca “Sviluppatore Android di Google Play API”
Clicca Abilita

Passo 2.3: Crea account di servizio

Vai a IAM & Amministrazione → Account di servizio
Clicca Crea account di servizio
Inserisci dettagli:
- Nome: github-actions-uploader
- Descrizione: "Account di servizio per le GitHub azioni per l'upload dei build"
Clicca Crea e continua
Saltare l'assegnazione del ruolo per ora (clicca Continua, poi Fatto)

Passo 2.4: Crea chiave di account di servizio

Clicca sul nuovo account di servizio creato
Vai a Chiavi tab
Clicca Aggiungi chiave → Crea nuova chiave
Scegli formato JSON formato
Clicca Crea
Un file JSON verrà scaricato - salva questo in modo sicuropotrai averne bisogno in seguito

Passo 2.5: Concedi accesso in Console Play

Vai a Console di Gioco Play
Vai a Configurazione → API access
Sotto Conti utente, clicca Concedi l'accesso per il tuo account utente
Sul Permessi dell'app aggiungi il tuo app
Sul Permessi dell'account tab, concedi questi permessi:
- Visualizza informazioni sull'app e scarica rapporti in blocco (lettura solo)
- Crea, modifica e elimina app bozzetto
- Pubblica app in piste di testing
- Pubblica app in produzione, escludi e altre piste
Clicca Invita utente
Clicca Invia invito

Passo 2.6: Verifica la chiave JSON

Il file JSON scaricato dovrebbe avere questo aspetto:

{
  "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": "..."
}

Convertirai questo in base64 nel passo di configurazione dei segreti GitHub.

3. Imposta Fastlane

Crea un fastlane cartella nella radice del tuo progetto e aggiungi un Fastfile con il seguente contenuto:

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 i segreti di GitHub

Ora che hai il tuo keystore e il file JSON del servizio, hai bisogno di archiviarli in modo sicuro in GitHub.

Fase 4.1: Accesso ai segreti di GitHub

Accedi al tuo repository su GitHub
Clicca Impostazioni → Segreti e variabili → Azioni
Clicca Nuova chiave segreta del repository

Passo 4.2: Aggiungi i segreti richiesti

Aggiungi ogni segreto uno per uno:

PLAY_CONFIG_JSON

Prendi il file JSON del servizio account che hai scaricato nel Passo 2.4
Convertilo in base64:

Sul macOS/Linux:

base64 service_account_key.json | pbcopy

Sul Windows (PowerShell):

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

Crea una nuova chiave segreta denominata PLAY_CONFIG_JSON e incolla la stringa base64

ANDROID_KEYSTORE_FILE

Converti il tuo keystore in base64:

Su macOS/Linux:

base64 my-release-key.keystore | pbcopy

Su Windows (PowerShell):

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

Crea un nuovo segreto denominato ANDROID_KEYSTORE_FILE e incolla la stringa base64

KEYSTORE_KEY_ALIAS

Crea un nuovo segreto con la chiave alias che hai utilizzato quando hai generato il keystore (ad esempio, my-key-alias)

KEYSTORE_KEY_PASSWORD

Crea un nuovo segreto con la password della chiave che hai impostato quando hai generato il keystore

KEYSTORE_STORE_PASSWORD

Crea un nuovo segreto con la password del keystore che hai impostato quando hai generato il keystore

DEVELOPER_PACKAGE_NAME

Creare un nuovo segreto con il nome del pacchetto della tua app (ad esempio, com.example.app)

Potrai trovare il nome del pacchetto della tua app android/app/build.gradle sotto applicationId

Passo 4.3: Verifica tutti i segreti

Assicurati di avere configurati questi 6 segreti:

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

5. Crea GitHub Workflow di azioni

Creazione .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

Cosa Funziona

Crea un tag Git per attivare il flusso di lavoro
GitHub Azioni costruisce il tuo app
Fastlane lo carica sul canale beta di Google Play
La tua app viene aggiornata automaticamente

Tempo e Costi di Costruzione

Tempo di costruzione: 3-5 minuti
Costo per repository privati: ~$0.04 per costruzione
Gratis per progetti open-source

Guida di configurazione CI/CD

Costruzione automatica Capacitor di iOS con GitHub azioni - Configurazione completa di CI/CD per iOS
Costruzione automatica e rilascio con GitHub azioni - Tutorial completo del pipeline CI/CD
Gestione delle costruzioni di sviluppo e prodotto con GitHub azioni - Gestione degli ambienti

Alternative piattaforme di CI/CD

Costruzione con GitLab CI - Alternativa di GitLab per Android
Costruzione con CodeMagic - Guida di configurazione di CodeMagic

Aggiornamenti in tempo reale & distribuzione

Capgo Aggiornamenti in Tempo Reale Documentazione - Aggiungi aggiornamenti OTA al tuo app
Integrazione CI/CD con Capgo - Integra gli aggiornamenti in tempo reale nel tuo pipeline

Risorse

Continua dall'aggiornamento Android automatico con Capacitor e dalle azioni di GitHub

Se stai utilizzando L'aggiornamento Android automatico con Capacitor e dalle azioni di GitHub per pianificare l'automazione CI/CD, connettilo con la CI/CD di Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Costruzioni native per il workflow del prodotto in Capgo Costruzioni native, Capgo Integrazioni for the product workflow in Capgo Integrations, per il workflow del prodotto in __CAPGO_KEEP_0__ Integrazioni, Integrazione CI/CD GitHub Actions Integration for the implementation detail in GitHub Actions Integration.

Automatic Capacitor Android build with GitHub actions