Automatic Capacitor Android build with GitHub actions

Configurare l'Integrazione Continua/Continua Integrazione per gli app Capacitor può essere complesso e richiede molto tempo. Ecco cosa devi sapere:

Consigliato per Nuove Costruzioni: Utilizza Capgo Build

Consigliamo ora di utilizzare Capgo Build con il Capgo CLI per costruzioni native Capacitor. Questa guida Fastlane viene mantenuta per i team che mantengono pipeline di azioni GitHub esistenti, ma nuove costruzioni Android dovrebbero utilizzare il Capgo CLI in modo da non dover mantenere Fastlane, esegutore Gradle, file di chiave e script di caricamento da parte tua.

Requisiti

Prima di iniziare, avrai bisogno di configurare:

• Un account GitHub con accesso amministrativo
• La tua app già pubblicata su Google Play Store con firma corretta
• Chiave di firma Android e file di keystore
• Progetto di Google Cloud Console con API di 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 Costruisci per CI/CD da Capgo

Svuota la manutenzione di Fastlane, Gradle runner, keystore e upload-script. Capgo Costruisci Esegue costruzioni native Android firmate da __CAPGO_KEEP_0__ utilizzando la tua pipeline CI/CD esistente:

• Funziona con la tua pipeline: Attiva Capgo Costruisci 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 JSON del servizio account Play Console nei tuoi segreti CI.
• Nessuna manutenzione del runner nativo: Capgo Costruisci 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.

Prenotazioni

• I piani Capgo iniziano da 12€/mese
• Includono aggiornamenti OTA e circa 15 compilazioni native al mese
• I minuti di compilazione extra sono fatturati per minuto attraverso i crediti

Configura Capgo Build in CI/CD

Guida di configurazione manuale

Ecco cosa devi fare:

Prenotazioni GitHub Pricing

Il prezzo delle GitHub Actions offre minuti gratuiti in base al tipo di repository:

• Repository pubblici: 2.000 minuti/mese
• Repository privati: 2.000 minuti/mese (esecutori Linux)

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

Istruzioni di configurazione manuale

1. Creare Android Keystore
2. Configura account di servizio Google Play
3. Configura Fastlane
4. Configura GitHub segreti
5. Creare GitHub workflow di azioni

1. Creare Android Keystore

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

Eseguisci 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 di inserire:

• Parola di accesso alla chiave: Scegli una password forte (avrai bisogno di questa come KEYSTORE_STORE_PASSWORD)
• Parola di accesso alla chiave: Scegli una password forte (avrai bisogno di questa come KEYSTORE_KEY_PASSWORD)
• Il tuo nome, l'organizzazione, ecc.: Inserisci i tuoi dati

Nota importante

• Salva questi valori in modo sicuro:

  • Posizione del file della chiave (ad esempio, my-release-key.keystore)
  • Alias della chiave (ad esempio, my-key-alias) - avrai bisogno di questa come KEYSTORE_KEY_ALIAS
  • Parola di accesso alla chiave - avrai bisogno di questa come KEYSTORE_STORE_PASSWORD
  • Inserisci la password - ne avrai bisogno per KEYSTORE_KEY_PASSWORD

• Ricrea il file del keystore: Se lo perdi, non potrai aggiornare il tuo app pubblicata

• Tienilo segreto: Non commettere mai il file del keystore a git

• Mantienilo al sicuro: Conserva più copie 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:

• Sul tuo computer locale dove hai costruito l'app per la prima volta
• Nel tuo Console di Gioco → Impostazioni → Firmato dell'app (se utilizzando la firma dell'app di Google Play)

2. Configura il Servizio di Gioco di Google Account

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

Passo 2.1: Creare il progetto Google Cloud

1. Vai a Console di Google Cloud
2. Creare un nuovo progetto o selezionare uno esistente
3. Nota l'ID del progetto

Passo 2.2: Abilitare il API dello sviluppatore di Google Play

1. Nella Console di Google Cloud, vai a APIs & Servizi → Libreria
2. Cerca “Sviluppatore Android di Google Play API”
3. Clicca Abilita

Passo 2.3: Crea account di servizio

1. Vai a IAM & Admin → Account di servizio
2. Clicca Crea account di servizio
3. Inserisci dettagli:
   • Nome: github-actions-uploader
   • Descrizione: "Account di servizio per GitHub Azioni per caricare build"
4. Clicca Crea e continua
5. Saltare l'assegnazione del ruolo per ora (clicca Continua, poi Fatto)

Passaggio 2.4: Crea chiave di account di servizio

1. Clicca sul nuovo account di servizio creato
2. Vai a Chiavi scheda
3. Clicca Aggiungi chiave → Crea nuova chiave
4. Scegli formato JSON Clicca
5. Crea Un file JSON verrà scaricato -
6. salva questo in modo sicuro sarà necessario in seguitoStep 2.5: Concedi l'accesso in Console Play

Vai a

1. Console di Gioco Play Vai a
2. Console di Gioco Play Configurazione → API accesso
3. Sotto Conti utente, clicca Concedi accesso per il tuo account utente
4. Sul pannello Permessi dell'app aggiungi il tuo app
5. Sul pannello Permessi dell'account concedi questi permessi:
   • Visualizza informazioni sull'app e scarica rapporti in bulk (solo lettura)
   • Crea, modifica e elimina app bozza
   • Rilascia app in pista di testing
   • Rilascia app in produzione, escludi e altre piste
6. Clicca Invita utente
7. 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 account, hai bisogno di archiviarli in modo sicuro in GitHub.

Fase 4.1: Accesso ai segreti di GitHub

1. Accedi al tuo repository su GitHub
2. Clicca Impostazioni → Segreti e variabili → Azioni
3. Clicca Segreto di nuovo repository

Passo 4.2: Aggiungi i segreti richiesti

Aggiungi ogni segreto uno per uno:

PLAY_CONFIG_JSON

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

Su macOS/Linux:

base64 service_account_key.json | pbcopy

Su Windows (PowerShell):

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

3. Crea un nuovo segreto denominato PLAY_CONFIG_JSON incolla la stringa base64

ANDROID_KEYSTORE_FILE

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

2. Crea un nuovo segreto denominato ANDROID_KEYSTORE_FILE e incolla la stringa base64

ALIAS_CHIAVE_KEYSTORE

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

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

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

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

NOME_PACCHETTO_DEVELOPER

KEYSTORE_KEY_ALIAS

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

Potrai trovare il nome del pacchetto nella sezione android/app/build.gradle sotto applicationId

Fase 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

Come Funziona

1. Creare un tag Git per attivare il workflow
2. GitHub Azioni costruisce il tuo app
3. Fastlane lo carica sul canale beta di Google Play
4. La tua app viene aggiornata automaticamente

Tempo di Costruzione e Costi

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

Articoli correlati

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 flusso di lavoro CI/CD
• Gestione delle costruzioni di sviluppo e prodotto con GitHub Azioni - Gestione degli ambienti

Alternative piattaforme di CI/CD

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

Aggiornamenti in tempo reale & distribuzione

• Capgo Live Updates Documentation - Aggiungi aggiornamenti OTA all'app
• Integrazione CI/CD con Capgo - Integra gli aggiornamenti in tempo reale nel tuo pipeline

Risorse

• GitHub Azioni Documentazione
• Documentazione Fastlane

Continua con gli Azioni automatiche di Capacitor Android con GitHub azioni

Se stai utilizzando Azioni automatiche di Capacitor Android con GitHub azioni per pianificare l'automazione CI/CD, connettile con Capgo CI/CD per il workflow del prodotto in Capgo CI/CD, Capgo Costruzioni Native per il workflow del prodotto in Capgo Costruzioni Native, Capgo Integrazioni per il workflow del prodotto in Capgo Integrazioni, Integrazione CI/CD per il dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione delle azioni per il dettaglio di implementazione in GitHub Integrazione delle azioni.