Costruzione di build Android automatica con Capacitor e GitHub

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

Consigliato per Nuove Costruzioni: Utilizza Capgo Build

Ora raccomandiamo di utilizzare Capgo Build con il Capgo CLI per le costruzioni native Capacitor. Questa guida Fastlane è 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, i runner di Gradle, le chiavi e i file del keystore, e i script di caricamento.

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
• La chiave di firma Android e i file del keystore
• Progetto di Google Cloud Console con API di Google Play Store abilitato
• Account di servizio con permessi adeguati
• Capacità di comprendere i flussi di lavoro di GitHub
• Conoscenza della configurazione di Fastlane
• Tempo per mantenere e debuggare il pipeline

Capgo Build per CI/CD da Capgo

Saltare la manutenzione di Fastlane, Gradle runner, keystore e upload-script. Capgo Build Esegue costruzioni native Android firmate direttamente dal tuo pipeline CI/CD esistente:

• Lavora con il tuo pipeline: Trasmetti Capgo Build da GitHub Actions, GitLab CI, Jenkins o script locali dopo la tua costruzione web e npx cap sync.
• La firma da segreti di CI: Mantieni le chiavi Android, gli alias delle chiavi, le password e il servizio account di Console Play in segreti CI propri.
• No manutenzione del runner nativo: Capgo Build fornisce ambienti di costruzione Android mantenuti, quindi non devi gestire SDK immagini, problemi di cache Gradle o Fastlane lanes.
• Articoli e sottoscrizione: Scarica gli artefatti firmati per la QA o invia release builds attraverso il Capgo CLI.

Prenotazione

• I piani Capgo iniziano a $12/mese
• Includono aggiornamenti OTA e circa 15 costruzioni native al mese
• I minuti di costruzione aggiuntivi sono fatturati per minuto attraverso crediti

Configura Capgo Build in CI/CD

Guida di configurazione manuale

Ecco cosa devi fare:

GitHub Actions Pricing

GitHub Azioni offre minuti gratuiti in base al tipo del tuo repository:

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

Per i progetti privati, i costi sono di circa $0,008/minuto. Un build tipico dura 3-5 minuti.

Passaggi 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 la tua app Android, devi creare un file 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:

• Password del keystore: Scegli una password forte (avrai bisogno di questa come KEYSTORE_STORE_PASSWORD)
• Password della 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 esempio, my-release-key.keystore)
  • Alias della chiave (ad esempio, my-key-alias) - avrai bisogno di questo come KEYSTORE_KEY_ALIAS
  • Password del keystore - avrai bisogno di questo come KEYSTORE_STORE_PASSWORD
  • Password della chiave - avrai bisogno di questo come KEYSTORE_KEY_PASSWORD

• Backup il file del keystore: Se lo perdi, non potrai aggiornare il tuo app pubblicato

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

• Conservalo al sicuro: Conserva più backup in luoghi sicuri

Alternativa: Utilizza Esistente Keystore

If hai già pubblicato il tuo app, devi utilizzare la stessa chiave di sicurezza che hai utilizzato inizialmente. Puoi trovarla:

• In macchina locale dove hai costruito l'app per la prima volta
• In Console di Gioco → Impostazioni → Firma dell'app (se utilizzando la firma dell'app di Gioco di Google)

2. Configura il Servizio di Gioco di Google

Per consentire agli GitHub Azioni di caricare le build su Gioco di Google, hai bisogno di un account di servizio.

Passo 2.1: Crea Progetto di Cloud di Google

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

Passo 2.2: Abilita il Fornitore di sviluppatore di Gioco di Google API

1. In Console di Cloud di Google, vai a Servizi API → Biblioteca
2. Cerca “Google Play Android Developer API”
3. Clicca Abilita

Passo 2.3: Crea account di servizio

1. Vai a IAM & Amministrazione → 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. Svuota l'assegnazione del ruolo per ora (clicca Continua, quindi Fatto)

Passo 2.4: Crea Chiave Account di Servizio

1. Clicca sul nuovo account di servizio creato
2. Vai a Chiavi tab
3. Clicca Aggiungi chiave → Crea una nuova chiave
4. Scegli formato JSON Clicca
5. Crea Un file JSON verrà scaricato -
6. salva questo in modo sicuro sarà necessario in seguitoyou’ll need it later

Passo 2.5: Concedi accesso in Console Play

1. Vai a Console di gioco di Google
2. Vai a Configurazione → API accesso
3. Sotto Conti utente, clicca Concedi accesso per il tuo account di servizio
4. Sul Autorizzazioni dell'app tabella, aggiungi il tuo app
5. Nella sezione Autorizzazioni dell'account tabella, concedi queste autorizzazioni:
   • 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
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 una fastlane cartella nella radice del tuo progetto e aggiungi un Fastfile con questo 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 GitHub

Ora che hai il tuo keystore e il file JSON del servizio, devi memorizzarli in modo sicuro in GitHub.

Passo 4.1: Accesso ai segreti GitHub

1. Vai al tuo repository su GitHub
2. Clicca Impostazioni → Segreti e variabili → Azioni
3. Clicca Nuovo segreto repository

Passaggio 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 Passaggio 2.4
2. Convertiscilo in base64:

Sul macOS/Linux:

base64 service_account_key.json | pbcopy

On Windows (PowerShell):

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

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

ANDROID_KEYSTORE_FILE

1. Converti il tuo keystore in base64:

On macOS/Linux:

base64 my-release-key.keystore | pbcopy

On 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

KEYSTORE_KEY_ALIAS

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

KEYSTORE_KEY_PASSWORD

Creare un nuovo segreto con la chiave password che hai impostato quando hai generato la chiave di archiviazione

KEYSTORE_STORE_PASSWORD

Creare un nuovo segreto con la password della chiave di archiviazione che hai impostato quando hai generato la chiave di archiviazione

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 in 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
• ✅ Password della chiave del keystore
• ✅ Password del keystore
• ✅ Nome del pacchetto dello sviluppatore

5. Crea GitHub Flusso di lavoro di Actions

Crea .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. Crea un tag Git per attivare il flusso di lavoro
2. GitHub Actions 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 build
• Gratuito per progetti open-source

Articoli correlati

Guida alla configurazione CI/CD

• Esecuzione automatica di build iOS con Capacitor e GitHub Actions - Configurazione completa di CI/CD per iOS
• Esecuzione automatica di build e rilascio con GitHub Actions - Tutorial completo di pipeline CI/CD
• Gestione di build Dev e Prod con GitHub Actions - Gestione degli ambienti

Alternative piattaforme CI/CD

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

Aggiornamenti in tempo reale e distribuzione

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

Risorse

• GitHub Documentazione delle azioni
• Documentazione di Fastlane

Prosegui dall'auto-costruzione di Capacitor Android con GitHub azioni

If you are using Automatic Capacitor Android build with GitHub actions per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e GitHub Integrazione azioni For i dettagli di implementazione in GitHub Azioni di integrazione.