Gestione delle credenziali

Gestisci i tuoi credenziali di costruzione per iOS e Android localmente per costruire facilmente le nuvole.

Panoramica

Capgo CLI conserva le tue credenziali di costruzione su macchina — mai sui server di Capgo. Di default vivono in uno globale file, ~/.capgo-credentials/credentials.json, condiviso tra tutti i tuoi progetti. Passa --local per tenerli per-progetto in .capgo-credentials.json al posto. Quando esegui una build, i credenziali salvate vengono utilizzate automaticamente e inviate in modo sicuro a Capgo, quindi eliminate dopo la completamento della build.

Hai bisogno di aiuto per ottenere le credenziali?

Se non hai ancora i tuoi certificati e credenziali, consulta questi guide esaustive:

iOS:

• Come ottenere i certificati iOS - Guida passo dopo passo
• Guida ai certificati iOS - Tutorial dettagliato passo dopo passo
• Blog: Costruzione automatica di iOS - Setup CI/CD completo

Android:

• Creazione di un keystore - Guida passo dopo passo
• Guida ai certificati Android - Tutorial dettagliato passo dopo passo
• Blog: Costruzione automatica di build per Android - Configurazione completa di CI/CD

Garanzia di Sicurezza

I tuoi credenziali NON sono mai memorizzate permanentemente sui server Capgo:

• ✅ Utilizzate SOLO durante il processo di costruzione attivo
• ✅ Eliminate automaticamente dopo la conclusione del processo di costruzione
• ✅ Le app vengono inviate direttamente su App Store/Play Store - non memorizziamo nulla
• ✅ Trasmesse in modo sicuro tramite HTTPS

Comandi

Gestisci Credenziali Interattivamente

La via più veloce per lavorare con le tue credenziali salvate è il gestore interattivo. Si apre una finestra di comando (lo stesso utilizzato da build init utilizza) dove puoi esplorare cosa è memorizzato, vedere cosa è configurato per app e piattaforma, esportare un file pronto per il CI/CD .env o cancellare le credenziali di una piattaforma:

bunx @capgo/cli@latest build credentials manage

Opzione	Descrizione
--appId <appId>	Applicazione da gestire (ti chiede di scegliere se omesso)
--platform <ios|android>	Piattaforma da gestire (ti chiede di scegliere se omesso)
--local	Usa il file per progetto .capgo-credentials.json al posto del file globale

Preferere comandi uno-shot, eseguibili da script? Utilizza i comandi individuali di seguito.

Salva Credenziali

Ricorda le tue credenziali di build localmente per l'uso automatico:

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

Aggiorna Credenziali

Aggiorna le credenziali esistenti senza doverle fornire nuovamente tutto:

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

The update utilizza comando fusione additiva per i profili di provisioning — i nuovi profili vengono fusi con quelli esistenti. Per sostituire l'intera mappa di provisioning al suo posto, aggiungi --overwrite-ios-provisioning-map.

Esempio — aggiungi un profilo di estensione ai credenziali esistenti:

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

Il comando di aggiornamento accetta le stesse opzioni di save ma tutte sono facoltative — solo i campi che fornisci vengono aggiornati.

Credenziali elencate

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

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 le credenziali

Elimina 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

Migrare le credenziali

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

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

Il comando di migrazione rileva le vecchie credenziali BUILD_PROVISION_PROFILE_BASE64 credenziali, le converte in CAPGO_IOS_PROVISIONING_MAP, e rimuove le chiavi legacy. Vedi Migrazione da Profilo Singolo per i dettagli.

Salvataggio delle credenziali iOS

Nota

Non hai ancora i certificati iOS? Vedi il guida per la creazione di 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 per iOS

Opzione	Descrizione	Obbligatorio
--certificate <path>	Percorso del file di certificato .p12	Sì (rilascio)
--p12-password <password>	Password per il file di certificato .p12	Sì (rilascio)
--ios-provisioning-profile <mapping>	Mappatura del profilo di provisioning (bundleId=path). Ripetibile per applicazioni multi-target. Se presente solo un profilo e nessun prefisso bundleId, CLI si auto-inferisce dal profilo.	Sì (rilascio)
--apple-key <path>	Percorso della chiave API .p8 di App Store Connect	Vedi nota¹
--apple-key-id <id>	ID chiave di App Store Connect API	Vedi nota¹
--apple-issuer-id <id>	ID emittente di App Store Connect API (UUID)	Vedi nota¹
--apple-team-id <id>	ID team di App Store Connect	Sì
--apple-id <email>	E-mail Apple ID per caricamento della password app-specifica (alternativa alla chiave API)	Vedi nota²
--apple-app-specific-password <password>	Password app-specifica (xxxx-xxxx-xxxx-xxxx)	Vedi nota²
--apple-app-id <id>	ID numerico di App Store Connect (ad esempio 1234567890)	Vedi nota²
--ios-distribution <mode>	Modalità di distribuzione: app_store o ad_hoc	No
--output-upload	Abilita un link di download a tempo limitato Capgo per l'artifact del build	No (predefinito: false)
--output-retention <seconds>	Quanto tempo mantenere gli output del build (ad esempio 3600s)	No (predefinito: 3600s)
--skip-build-number-bump	Saltare l'aumento automatico del numero di versione	No

¹ Requisiti chiave App Store Connect API

• app_store modalità (predefinito): Tutte e tre le opzioni chiave API sono richieste a meno che non si passi --output-upload o --skip-build-number-bump (che bypassa la necessità di una sottoscrizione guidata da API-driven).
• ad_hoc modalità: Queste opzioni sono non richieste — non si effettua alcuna sottoscrizione all'App Store. Vedi Modalità di distribuzione Ad-Hoc per i dettagli.

² Password app-specifica (non consigliata)

Questo metodo è scoraggiato e consigliato contro. Esiste solo come percorso di compatibilità per le squadre che stanno migrando da Ionic Appflow. Preferisci una chiave App Store Connect API (.p8), che è l'opzione consigliata, più capace e più sicura per CI/CD. Se devi usarla, tutte e tre le opzioni (--apple-id, --apple-app-specific-password, --apple-app-ide --apple-app-id (App Store Connect → il tuo app → App Information → Apple ID) consente l'upload senza richiedere una richiesta interattiva 2FA; con questo metodo il numero di build ricade su un timestamp perché App Store Connect non viene interrogato.

Cosa si Salva

Quando salvate le credenziali iOS, il CLI:

1. Legge i file del certificato e del profilo di provisioning
2. Li converte in codifica base64
3. Li salva in ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Memorizza le password e gli ID come testo piano (solo file locali)

La struttura del file memorizzato:

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

Salvare credenziali Android

Nota

Non hai ancora un keystore? Vedi il guida per la creazione di un keystore e la configurazione delle credenziali di Store Play Esempio Completo

Sezione intitolata “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 per Android

Opzione	Descrizione	Richiesto
--keystore <path>	Percorso per il file .keystore o .jks	Sì (rilascio)
--keystore-alias <alias>	Cognome dell'alias nella chiave	Sì (rilascio)
--keystore-key-password <password>	Password per l'alias della chiave	Sì (rilascio)
--keystore-store-password <password>	Password per il keystore	Sì (rilascio)
--play-config <path>	Percorso al file JSON del servizio account di Play Store	Sì (invio)

Cosa si conserva

Quando si salvano le credenziali Android, il CLI:

1. Legge i file keystore e JSON del servizio account
2. Li converte in codifica base64
3. Li salva in ~/.capgo-credentials/credentials.json o .capgo-credentials.json con --local)
4. Conserva le password e l'alias come testo normale (solo file locali)

La struttura del file archiviato:

{
  "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 quando si costruisce:

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

È anche possibile sovrascrivere le credenziali salvate utilizzando le 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 di ambiente (priorità più alta)
2. Dettagli delle credenziali salvate (~/.capgo-credentials/credentials.json, o locale .capgo-credentials.json)
3. Senza credenziali (priorità più bassa)

Visualizza Credenziali Salvate

Elenco delle credenziali salvate:

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.

Pratiche di sicurezza migliorative

Salvataggio Locale Sicurezza

1. Permessi di 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 Commettere Mai le Credenziali

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

   Il file globale risiede nella directory casella utente, al di fuori del repository.

3. Credenziali Separate

   • Usa credenziali diverse per lo sviluppo locale vs CI/CD
   • Rimuovi le credenziali regolarmente
   • Non condividere le credenziali tra membri del team

Utilizzo CI/CD

Per ambienti CI/CD, preferisci le variabili di ambiente alle credenziali salvate.

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

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

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

Scrive un .env.capgo.<appId>.<platform> file (permessi 0600) contenente ogni credenziale salvata come variabile di ambiente — ogni riga è un segreto da aggiungere al tuo provider CI/CD. Le due piattaforme sono combinate per impostazione predefinita; aggiungi --platform ios o --platform android per limitarlo a una.

Attenzione

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

Riferimento completo alle variabili di ambiente

CLI legge le seguenti variabili di ambiente per le credenziali:

Credentiali iOS:

Variabile	Descrizione	Formato	Richiesto
BUILD_CERTIFICATE_BASE64	Certificato P12/PKCS12 per la firma di code	Base64	Sì (rilascio)
CAPGO_IOS_PROVISIONING_MAP	JSON mappa degli ID pacchetti alle informazioni di profilo di provisioning	Stringa JSON	Sì (rilascio)
P12_PASSWORD	Password per il certificato P12	Testo normale	Facoltativo
APPLE_KEY_ID	ID chiave App Store Connect API	Stringa (ad esempio, "ABC1234567")	Vedi nota¹
APPLE_ISSUER_ID	ID emittente App Store Connect API	Stringa UUID	Vedi nota¹
APPLE_KEY_CONTENT	Contenuto della chiave App Store Connect API (.p8 file)	Base64	Vedi nota¹
APP_STORE_CONNECT_TEAM_ID	ID del team di sviluppatore di Apple	Stringa (ad esempio, “XXXXXXXXXX”)	Sì
CAPGO_IOS_DISTRIBUTION	Modalità di distribuzione: app_store (di default) o ad_hoc	Stringa	No

Credenziali Android:

Variabile	Descrizione	Formato	Richiesto
ANDROID_KEYSTORE_FILE	File del keystore per la firma APK/AAB	Base64	Sì (rilease)
KEYSTORE_KEY_ALIAS	Alias della chiave all'interno del keystore	Stringa	Sì (rilease)
KEYSTORE_KEY_PASSWORD	Password per l'alias della chiave	Testo piano	Sì*
KEYSTORE_STORE_PASSWORD	Password per il file del keystore	Testo normale	Sì
PLAY_CONFIG_JSON	File JSON del servizio Google Play	Base64	Sì (invio)

*Se vengono forniti solo due password, verrà utilizzata la prima per l'accesso e la seconda per il token* KEYSTORE_KEY_PASSWORD e KEYSTORE_STORE_PASSWORD.

Esempi di azioni di GitHub

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 dei tuoi 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

Consiglio

Il tr -d '\n' elimina le righe di fine riga per creare una stringa di base64 a una riga sola, che è più facile da memorizzare come segreto CI/CD.

Perché le Variabili di Ambiente sono più Sicure

Questo approccio è più sicuro perché:

• I segreti sono gestiti dalla tua piattaforma CI/CD
• No file di credenziali sui runner
• Accesso facile e controllo delle credenziali
• Tracce di audit per l'uso delle credenziali

Rotazione delle credenziali

Rotazione regolare delle credenziali:

1. iOSGenera nuovi certificati e API chiavi ogni anno
2. AndroidCambia le password del keystore ogni anno
3. Dopo i cambiamenti della squadraRotazione quando i membri della squadra lasciano

Aggiorna le credenziali salvate:

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

Risoluzione dei problemi

”Nessuna credenziale trovata”

Se il build dice che non sono state trovate le credenziali:

1. Controlla 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 l'esistenza del file delle credenziali:

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

“Permission denied” when reading credentials

Sezione intitolata “errore di permesso quando si leggono le credenziali”

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

Copia nel portapenne

Verifica di aver specificato 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

Pulisci 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 da Variabili di Ambiente

Se stai utilizzando attualmente le variabili di ambiente, puoi migrare alle credenziali salvate:

1. Estrai le tue attuali variabili di ambiente

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. Decodifica i file base64 di ritorno ai file originali (se necessario)

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

3. Salva utilizzando il 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 già le credenziali salvate nel formato vecchio (singolo BUILD_PROVISION_PROFILE_BASE64), esegui:

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

   Questo converte il profilo legacy a CAPGO_IOS_PROVISIONING_MAP e rimuove gli BUILD_PROVISION_PROFILE_BASE64 e APPLE_PROFILE_NAME chiavi.

4. Testa la costruzione

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

5. Elimina le variabili di ambiente (facoltativo)

   unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

Posizione del file

I credenziali sono memorizzate in un unico file JSON:

• Globali (di default): ~/.capgo-credentials/credentials.json — condiviso da tutti i tuoi progetti
• Locali (con --local): .capgo-credentials.json nel root del tuo progetto — sovrascrive il file globale per quel progetto

Il file viene creato automaticamente la prima volta che si salvano le credenziali. Aggiungi .capgo-credentials.json a .gitignore così che le credenziali per progetto non vengono mai committe.

Passaggi successivi

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

Aiuto?

• 📚 Guida di risoluzione dei problemi
• 💬 Comunità Discord
• 📧 Email: support@capgo.app

Continua da Gestione delle credenziali

Se stai utilizzando Gestione delle credenziali per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Build nativi 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 il dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione azioni per il dettaglio di implementazione in GitHub Integrazione azioni.