Gestione credenziali

Gestisci localmente le credenziali di build per iOS e Android per build cloud più comode.

Panoramica

Capgo CLI memorizza le tue credenziali di build sul tuo computer — mai sui server di Capgo. Di default risiedono in un unico file globale , ~/.capgo-credentials/credentials.jsoncondiviso tra tutti i tuoi progetti. Passa --local per mantenerle per progetto nella .capgo-credentials.json invece. Quando esegui una build, le credenziali salvate vengono utilizzate automaticamente e inviate in modo sicuro a Capgo, poi eliminate al termine della build.

Ti serve aiuto per le credenziali?

Se non hai ancora i certificati e le credenziali, consulta queste guide complete:

iOS:

• Come ottenere i certificati iOS - Guida passo dopo passo
• Guida ai certificati iOS - Tutorial dettagliato passo dopo passo
• Blog: Build iOS automatiche - Configurazione CI/CD completa

Android:

• Creazione di un keystore - Guida passo dopo passo
• Guida ai certificati Android - Tutorial dettagliato passo dopo passo
• Blog: Build Android automatiche - Configurazione CI/CD completa

Garanzia di sicurezza

Le tue credenziali NON vengono MAI salvate permanentemente sui server di Capgo:

• ✅ Usate SOLO durante il processo di build attivo
• ✅ Eliminate automaticamente al termine della build
• ✅ Le app sono inviate direttamente ad App Store/Play Store - non salviamo NULLA
• ✅ Trasmesse in modo sicuro tramite HTTPS

Comandi

Gestisci le credenziali in modo interattivo

Il modo più rapido per gestire le tue credenziali salvate è il manager interattivo. Apre una TUI (la stessa che build init utilizzi) dove puoi sfogliare i dati salvati, vedere la configurazione per ogni app e piattaforma, esportare un file .env file, oppure elimina le credenziali di una piattaforma:

bunx @capgo/cli@latest build credentials manage

Opzione	Descrizione
--appId <appId>	App da gestire (se omessa, ti chiede di sceglierla)
--platform <ios|android>	Piattaforma da gestire (richiesta se omessa)
--local	Usa quella per progetto .capgo-credentials.json al posto del file globale

Preferisci comandi one-shot e scriptabili? Usa i singoli comandi qui sotto.

Salva credenziali

Salva le credenziali di build in locale per un uso automatico:

bunx @capgo/cli@latest build credentials save --platform <ios|android> [options]

Aggiorna credenziali

Aggiorna parzialmente le credenziali esistenti senza reinserirle tutte:

bunx @capgo/cli@latest build credentials update --platform <ios|android> [options]

Il update comando utilizza un merge additivo per i profili di provisioning: i nuovi profili vengono uniti a quelli esistenti. Per sostituire invece l'intera mappa di provisioning, aggiungi --overwrite-ios-provisioning-map.

Esempio — aggiungi un profilo estensione alle credenziali esistenti:

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"

Il comando update accetta le stesse opzioni di save ma sono tutte opzionali: vengono aggiornati solo i campi forniti.

Elenca credenziali

Visualizza le credenziali attualmente salvate (le password sono oscurate):

bunx @capgo/cli@latest build credentials list

# List credentials for a specific app
bunx @capgo/cli@latest build credentials list --appId com.example.app

Cancella credenziali

Rimuovi le credenziali salvate dal tuo computer locale:

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

# Clear credentials for a specific app + platform
bunx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios

Migra credenziali

Converti il formato legacy a profilo singolo nel nuovo formato multi-target:

bunx @capgo/cli@latest build credentials migrate --platform ios

Il comando migrate rileva le vecchie BUILD_PROVISION_PROFILE_BASE64 credenziali, le converte in CAPGO_IOS_PROVISIONING_MAP, e rimuove le chiavi legacy. Vedi Migrazione da Single Profile per i dettagli.

Salvataggio credenziali iOS

Nota

Non hai ancora i certificati iOS? Guarda il Guida alle build iOS per le istruzioni sulla creazione di certificati e profili di provisioning.

Esempio completo

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "YourP12Password" \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id "ABC1234567" \
  --apple-issuer-id "00000000-0000-0000-0000-000000000000" \
  --apple-team-id "TEAM123456"

Opzioni iOS

Opzione	Descrizione	Obbligatorio
--certificate <path>	Percorso del file di certificato .p12	Sì (release)
--p12-password <password>	Password del certificato .p12	Sì (release)
--ios-provisioning-profile <mapping>	Mappatura dei provisioning profile (bundleId=path). Ripetibile per app multi-target. Se c'è un solo provisioning profile e nessun prefisso bundleId, CLI lo deduce automaticamente dal profilo.	Sì (release)
--apple-key <path>	Percorso della chiave .p8 di App Store Connect API	Vedi nota¹
--apple-key-id <id>	Key ID API di App Store Connect	Vedi nota¹
--apple-issuer-id <id>	Issuer ID (UUID) di App Store Connect API	Vedi nota¹
--apple-team-id <id>	Team ID di App Store Connect	Sì
--apple-id <email>	Email Apple ID per l'upload della password specifica per l'app (alternativa alla chiave API)	Vedi nota²
--apple-app-specific-password <password>	Password specifica per l'app (xxxx-xxxx-xxxx-xxxx)	Vedi nota²
--apple-app-id <id>	ID numerico dell'app su App Store Connect (es. 1234567890)	Vedi nota²
--ios-distribution <mode>	Modalità di distribuzione: app_store (default) o ad_hoc	No
--output-upload	Abilita un link di download Capgo a tempo limitato per l'artefatto della build	No (default: false)
--output-retention <seconds>	Per quanto tempo conservare gli output di build (es. 3600s)	No (default: 3600s)
--skip-build-number-bump	Salta l'incremento automatico del numero di build	No

¹ Requisiti chiave App Store Connect API

• app_store modalità (default): tutte e tre le opzioni di chiave API sono obbligatorie a meno che non si passi --output-upload oppure --skip-build-number-bump (che elimina la necessità di un invio guidato da API).
• ad_hoc modalità: Queste opzioni sono non obbligatorie — non viene effettuato alcun invio all'App Store. Vedi Modalità di distribuzione Ad-Hoc per i dettagli.

² Password specifica per l'app (non consigliata)

Questo metodo è sconsigliato e va evitato. Esiste solo come opzione di compatibilità per i team che migrano da Ionic Appflow. Preferisci una chiave API di App Store Connect (.p8), che è l'opzione consigliata, più potente e più sicura per la CI/CD. Se devi usarla, tutte e tre le opzioni (--apple-id, --apple-app-specific-password, e --apple-app-id) sono richiesti insieme. Il numero --apple-app-id (App Store Connect → la tua app → App Information → Apple ID) permette di eseguire l'upload senza un prompt 2FA interattivo; con questo metodo il build number ricade su un timestamp perché App Store Connect non viene interrogato.

Cosa viene salvato

Quando salvi le credenziali iOS, CLI:

1. Legge i file del certificato e del provisioning profile
2. Li converte in codifica base64
3. Li salva in ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Salva password e ID in chiaro (solo file locali)

Struttura del file salvato:

{
  "ios": {
    "BUILD_CERTIFICATE_BASE64": "...",
    "CAPGO_IOS_PROVISIONING_MAP": "{\"com.example.app\":{\"profile\":\"...\",\"name\":\"match AppStore com.example.app\"}}",
    "APPLE_KEY_CONTENT": "...",
    "P12_PASSWORD": "...",
    "APPLE_KEY_ID": "ABC1234567",
    "APPLE_ISSUER_ID": "...",
    "APP_STORE_CONNECT_TEAM_ID": "TEAM123456",
    "CAPGO_IOS_DISTRIBUTION": "app_store"
  }
}

Salvataggio credenziali Android

Nota

Non hai ancora un keystore? Guarda il Guida alle build Android per istruzioni su come creare un keystore e configurare le credenziali del Play Store.

Esempio completo

bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "KeyPassword123" \
  --keystore-store-password "StorePassword123" \
  --play-config ./play-store-service-account.json

Opzioni Android

Opzione	Descrizione	Obbligatorio
--keystore <path>	Percorso del file .keystore o .jks	Sì (release)
--keystore-alias <alias>	Alias della chiave nel keystore	Sì (release)
--keystore-key-password <password>	Password per l'alias della chiave	Sì (release)
--keystore-store-password <password>	Password del keystore	Sì (release)
--play-config <path>	Percorso del JSON dell'account di servizio Play Store	Yes (submission)

Cosa viene salvato

Quando salvi le credenziali Android, CLI:

1. Legge i file keystore e JSON dell'account di servizio
2. Li converte in codifica base64
3. Li salva in ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Salva password e alias in testo semplice (solo file locali)

Struttura del file salvato:

{
  "android": {
    "ANDROID_KEYSTORE_FILE": "...",
    "PLAY_CONFIG_JSON": "...",
    "KEYSTORE_KEY_ALIAS": "my-key-alias",
    "KEYSTORE_KEY_PASSWORD": "...",
    "KEYSTORE_STORE_PASSWORD": "..."
  }
}

Utilizzo delle credenziali salvate

Una volta salvate le credenziali, vengono utilizzate automaticamente durante il build:

# Credentials automatically loaded from ~/.capgo-credentials/credentials.json
bunx @capgo/cli@latest build request com.example.app --platform ios

Puoi anche sovrascrivere le credenziali salvate usando variabili di ambiente:

# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
bunx @capgo/cli@latest build request com.example.app --platform ios

Ordine di precedenza:

1. Variabili d'ambiente (priorità massima)
2. Credenziali salvate (~/.capgo-credentials/credentials.json, o locali .capgo-credentials.json)
3. Nessuna credenziale (priorità minima)

Visualizzazione delle credenziali salvate

Elenca le credenziali che hai salvato:

bunx @capgo/cli@latest build credentials list

Esempio di output:

📋 Saved Build Credentials:

iOS Credentials:
  ✓ Certificate (base64)
  ✓ Provisioning Map (JSON)
  ✓ Apple Key Content (base64)
  ✓ P12 Password: ********
  ✓ Apple Key ID: ABC1234567
  ✓ Apple Issuer ID: 00000000-0000-0000-0000-000000000000
  ✓ Team ID: TEAM123456

Android Credentials:
  ✓ Keystore (base64)
  ✓ Play Store Config (base64)
  ✓ Keystore Alias: my-key-alias
  ✓ Key Password: ********
  ✓ Store Password: ********

Location: ~/.capgo-credentials/credentials.json

🔒 These credentials are stored locally on your machine only.
   When building, they are sent to Capgo but NEVER stored there.
   They are auto-deleted after build completion.

Best practice di sicurezza

Sicurezza del Local Storage

1. Permessi dei file

   # Global credentials directory + file
   chmod 700 ~/.capgo-credentials
   chmod 600 ~/.capgo-credentials/credentials.json
   # Local (per-project) credentials, if you use --local
   chmod 600 .capgo-credentials.json

2. Non committare mai le credenziali

   # Ignore the per-project credentials file (used with --local)
   echo ".capgo-credentials.json" >> .gitignore

   Il file globale si trova nella tua home directory, fuori dal repo.

3. Separa le credenziali

   • Usa credenziali diverse per lo sviluppo locale e la CI/CD
   • Ruota le credenziali regolarmente
   • Non condividere le credenziali tra i membri del team

Utilizzo in CI/CD

Per gli ambienti CI/CD, preferisci le variabili d'ambiente alle credenziali salvate.

Esporta un file pronto all'uso .env (consigliata)

Invece di codificare in base64 manualmente ogni file di credenziali (vedi qui sotto), lascia che build credentials manage generi il file per te:

bunx @capgo/cli@latest build credentials manage
# pick your app → choose "Export to .env"

Scrive un file .env.capgo.<appId>.<platform> file (permessi 0600) contenente ogni credenziale salvata come variabile d'ambiente: ogni riga è un segreto da aggiungere al tuo provider CI/CD. Entrambe le piattaforme sono combinate di default; aggiungi --platform ios oppure --platform android per limitarlo a una sola.

Attenzione

Il file esportato contiene i tuoi segreti di firma — aggiungilo a .gitignore e non committarlo mai.

Riferimento completo alle variabili d'ambiente

Il CLI legge le seguenti variabili d'ambiente per le credenziali:

Credenziali iOS:

Variabile	Descrizione	Formato	Obbligatorio
BUILD_CERTIFICATE_BASE64	Certificato P12/PKCS12 per la firma di code	Base64	Sì (release)
CAPGO_IOS_PROVISIONING_MAP	Mappa JSON dei bundle ID ai dati del provisioning profile	Stringa JSON	Sì (release)
P12_PASSWORD	Password per il certificato P12	Testo in chiaro	Opzionale
APPLE_KEY_ID	Key ID API di App Store Connect	Stringa (es. “ABC1234567”)	Vedi nota¹
APPLE_ISSUER_ID	Issuer ID API di App Store Connect	Stringa UUID	Vedi nota¹
APPLE_KEY_CONTENT	Chiave API di App Store Connect (contenuto file .p8)	Base64	Vedi nota¹
APP_STORE_CONNECT_TEAM_ID	Team ID di Apple Developer	Stringa (es. “XXXXXXXXXX”)	Sì
CAPGO_IOS_DISTRIBUTION	Modalità di distribuzione: app_store (default) o ad_hoc	Stringa	No

Credenziali Android:

Variabile	Descrizione	Formato	Obbligatorio
ANDROID_KEYSTORE_FILE	File keystore per la firma di APK/AAB	Base64	Sì (release)
KEYSTORE_KEY_ALIAS	Alias della chiave all'interno del keystore	Stringa	Sì (release)
KEYSTORE_KEY_PASSWORD	Password per l'alias della chiave	Testo in chiaro	Sì*
KEYSTORE_STORE_PASSWORD	Password del file keystore	Testo in chiaro	Sì*
PLAY_CONFIG_JSON	JSON dell'account di servizio Google Play	Base64	Yes (submission)

*Se viene fornita una sola password, verrà utilizzata per entrambe KEYSTORE_KEY_PASSWORD e KEYSTORE_STORE_PASSWORD.

Esempio di GitHub Actions

.github/workflows/build.yml

name: Cloud Build

on:
  push:
    branches: [main]

jobs:
  build-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx @capgo/cli@latest build request com.example.app --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          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 }}

  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx @capgo/cli@latest build request com.example.app --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          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 }}

Preparazione dei valori Base64

Per convertire i file delle credenziali in base64 per i segreti CI/CD:

# iOS Certificate (.p12)
base64 -i certificate.p12 | tr -d '\n' > certificate_base64.txt

# iOS Provisioning Profiles — use the CLI to generate CAPGO_IOS_PROVISIONING_MAP:
bunx @capgo/cli@latest build credentials save --platform ios \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  # ... other options
# Then copy CAPGO_IOS_PROVISIONING_MAP from ~/.capgo-credentials/credentials.json to your CI secrets

# iOS App Store Connect Key (.p8)
base64 -i AuthKey_XXXXXX.p8 | tr -d '\n' > apple_key_base64.txt

# Android Keystore (.keystore or .jks)
base64 -i release.keystore | tr -d '\n' > keystore_base64.txt

# Google Play Service Account JSON
base64 -i play-store-service-account.json | tr -d '\n' > play_config_base64.txt

Tip

Il tr -d '\n' rimuove i caratteri di a capo per creare una stringa base64 su una sola riga, più facile da salvare come segreto CI/CD.

Perché le variabili d'ambiente sono più sicure

Questo approccio è più sicuro perché:

• I segreti sono gestiti dalla tua piattaforma CI/CD
• Nessun file di credenziali sui runner
• Rotazione e controllo degli accessi semplificati
• Audit trail per l'uso dei segreti

Rotazione delle credenziali

Ruota regolarmente le tue credenziali:

1. iOS: Genera nuovi certificati e chiavi API ogni anno
2. Android: Cambia le password del keystore ogni anno
3. Dopo cambiamenti nel team: Ruota quando i membri del team lasciano l'organizzazione

Aggiorna le credenzial salvate:

# Re-run save command with new credentials
bunx @capgo/cli@latest build credentials save --platform ios --certificate ./new-cert.p12 ...

Risoluzione problemi

“Nessuna credenziale trovata”

Se la build segnala che non sono state trovate credenziali:

1. Verifica se le credenziali sono salvate:

   bunx @capgo/cli@latest build credentials list

2. Salva le credenziali se mancanti:

   bunx @capgo/cli@latest build credentials save --platform ios ...

3. Verifica che il file di credenziali esista:

   ls -la ~/.capgo-credentials/credentials.json   # global
   ls -la .capgo-credentials.json                 # local (--local)

“Permesso negato” durante la lettura delle credenziali

Correggi i permessi del file:

chmod 600 ~/.capgo-credentials/credentials.json   # global
chmod 600 .capgo-credentials.json                 # local

Le credenziali non vengono usate

Verifica che sia specificata la piattaforma corretta:

# Make sure --platform matches saved credentials
bunx @capgo/cli@latest build request com.example.app --platform ios  # Uses ios credentials
bunx @capgo/cli@latest build request com.example.app --platform android  # Uses android credentials

Cancella e salva nuovamente le credenziali

Se le credenziali sembrano corrotte:

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

# Save again
bunx @capgo/cli@latest build credentials save --platform ios ...

Migrazione dalle variabili d'ambiente

Se stai usando le variabili d'ambiente, puoi migrare alle credenziali salvate:

1. Estrai le variabili d'ambiente attuali

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. Decodifica i file base64 nei file originali (se necessario)

   echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
   echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

3. Salva usando CLI

   bunx @capgo/cli@latest build credentials save \
     --platform ios \
     --certificate ./cert.p12 \
     --ios-provisioning-profile ./profile.mobileprovision \
     --p12-password "$P12_PASSWORD" \
     --apple-key-id "$APPLE_KEY_ID" \
     --apple-issuer-id "$APPLE_ISSUER_ID" \
     --apple-team-id "$APP_STORE_CONNECT_TEAM_ID"

   Se hai credenziali salvate nel vecchio formato (singolo BUILD_PROVISION_PROFILE_BASE64), esegui:

   bunx @capgo/cli@latest build credentials migrate --platform ios

   Questo converte il profilo singolo legacy in un CAPGO_IOS_PROVISIONING_MAP e rimuove il vecchio BUILD_PROVISION_PROFILE_BASE64 e APPLE_PROFILE_NAME chiavi.

4. Testa la build

   bunx @capgo/cli@latest build request com.example.app --platform ios

5. Rimuovi le variabili d'ambiente (opzionale)

   unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

Posizione file

Le credenziali sono memorizzate in un singolo file JSON:

• Globale (predefinito): ~/.capgo-credentials/credentials.json — condiviso tra tutti i tuoi progetti
• Locale (con --local): .capgo-credentials.json nella root del tuo progetto — sovrascrive il file globale per quel progetto

Il file viene creato automaticamente al primo salvataggio delle credenziali. Aggiungi .capgo-credentials.json al tuo .gitignore in modo che le credenziali per progetto non vengano mai commit.

Prossimi passi

• Per iniziare - Crea la tua prima build
• Build iOS - Configurazione di build specifica per iOS
• Build Android - Configurazione di build specifica per Android
• Risoluzione problemi - Problemi comuni e soluzioni

Serve aiuto?

• 📚 Guida al troubleshooting
• 💬 community Discord
• 📧 Email: support@capgo.app

Continua da Gestione credenziali

Se stai usando Gestione credenziali 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.