Build Android automatica di Capacitor con GitHub Actions

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

Consigliato per le nuove build: usa Capgo Build

Ora consigliamo di usare Capgo Build con Capgo CLI per le build native Capacitor. Questa guida su Fastlane è pensata per i team che gestiscono pipeline GitHub Actions esistenti, ma per i nuovi build Android si consiglia di usare Capgo CLI per evitare di dover gestire manualmente Fastlane, i runner Gradle, i keystore e gli script di upload.

Prerequisiti

Prima di iniziare, dovrai configurare:

• Un account GitHub con permessi di admin
• La tua app già pubblicata su Google Play Store e correttamente firmata
• Chiavi di firma e file keystore per Android
• Un progetto Google Cloud Console con API per Play Store abilitato
• Un service account con i permessi corretti
• Una buona conoscenza dei workflow di GitHub Actions
• Conoscenza della configurazione di Fastlane
• Tempo per la manutenzione e il debug della pipeline

Capgo Build per CI/CD con Capgo

Dimentica la manutenzione di Fastlane, Gradle runner, keystore e script di upload. Build Capgo esegue build native Android firmate direttamente dalla tua pipeline CI/CD:

• Si integra con la tua pipeline: Avvia Capgo Build tramite GitHub Actions, GitLab CI, Jenkins o script locali dopo la web build e npx cap sync.
• Firma tramite segreti CI: Mantieni i keystore Android, alias, password e il JSON del service account di Play Console nei tuoi segreti CI.
• Nessuna gestione runner native: Capgo Build offre ambienti di build Android pronti all'uso, così non dovrai gestire immagini SDK, problemi di cache Gradle o lane di Fastlane.
• Artifacts and submission: Scarica gli artifact firmati per la QA o invia le release build tramite Capgo CLI.

Prezzi

• I piani Capgo partono da $12/mese
• Include aggiornamenti OTA e circa 15 Native Build al mese
• I minuti extra di build sono fatturati al minuto tramite crediti

Configura Capgo Build in CI/CD

Guida alla configurazione manuale

Ecco cosa devi fare:

Prezzi GitHub Actions

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

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

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

Passaggi di configurazione manuale

1. Crea il keystore Android
2. Configura l'account di servizio Google Play
3. Configura Fastlane
4. Configura i secret di GitHub
5. Crea il workflow GitHub Actions

1. Crea il keystore Android

Prima di firmare e pubblicare la tua app Android, devi creare un file keystore. È una configurazione da fare una sola volta.

Genera il keystore con keytool

Esegui questo comando nel terminale:

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

Ti verrà richiesto di inserire:

• Password del keystore: Scegli una password sicura (ti servirà come KEYSTORE_STORE_PASSWORD)
• Password della chiave: Scegli una password sicura (ti servirà come KEYSTORE_KEY_PASSWORD)
• Nome, organizzazione, ecc.: Inserisci i tuoi dati

Note importanti

• Salva questi valori in modo sicuro:

  • Percorso del file keystore (es. my-release-key.keystore)
  • Alias della chiave (es. my-key-alias) - ti servirà come KEYSTORE_KEY_ALIAS
  • Password del keystore - ti servirà come KEYSTORE_STORE_PASSWORD
  • Password della chiave - ti servirà per KEYSTORE_KEY_PASSWORD

• Fai il backup del file keystore: se la perdi, non potrai aggiornare l'app pubblicata

• Mantienila segreta: non fare mai il commit del file keystore su git

• Conservala in sicurezza: tieni più backup in luoghi sicuri

Alternativa: usa un keystore esistente

Se hai già pubblicato la tua app, devi usare lo stesso keystore usato inizialmente. Lo puoi trovare qui:

• Sulla tua macchina locale dove hai fatto la prima build dell'app
• Nella Play Console → Setup → App signing (se usi Google Play App Signing)

2. Configura il Google Play Service Account

Per consentire alle GitHub Actions di fare l'upload dei build su Google Play, è necessario un service account.

Passaggio 2.1: Crea un progetto Google Cloud

1. Vai su Google Cloud Console
2. Crea un nuovo progetto o seleziona uno esistente
3. Prendi nota dell'ID del progetto

Passaggio 2.2: Abilita l'API per Google Play Developer

1. Nella Google Cloud Console, vai su APIs & Services → Libreria
2. Cerca “Google Play Android Developer API”
3. Clicca su Abilita

Passaggio 2.3: Crea un Service Account

1. Vai su IAM e Amministrazione → Service Account
2. Clicca su Crea Service Account
3. Inserisci i dettagli:
   • Nome: github-actions-uploader
   • Descrizione: “Service account per GitHub Actions per l'upload dei build”
4. Clicca su Crea e continua
5. Salta l'assegnazione dei ruoli per ora (clicca Continua, poi Fatto)

Passaggio 2.4: Crea la chiave del Service Account

1. Clicca sul service account appena creato
2. Vai su Chiavi scheda
3. Clicca su Aggiungi chiave → Crea nuova chiave
4. Usa JSON formato
5. Clicca su Crea
6. Verrà scaricato un file JSON - salvalo in modo sicuro, ti servirà in seguito

Passaggio 2.5: Concedi l'accesso in Play Console

1. Vai su Google Play Console
2. Vai su Setup → Accesso a API
3. Sotto Service account, clicca Concedi l'accesso per il tuo service account
4. Nella scheda Permessi app aggiungi la tua app
5. Nella scheda Permessi account tab, concedi questi permessi:
   • Visualizza info app e scarica report in blocco (sola lettura)
   • Crea, modifica ed elimina app in bozza
   • Rilascia app sui canali di test
   • Rilascia app in produzione, esclusione e altri canali
6. Clicca su Invita utente
7. Clicca su Invia invito

Passaggio 2.6: Verifica la chiave JSON

Il file JSON scaricato dovrebbe apparire così:

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

Lo convertirai in base64 durante il setup dei secrets in GitHub.

3. Configura Fastlane

Crea un fastlane cartella nella root del 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 Secret di GitHub

Ora che hai il keystore e il JSON del service account, devi salvarli in modo sicuro su GitHub.

Passaggio 4.1: Accedi ai Secret di GitHub

1. Vai al tuo repository su GitHub
2. Clicca su Impostazioni → Secret e variabili → Azioni
3. Clicca su Nuovo secret del repository

Passaggio 4.2: Aggiungi i Secret necessari

Aggiungi ciascun secret uno alla volta:

PLAY_CONFIG_JSON

1. Prendi il file JSON del service account scaricato al 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 secret chiamato PLAY_CONFIG_JSON e 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 secret chiamato ANDROID_KEYSTORE_FILE e incolla la stringa base64

KEYSTORE_KEY_ALIAS

Crea un nuovo secret con l'alias della chiave che hai usato per generare il keystore (es. my-key-alias)

PASSWORD_CHIAVE_KEYSTORE

Crea un nuovo secret con la password della chiave impostata quando hai generato il keystore

KEYSTORE_STORE_PASSWORD

Crea un nuovo secret con la password del keystore impostata quando lo hai generato

NOME_DEL_PACCHETTO_SVILUPPATORE

Crea un nuovo secret con il package name della tua app (es. com.example.app)

Puoi trovare il tuo package name in android/app/build.gradle sotto applicationId

Passaggio 4.3: Verifica tutti i secret

Assicurati di aver configurato questi 6 secret:

• ✅ PLAY_CONFIG_JSON
• ✅ ANDROID_KEYSTORE_FILE
• ✅ KEYSTORE_KEY_ALIAS
• ✅ PASSWORD_KEYSTORE_KEY
• ✅ PASSWORD_DEL_KEYSTORE_STORE
• ✅ DEVELOPER_PACKAGE_NAME

5. Crea il workflow GitHub 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 avviare la workflow
2. GitHub Actions builda la tua app
3. Fastlane la carica sul canale beta di Google Play
4. La tua app viene aggiornata automaticamente

Tempi e costi di build

• Tempo di build: 3-5 minuti
• Costo per repo private: ~$0.04 per build
• Gratis per progetti open-source

Articoli correlati

Guide al setup CI/CD

• Build Capacitor iOS automatica con GitHub Actions - Setup CI/CD completo per iOS
• Build e Release automatiche con GitHub Actions - Tutorial completo sulla pipeline CI/CD
• Gestisci build Dev e Prod con GitHub Actions - Gestione degli environment

Alternative per la CI/CD

• Build con GitLab CI - Alternativa GitLab per Android
• Build con CodeMagic - Guida al setup di CodeMagic

Live Update & Deployment

• Documentazione Capgo Live Updates - Aggiungi aggiornamenti OTA alla tua app
• Integrazione CI/CD con Capgo - Integra i live updates nella tua pipeline

Risorse

• Documentazione GitHub Actions
• Documentazione Fastlane

Continua con il build Android automatico di Capacitor tramite GitHub actions

Se stai usando Build Android automatica di Capacitor con GitHub Actions per pianificare l'automazione CI/CD e connetterla a CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, Integrazione CI/CD per i dettagli implementativi in CI/CD Integration, e Integrazione GitHub Actions per i dettagli implementativi in GitHub Actions Integration.