Come firmare e costruire un'app Capacitor nel cloud

Per firmare e costruire un Capacitor app nel cloud, crei i materiali di firma una volta (un keystore Android, un certificato di distribuzione iOS e un profilo di provisioning), li dai a un servizio di costruzione cloud e poi attivi le costruzioni dal tuo terminale o dal CI. Il servizio compila il progetto nativo, lo firma e può caricarlo direttamente su TestFlight o Google Play. Questa guida copre ogni file di firma, come crearli senza un Mac, come configurarli con Capgo Build e come automatizzare le costruzioni firmate in modo sicuro.

Cosa significa 'firmare nel cloud'

Entrambe le store accettano solo binari firmati. La firma dimostra che il costruito proviene da te e che nessuno l'ha modificato dopo. Localmente, Xcode e Android Studio nascondono la maggior parte di questo. Nel cloud, nulla è implicito, quindi devi sapere esattamente quali file sono coinvolti:

Mantieni questi fuori da Git. Tutto il resto li archivia nel tuo file di credenziali locale o nel tuo archivio segreto di CI.

Autenticazione Android

Creare il keystore di upload

If l'applicazione è già presente su Google Play, riutilizza il keystore esistente. La firma di un aggiornamento con una chiave diversa è rifiutata a meno che non si passi attraverso il reset della chiave di caricamento del Console di Gioco.

Per una nuova applicazione:

keytool -genkeypair -v \
  -storetype PKCS12 \
  -keystore release.jks \
  -alias upload \
  -keyalg RSA -keysize 2048 \
  -validity 10000

Note:

• Google Play richiede che la chiave sia valida fino almeno al 22 ottobre 2033. -validity 10000 (circa 27 anni) copre questo.
• Con il tipo di archiviazione PKCS12, la password della chiave è la stessa della password dell'archiviazione.
• Non hai a disposizione un JDK? Il generatore di keystore Android produce lo stesso file nel browser.

Play App Signing e l'upload key

Le nuove applicazioni su Google Play utilizzano Play App Signing. Google detiene la chiave di firma dell'applicazione e riassegna ciò che gli utenti scaricano. Il tuo keystore è il carica la chiave. Se lo perdi, il supporto di Play Console può registrare una nuova chiave di caricamento, il che è il motivo per cui perderlo è un ritardo, non un disastro. Fai comunque una copia di backup.

Servizio di account per caricamenti

Per caricare dalla cloud, crea un servizio di account in Google Cloud, abilita il Google Play Android Developer API, scarica la sua chiave JSON e invita il servizio di account in Play Console sotto Utenti e autorizzazioni con le autorizzazioni di rilascio per la tua app. L'onboarding di Capgo può farlo tramite l'accesso Google, come mostrato di seguito.

firmatura iOS

I tre pezzi di Apple

• Certificato di distribuzione Apple. Uno per team è sufficiente, valido per un anno. Apple limita il numero di quelli che puoi avere, quindi non crearne uno per sviluppatore.
• Profilo di provisioning. Collega l'ID del bundle, il certificato e le funzionalità come le notifiche push. Utilizza un App Store Connect profilo per TestFlight e l'App Store, e un Ad Hoc profilo per installazioni su dispositivi registrati. Ogni estensione dell'app (widget, estensione di condivisione, servizio di notifica) ha bisogno del proprio profilo.
• App Store Connect API chiave. Creato sotto Utenti e accesso > Integrazioni con accesso all'App Manager. Il .p8 file scarica solo una volta.

È necessario avere diritti di amministratore o titolare dell'account nel team di sviluppatore Apple per creare questi.

Creare un certificato senza un Mac

The Keychain Access flow richiede macOS, ma OpenSSL funziona in ogni dove:

# 1. Private key and certificate signing request
openssl req -new -newkey rsa:2048 -nodes \
  -keyout dist.key -out dist.csr \
  -subj "/emailAddress=dev@example.com/CN=Example Inc/C=US"

# 2. Upload dist.csr at developer.apple.com > Certificates > + > Apple Distribution
#    and download distribution.cer

# 3. Convert and bundle into a .p12
openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -legacy \
  -inkey dist.key -in distribution.pem \
  -out distribution.p12 -passout pass:choose-a-password

The -legacy flag matters con OpenSSL 3: senza di esso, le macchine di costruzione macOS possono fallire nell'importare il .p12 con "verifica MAC fallita". Il browser-based Generatore di certificato iOS Poi crea il profilo di provisioning nel portale dei sviluppatori (

Crea quindi il profilo di provisioning nel portale dei sviluppatori ("Profili > + > App Store Connectseleziona il tuo ID app e il nuovo certificato, e scaricalo.

Imposta la firma con Capgo Costruisci

Capgo Build compiles and signs Capacitor apps on Capgo-managed machines, so you can build iOS from Windows or Linux. Start by logging in and registering the app:

bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add

Opzione A: onboarding guidato (consigliato)

bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build init --platform android

Su iOS, l'onboarding crea o riutilizza il certificato di distribuzione e il profilo di provisioning per l'App Store con la tua chiave API di App Store Connect. Su macOS può anche guidarti nella creazione di quella chiave API. Su Android, crea o importa il keystore e può provvedere all'invio del servizio account Google Cloud e all'invito al Console di gioco attraverso l'accesso Google. Alla fine offre di avviare la prima compilazione.

Opzione B: salvare file esistenti

Se già hai i file dalle sezioni precedenti:

# iOS
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./distribution.p12 \
  --p12-password "choose-a-password" \
  --ios-provisioning-profile ./AppStore.mobileprovision \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id 00000000-0000-0000-0000-000000000000 \
  --apple-team-id TEAM123456

# Android
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.jks \
  --keystore-alias upload \
  --keystore-key-password "store-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

Per le app con estensioni, ripeti --ios-provisioning-profile con un bundleId=path mapping per ogni target:

  --ios-provisioning-profile com.example.app=./App.mobileprovision \
  --ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision

Le credenziali sono memorizzate in ~/.capgo-credentials/credentials.json, chiavi da app ID e piattaforma. Aggiungi --local per memorizzarle nel .capgo-credentials.json al posto, e aggiungi quel file a .gitignoreControlla cosa viene salvato con bunx @capgo/cli@latest build credentials list.

Esegui una compilazione firmata

Prepara il progetto nativo, poi richiedi la compilazione:

bun run build
bunx cap sync

# iOS: sign with the App Store profile and upload to TestFlight
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

# Android: sign the AAB and upload to the internal track
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release --android-track internal

Il flusso dei log si riversa nel tuo terminale. Una scansione pre-compilazione controlla la scadenza del certificato, le password e la coppia di profili prima di caricare qualsiasi cosa, quindi la maggior parte degli errori di firma fallisce in secondi invece di minuti. Eseguiolo da solo con bunx @capgo/cli@latest build prescan --platform ios.

Variazioni utili:

Esegui una compilazione ad hoc, raccogli prima gli UDID dei dispositivi con il Finder di UDID per iOS e aggiungili al profilo.

Sviluppa costruisci ed esegui build firmati in CI

In CI, pass le credenziali come variabili di ambiente anziché un file di credenziali. Il CLI esporta esattamente ciò di cui hai bisogno:

bunx @capgo/cli@latest build credentials manage --appId com.example.app
# choose "Export to .env"

Sulla GitHub, invia ogni riga ai segreti del repository con un comando, poi cancella il file:

gh secret set -f .env.capgo.com.example.app
gh secret set CAPGO_TOKEN --body "your-capgo-api-key"
rm .env.capgo.com.example.app

Flusso di rilascio che firma e invia sia le piattaforme su un tag:

name: Signed release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}
      - run: bunx @capgo/cli@latest build request com.example.app --platform ${{ matrix.platform }} --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

La job esegue su Linux. Nessun runner di macOS, nessun comando di keychain, nessun fastlane. Le stesse variabili di ambiente funzionano in qualsiasi CI: variabili di GitLab CI/CD, variabili di Bitbucket sicure, segreti di Gitea, o gruppi di variabili di Azure DevOps. Guida passo passo per le piattaforme: Flussi di Bitbucket Pipelines, azioni di Gitea, e le documentazioni delle azioni di GitHub.

Come vengono gestiti le tue chiavi

A domanda giusta prima di consegnare le chiavi di firma a qualsiasi servizio cloud. Con Capgo Build:

• Le credenziali sono presenti sul tuo computer (~/.capgo-credentials/) o nel tuo archivio segreto CI. Capgo non mantiene una cassetta di sicurezza delle tue chiavi.
• Per ogni build, CLI le invia tramite HTTPS. Vengono utilizzate solo durante quel build e vengono eliminate quando è completato.
• Solo il progetto nativo preparato viene caricato. La tua sorgente web, .git, e .env i file non lo sono.
• Gli app compilati vanno direttamente su App Store Connect o Google Play, o a un link di download a tempo limitato se lo richiedi.

Il trade-off: rotare una credenziale significa aggiornare i segreti CI da te stesso. Ri-esporta con build credentials manage e sposta nuovamente il file.

Scadenza e rotazione

Mettere le date Apple in un calendario condiviso. Un certificato scaduto non influisce sugli app già installate sui dispositivi degli utenti, ma blocca ogni nuova build.

Risolvere i problemi

Ulteriori correzioni sono nella Capgo Build troubleshooting guide e CI/CD per Capacitor: trappole comuni.

After il primo build firmato

Sono necessari solo i build nativi firmati quando cambiano le code. Per le modifiche JavaScript, CSS e HTML, invia un code live update Per applicazioni installate invece e conserva le costruzioni dello store per le rilascio che toccano plugin o configurazione nativa. Se provenite da un setup basato su Mac, Costruisci un'app iOS da Windows con Capgo Build mostra il workflow completo senza macOS.