Costruzione automatica di Capacitor per Android con azioni di GitHub

La configurazione della CI/CD per le applicazioni Capacitor può essere complessa e richiede molto tempo. Ecco cosa devi sapere:

Consigliato per Nuove Costruzioni: Utilizza Capgo Costruzione

Ora raccomandiamo di utilizzare Capgo Costruzione 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, eseguitori Gradle, chiavi di archiviazione e script di caricamento da parte tua.

Prerequisiti

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
Chiavi di firma Android e file keystore
Progetto Google Cloud Console con Play Store API abilitato
Account di servizio con autorizzazioni adeguate
Comprensione dei flussi di lavoro di GitHub Actions
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:

Funziona con il tuo pipeline: Trascina Capgo Build da GitHub Actions, GitLab CI, Jenkins o script locali dopo la tua costruzione web e npx cap sync.
Autenticazione da segreti CI: Mantieni le chiavi Android, gli alias chiave, le password e il file JSON del servizio account Play Console nei tuoi segreti CI.
: Nessun mantenimento del runner nativo: Capgo Build fornisce ambienti di costruzione Android mantenuti, quindi non devi gestire SDK immagini, problemi di cache Gradle o percorsi Fastlane.
Articoli e sottoscrizione: Scarica gli articoli firmati per la QA o sottoscrivi i rilasci tramite il Capgo CLI.

Prenotazione

Capgo plans start at $12/month
__CAPGO_KEEP_0__ piani iniziano da 12€/mese
: Includono aggiornamenti OTA e circa 15 costruzioni native al mese

Set up Capgo Build in CI/CD

context":"Pagina/area: Capgo Builder / prodotto di costruzione nativa cloud. Ruolo: Frase di copertina del sito web. Visto in: pagina native-build.astro. Messaggio chiave `native_build_builder_minuti_di_costruzione` (Minuti di costruzione del costruttore di costruzione nativa)."

Ecco cosa devi fare:

GitHub Azioni Tariffe

Prezzo azione GitHub

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 dollari/minute. Una costruzione tipica richiede 3-5 minuti.

Passaggi di configurazione manuale

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

1. Creare Keystore Android

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

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:

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
Ricrea 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
Allocca lo in modo sicuro: Mantieni più copie di backup in luoghi sicuri

Alternativa: Utilizza Keystore Esistente

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 → Firma app (se utilizzi la firma app di Google Play)

2. Configura il Servizio di Google Play

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

Passo 2.1: Crea 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 lo sviluppatore Google Play API

In Google Cloud Console, vai a Servizi e API → Libreria
Cerca "Sviluppatore Android Google Play API"
Clicca Abilita

Passo 2.3: Crea account di servizio

Vai a IAM & Admin → Account di servizio
Clicca Creare account di servizio
Inserisci i dettagli:
- Nome: github-actions-uploader
- Descrizione: “Account di servizio per GitHub azioni per l'upload dei build”
Clicca Creare e Continua
Saltare l'assegnazione del ruolo per ora (clicca Continua, quindi Fatto)

Passo 2.4: Creare chiave di account di servizio

Clicca sull'account di servizio appena creato
Vai a Cerca le tabella
Clicca Aggiungi chiave → Crea una nuova chiave
Scegli formato JSON Clicca
Crea Scaricherai un file in formato JSON -
Scaricherai un file JSON - salva questo in modo sicuroavrai bisogno di questo più tardi

Passo 2.5: Concedi accesso in Console Play

Vai a Console Play Google
Vai a Configurazione → API access
__CAPGO_KEEP_0__ accesso SottoConti del servizio , clicca su per il tuo account di servizio
Nella sezione I permessi dell'app aggiungi la tua app
Nella sezione I permessi dell'account concedi questi permessi:
- Visualizzare informazioni sull'app e scaricare rapporti in blocco (solo lettura)
- Crea, modifica e elimina app di bozza
- Pubblica app nei percorsi di testing
- Pubblica app nei percorsi di produzione, escludi e altri percorsi
Clicca Invita l'utente
Clicca Invia l'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. Configura Fastlane

Crea una 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 GitHub

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

Passo 4.1: Accedi ai GitHub Segreti protetti

Vai al tuo repository su GitHub
Clicca Impostazioni → Segreti e variabili → azioni
Clicca Nuovo segreto repository

Passo 4.2: Aggiungi i segreti richiesti

Aggiungi ogni segreto uno per uno:

PLAY_CONFIG_JSON

Carica il file JSON del servizio account che hai scaricato nel Passo 2.4
Converti 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

Crea un nuovo segreto denominato PLAY_CONFIG_JSON e incolla la stringa in 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 in base64

KEYSTORE_KEY_ALIAS

Creare un nuovo segreto con la chiave alias utilizzata quando si è generato il keystore (ad esempio, my-key-alias)

KEYSTORE_KEY_PASSWORD

Creare un nuovo segreto con la chiave password impostata quando si è generato il keystore

KEYSTORE_STORE_PASSWORD

Creare un nuovo segreto con la password del keystore impostata quando si è 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 nella sezione android/app/build.gradle Step 4.3: Verifica Tutti i Segreti applicationId

Assicurati di avere configurati questi 6 segreti:

✅ PLAY_CONFIG_JSON

Step 4.3: Verifica Tutti i Segreti
✅ FILE DEL KEYS DI ANDROID
✅ ALIAS DELLA CHIAVE DEL KEYS
✅ PASSWORD DELLA CHIAVE DEL KEYS
✅ PASSWORD DELLO STORE DEL KEYS
✅ NOME DELLA DIRETTA DELLO SVILUPPATORE

5. Crea GitHub Workflow di azioni

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

Creare un tag Git per attivare il workflow
GitHub Azioni costruisce il tuo app
Fastlane lo carica sul canale beta di Google Play
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

Guida alla configurazione CI/CD

Build automatico Capacitor per iOS con GitHub Actions - Configurazione completa di CI/CD per iOS
Build automatico e rilascio con GitHub Actions - Tutorial completo della pipeline CI/CD
Gestione dei build Dev e Prod con GitHub Actions - Gestione degli ambienti

Piattaforme CI/CD alternative

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

Aggiornamenti in tempo reale & distribuzione

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

Risorse

Keep going from Automatic Capacitor Android build with GitHub actions

Se stai utilizzando Automatic Capacitor Android build with GitHub actions per pianificare l'automazione CI/CD, connettilo con Capgo automazione CI/CD per il flusso di lavoro del prodotto in Capgo automazione 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 nella integrazione CI/CD, e GitHub Integrazione delle azioni per i dettagli di implementazione nella GitHub Integrazione delle azioni.

Automatic Capacitor Android build with GitHub actions