Gestione delle credenziali

Gestisci le tue credenziali di build iOS e Android localmente per eseguire build cloud comodi.

Panoramica

Capgo CLI conserva le tue credenziali di costruzione sulla tua macchina — mai sui server di Capgo. Di default vivono in uno global globale ~/.capgo-credentials/credentials.json, condiviso da tutti i tuoi progetti. --local per mantenerli per-project nella .capgo-credentials.json invece. Quando esegui una build, i credenziali salvate vengono utilizzate automaticamente e inviate in modo sicuro a Capgo, poi cancellate dopo la completamento della build.

Aiuto per ottenere le credenziali?

Se non hai ancora i certificati e le credenziali, consulta questi guide approfondite:

iOS:

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

Android:

• Creazione di un Keystore: - Guida passo dopo passo
• Guida alle certificazioni Android: - Tutorial dettagliato passo dopo passo
• Blog: Costruzione automatica di Android: - Configurazione completa CI/CD

Garanzia di sicurezza:

Le tue credenziali NON sono mai memorizzate permanentemente sui server Capgo:

• ✅ Utilizzate SOLO durante il processo di costruzione attivo
• ✅ Eliminato automaticamente dopo la completamento della costruzione
• ✅ Le App vengono inviate direttamente su App Store/Play Store - non conserviamo NULLA
• ✅ Vengono trasmesse in modo sicuro tramite HTTPS

Comandi

Gestisci Credenziali Interattivamente

Il modo più veloce per lavorare con le tue credenziali salvate è il gestore interattivo. Apre una TUI (lo stesso utilizzato build init utilizza) dove puoi esplorare cosa è memorizzato, vedere cosa è configurato per app e piattaforma, esportare un CI/CD pronto per l'uso .env file, o cancella le credenziali di una piattaforma:

bunx @capgo/cli@latest build credentials manage

Option	Descrizione
--appId <appId>	Applicazione per la gestione (ti chiede di scegliere se omesso)
--platform <ios|android>	Piattaforma per gestire (richiede conferma se omesso)
--local	Usa il file per progetto .capgo-credentials.json invece del file globale

Preferisci comandi scriptabili, uno alla volta? Usa i comandi individuali di seguito.

Salva Credenziali

Ripristina le tue credenziali di costruzione localmente per l'uso automatico:

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

Aggiorna Credenziali

Aggiorna parzialmente le credenziali esistenti senza doverle fornire nuovamente tutte:

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

Il update comando utilizza l'aggiunta di merge per la configurazione dei profili di provisioning — nuovi profili vengono fusi con quelli esistenti. Per sostituire l'intera mappa di provisioning, aggiungi --overwrite-ios-provisioning-map.

Esempio — aggiungi un profilo di 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 di aggiornamento accetta le stesse opzioni che save ma pero tutti sono facoltativi — vengono aggiornati solo i campi che fornite.

Elenco Credenziali

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

Credenziali Chiare

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 Credenziali

Converti il formato di profilo singolo di versione precedente nel nuovo formato multi-target:

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

Il comando migrate rileva vecchi BUILD_PROVISION_PROFILE_BASE64 Migrazione da un Profilo Singolo CAPGO_IOS_PROVISIONING_MAPper maggiori informazioni. Salvataggio delle credenziali iOS per ulteriori informazioni.

Salvataggio credenziali iOS

Nota

Non hai ancora i certificati iOS? Vedi il Guida ai costrutti iOS per 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	Richiesto
--certificate <path>	Percorso del file di certificato .p12	Sì (rilease)
--p12-password <password>	Password per il file di certificato .p12	Sì (rilease)
--ios-provisioning-profile <mapping>	Mappatura del profilo di provisioning (bundleId=path) Ripetibile per applicazioni multi-target. Se solo un profilo e nessun prefisso bundleId, CLI si auto-inferisce dal profilo.	Sì (rilease)
--apple-key <path>	Percorso per la chiave .p8 di App Store Connect API	Vedi nota¹
--apple-key-id <id>	ID chiave di App Store Connect API	Vedi nota¹
--apple-issuer-id <id>	App Store Connect API ID emittente (UUID)	Vedi nota¹
--apple-team-id <id>	ID team App Store Connect	Sì
--apple-id <email>	Indirizzo email Apple ID per l'upload della password app-specifica (alternativa al API chiave)	Vedi nota²
--apple-app-specific-password <password>	Password app-specifica (xxxx-xxxx-xxxx-xxxx)	Vedi nota²
--apple-app-id <id>	ID app numerico App Store Connect (ad es. 1234567890)	Vedi nota²
--ios-distribution <mode>	Modalità di distribuzione: app_store (di default) o ad_hoc	No
--output-upload	Enable a time-limited Capgo download link for the build artifact	No (di default: false)
--output-retention <seconds>	Quanto mantenere gli output di costruzione (ad esempio 3600s)	No (di default: 3600s)
--skip-build-number-bump	Saltare l'aumento automatico del numero di build	No

¹ Requisiti chiave App Store Connect API

• app_store modalità di default: tutte e tre le opzioni chiave API richiesto se non si passa --output-upload o --skip-build-number-bump (che evitano la necessità di una sottoscrizione guidata da API)
• ad_hoc modeQueste opzioni sono Queste opzioni sono — non si effettua alcuna sottoscrizione all'App Store. Vedi Modalità di Distribuzione Ad-Hoc Modalità di distribuzione Ad-Hoc

² Password dell'applicazione (non consigliato)

Questa funzione è scoraggiata e consigliata contro. Esiste solo come percorso di compatibilità per le squadre che stanno migrando da Ionic Appflow. Preferisci una chiave API di App Store Connect (.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, and --apple-app-idSono richiesti insieme. Il numero --apple-app-id (App Store Connect → your app → App Information → Apple ID) lets the upload run without an interactive 2FA prompt; with this method the build number falls back to a timestamp because App Store Connect is not queried.

Sezione intitolata “Cosa si Salva”

Quando salvi le credenziali iOS, il CLI:

1. Legge i file di certificato e provisioning
2. Converte in codifica base64
3. Salva loro in ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Memorizza le password e gli ID come testo normale (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"
  }
}

Salvataggio delle credenziali Android

Nota

Non hai ancora un keystore? Vedi il Guida per le costruzioni Android Istruzioni per la creazione di un keystore e la configurazione dei credenziali di 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 per Android

Opzione	Descrizione	Obbligatorio
--keystore <path>	Percorso del file .keystore o .jks	Sì (rilascio)
--keystore-alias <alias>	Alias della chiave nel keystore	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 del file JSON del servizio account Play Store	Yes (submission)

Cosa viene memorizzato

Quando salvate le credenziali Android, il CLI:

1. Legge i file keystore e JSON del servizio account
2. Converte in codifica base64
3. Salva loro in ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Memorizza le password e gli alias come testo normale (solo file locali)

La struttura del file memorizzato:

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

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

Puoi anche 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. Credenziali salvate (~/.capgo-credentials/credentials.jsono locale .capgo-credentials.json)
3. Nessuna credenziale (priorità più bassa)

Visualizzazione delle credenziali salvate

Elenco delle 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.

Pratiche di sicurezza

Sicurezza del Storage locale

1. Autorizzazioni 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 commettere mai le credenziali

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

   Il file globale si trova nella directory casella utente, fuori dal 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 quelle salvate le credenziali.

Esporta un ready-to-use .env (consigliato)

Invece di codificare manualmente ogni file di credenziali in base64 (vedi) di seguito), let build credentials manage Finestra del terminale

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

It writes a .env.capgo.<appId>.<platform> file (permessi) 0600) containing every saved credential as an environment variable — each line is one secret to add to your CI/CD provider. Both platforms are combined by default; add --platform ios a --platform android Per limitare lo scope a uno.

Attenzione

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

Riferimento completo alle variabili di ambiente

Il CLI legge le seguenti variabili di ambiente per le credenziali:

Credenziali iOS:

Variabile	Descrizione	Formato	Obbligatorio
BUILD_CERTIFICATE_BASE64	Certificato P12/PKCS12 per la firma di code	Base64	Sì (rilease)
CAPGO_IOS_PROVISIONING_MAP	Cartella JSON dei ID pacchetti a dati di profilo di provisioning	Stringa JSON	Sì (rilease)
P12_PASSWORD	Password per il certificato P12	Testo piano	Facoltativo
APPLE_KEY_ID	ID chiave di App Store Connect per API	Stringa (ad esempio, "ABC1234567")	Vedi nota¹
APPLE_ISSUER_ID	App Store Connect API ID rilasciatore	Stringa UUID	Vedi nota¹
APPLE_KEY_CONTENT	App Store Connect API chiave (.p8 file content)	Base64	Vedi nota¹
APP_STORE_CONNECT_TEAM_ID	ID team Apple Developer	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	Obbligatorio
ANDROID_KEYSTORE_FILE	File keystore per la firma APK/AAB	Base64	Sì (rilascio)
KEYSTORE_KEY_ALIAS	Alias della chiave all'interno del keystore	Stringa	Sì (rilascio)
KEYSTORE_KEY_PASSWORD	Password per l'alias della chiave	Testo normale	Sì*
KEYSTORE_STORE_PASSWORD	Password per il file del keystore	Testo normale	Sì*
PLAY_CONFIG_JSON	JSON del servizio Google Play	Base64	Yes (submission)

*Se viene fornata solo una password, verrà utilizzata per entrambi KEYSTORE_KEY_PASSWORD and KEYSTORE_STORE_PASSWORD.

GitHub Azioni di Esempio

github/workflow/compila.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 di 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' elimina i caratteri di fine riga per creare una stringa base64 a una sola riga, più facile da memorizzare come segreto CI/CD.

Perché le variabili di ambiente sono più sicure.

Questa approccio è più sicuro perché:

• I segreti sono gestiti dalla tua piattaforma CI/CD.
• Assenza di file di credenziali sui runner.
• Accesso facile e controllo delle rotazioni.
• Tracce di audit per l'utilizzo dei segreti.

Rotazione delle credenziali.

Rotazione regolare delle tue credenziali:

1. iOS: Genera nuovi certificati e API chiavi annualmente
2. Android: Cambia le password del keystore ogni anno
3. : Dopo i cambiamenti del team: Ruota quando i membri del team 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 ...

Risolvere i problemi

“Non sono stati trovati alcun credenziali”

Se il build indica che non sono stati trovati alcun credenziale:

1. Controlla se le credenziali sono state 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)

“Permesso negato” quando si legge una credenziale

Correggi i permessi del file:

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

I credenziali non vengono utilizzate

Verifica che la piattaforma corretta sia specificata:

# 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 essere danneggiate:

# 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 ai credenziali salvate:

1. Estrai le tue attuali variabili di ambiente

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. Decodifica i file base64 di nuovo in 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à salvato le credenziali in formato vecchio (singolo BUILD_PROVISION_PROFILE_BASE64) esegui:

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

   Questo converte il profilo legacy a un CAPGO_IOS_PROVISIONING_MAP e rimuove l'antico BUILD_PROVISION_PROFILE_BASE64 e APPLE_PROFILE_NAME keys.

4. Verifica 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 — condivise tra tutti i tuoi progetti
• Locali (con --local): .capgo-credentials.json nel tuo root del 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 al tuo .gitignore così le credenziali per progetto non vengono mai committe.

Next Steps

• Getting Started - Crea il tuo primo build
• Build iOS - Configurazione di build specifica per iOS
• Build Android - Configurazione di costruzione specifica per Android
• Troubleshooting Risoluzione dei problemi

Aiuto necessario?

• 📚 Scheda intitolata “Aiuto?”
• 💬 Guida alla risoluzione dei problemi
• Comunità Discord support@capgo.app

supporto@__CAPGO_KEEP_0__.app

Scheda intitolata “Continua da Gestione delle credenziali” 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 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, Integrazioni per il flusso di lavoro del prodotto in Integrazioni, Integrazione GitHub Azioni per i dettagli di implementazione in GitHub Integrazione delle azioni.