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

Ora raccomandiamo di utilizzare Capgo Build con il Capgo CLI For costruzione nativa 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, eseguitori 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 di Play Store abilitato
• Account di servizio con autorizzazioni corrette
• Comprensione dei flussi di lavoro di azioni GitHub
• Conoscenza della configurazione di Fastlane
• Tempo per mantenere e debuggare la pipeline

Impostazione CI/CD Professionale da Capgo

Saltare la complessità. Capgo __CAPGO_KEEP_0__ configura la tua pipeline CI/CD direttamente nella tua piattaforma preferita:

• Indipendenza di Piattaforma: Funziona con GitHub Actions, GitLab CI o altri
• Integrazione Semplice: Non è necessario cambiare piattaforma, funziona con il tuo processo attuale
• Configurazione Personalizzata: Impostazione personalizzata che si adatta alle esigenze del tuo progetto
• Guida Esperta: Abbiamo già configurato CI/CD per +50 app

Prezzi

• Fattura di configurazione una tantum: $2,600
• I tuoi costi di esecuzione: ~$300/all'anno
• Confronta con Altra soluzione proprietaria: $6,000/all'anno
• Salva $26,100 in 5 anni

Configura CI/CD Ora

Guida di configurazione manuale

Se desideri ancora configurare tutto da solo, ecco cosa devi fare:

GitHub Azioni Prezzi

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

• Repository pubblici: 2,000 minuti/mese
• Repository private: 2.000 minuti/mese (esecutori Linux)

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

Passaggi di configurazione manuale

1. Crea chiave di sicurezza Android
2. Configura account servizio Google Play
3. Configura Fastlane
4. Configura segreti GitHub
5. Crea workflow GitHub Actions

1. Crea chiave di sicurezza Android

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

Genera chiave di sicurezza 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:

• 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)
• Il tuo nome, organizzazione, ecc.: Inserisci i tuoi dati

Nota importante

• 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 questa come KEYSTORE_KEY_ALIAS
  • La password del keystore - avrai bisogno di questa come KEYSTORE_STORE_PASSWORD
  • La password della chiave - avrai bisogno di questa come KEYSTORE_KEY_PASSWORD

• Esegui un backup del 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 modo 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:

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

2. Configura il Servizio Account di Google Play

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

Passo 2.1: Crea Progetto Google Cloud

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

Passo 2.2: Abilita il Servizio di Sviluppatore di Google Play API

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

Passo 2.3: Crea Conto Servizio

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

Passo 2.4: Crea Chiave Account Servizio

1. Clicca sul nuovo account servizio appena creato
2. Vai a Chiavi tab
3. Clicca Aggiungi Chiave → Crea una nuova chiave
4. Scegli formato JSON formato
5. Clicca Crea
6. Un file JSON verrà scaricato - Salva questo in modo sicurosarà necessario in futuro

Passo 2.5: Concedi accesso in Console di Gioco

1. Vai a Console di Gioco di Google
2. Vai a Configura → API accesso
3. Sotto Conti dei servizi, clicca Concedi accesso per il tuo account dei servizi
4. Sul Autorizzazioni dell'app tabella, aggiungi il tuo app
5. Sul Autorizzazioni account tab, concedi queste autorizzazioni:
   • Visualizza informazioni sull'app e scarica rapporti in bulk (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 passaggio di configurazione dei segreti GitHub.

3. Imposta Fastlane

Crea un 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. 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

FILE DEL KEYSORE DI ANDROID

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 DELLA CHIAVE DEL KEYSORE

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

PASSWORD DELLA CHIAVE DEL KEYSORE

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

PASSWORD DEL KEYSORE

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

Nome del pacchetto dello sviluppatore

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

Puoi trovare il nome del pacchetto in android/app/build.gradle sotto applicationId

Passo 4.3: Verifica Tutti i Segreti

Assicurati di avere configurati questi 6 segreti:

• ✅ Configurazione di gioco JSON
• ✅ File del keystore Android
• ✅ Alias della chiave del keystore
• ✅ Password della chiave del keystore
• ✅ Password del keystore
• ✅ Nome del pacchetto dello sviluppatore

5. Crea GitHub Flussi 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 carica il tuo app sul canale beta di Google Play
4. Il tuo app viene aggiornato 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 iOS automatica con Capacitor azioni e GitHub - Configurazione completa di CI/CD per iOS
• Costruzione e rilascio automatico con GitHub azioni - Tutorial completo del flusso di lavoro di CI/CD
• Gestione di costruzioni Dev e Prod 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 Documentazione Aggiornamenti in Tempo Reale - Aggiungi aggiornamenti OTA al tuo app
• Integrazione CI/CD con Capgo - Integra aggiornamenti in tempo reale nel tuo pipeline

Risorse

• GitHub Documentazione Azioni
• Documentazione Fastlane