Gestione delle credenziali

Gestisci le tue credenziali di costruzione iOS e Android localmente per costruire facilmente in cloud.

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 tenerle in .capgo-credentials.json altrimenti. 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 le credenziali?

Se non hai ancora i certificati e le 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: Costruzioni iOS automatiche - Configurazione completa CI/CD

Italiano:

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

Garanzia di Sicurezza

I tuoi credenziali NON vengono mai memorizzate permanentemente sui server di Capgo:

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

Comandi

Gestisci Credenziali Interattivamente

Il modo più veloce per lavorare con le tue credenziali salvate è il manager 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 un'istanza del platform:

bunx @capgo/cli@latest build credentials manage

Comandi	Descrizione
--appId <appId>	Applicazione per la gestione (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 invece del file globale

Preferisci comandi scriptabili, uno alla volta? Usa i comandi individuali qui sotto.

Salva Credenziali

Ricorda le tue credenziali di costruzione 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 tutte:

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

Il update il comando utilizza l'aggiunta di merge Per la configurazione dei profili di provisioning — i nuovi profili vengono uniti a 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 tutte sono facoltative — solo i campi che fornite vengono aggiornati.

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

Sezione intitolata “Cancella Credenziali”

# 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 di profilo singolo legacy nel nuovo formato multi-target:

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

Il comando migrate rileva vecchi BUILD_PROVISION_PROFILE_BASE64 le converte nel nuovo formato CAPGO_IOS_PROVISIONING_MAPe elimina le chiavi legacy. Consulta Migrazione da un Profilo Singolo per maggiori informazioni.

Salvataggio delle credenziali iOS

Nota

Non hai ancora i certificati iOS? Vedi il Guida ai 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

Option	Descrizione	Richiesto
--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=pathRipetibile per applicazioni multi-target. Se solo un profilo e nessun prefisso bundleId, CLI si auto-estende dal profilo.	Sì (rilascio)
--apple-key <path>	Percorso della 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 del team di 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 numerico di App Store Connect (ad es. 1234567890)	Vedi nota²
--ios-distribution <mode>	Modalità di distribuzione: app_store (di default) o ad_hoc	No
--output-upload	Abilita un collegamento di download a tempo limitato per l'artefatto di costruzione per Capgo	No (di default: false)
--output-retention <seconds>	How long to keep build outputs (e.g. 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 sono obbligatorio se non si passa --output-upload o --skip-build-number-bump o (che evita la necessità di API-driven invio).
• ad_hoc modalità: Queste opzioni sono non richiesto — non si effettua alcuna sottoscrizione all'App Store. Vedi Modalità di distribuzione Ad-Hoc per ulteriori informazioni.

² Password app-specifica (non consigliata)

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), e ( --apple-app-id) sono richieste insieme. Il numero --apple-app-id (App Store Connect → la tua app → Informazioni sull'app → ID Apple) consente all'upload di eseguire senza una richiesta interattiva di 2FA; con questo metodo il numero di build ricade su un timestamp perché App Store Connect non viene interrogato.

Cosa si Salva

Quando salvi 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 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 la Guida per gli edifici Android Per ulteriori istruzioni su come creare un keystore e configurare le credenziali di Store Play.

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 archiviata:

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

Copia negli appunti

Una volta salvati i credenziali, vengono utilizzati 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.json, o locali) .capgo-credentials.json)
3. Nessuna credenziale (priorità più bassa)

Visualizza Credenziali Salvate

Elenco delle credenziali che hai salvato:

bunx @capgo/cli@latest build credentials list

__CAPGO_KEEP_0__

📋 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. I diritti del 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

   La cartella globale si trova nella directory casella utente, fuori dal repository.

3. Credenziali separate

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

Utilizzo CI/CD

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

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 aggiungi --platform android Per limitare 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	JSON mappa degli ID bundle ai dati di profilo di provisioning	Stringa JSON	Sì (rilease)
P12_PASSWORD	Password per il certificato P12	Testo semplice	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	Credenziali	No

Credenziali Android:

Variabile	Descrizione	Formato	Richiesto
ANDROID_KEYSTORE_FILE	File keystore per la firma APK/AAB	Base64	Sì (rilascio)
KEYSTORE_KEY_ALIAS	Alias della chiave all'interno del keystore	Credenziali	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 fornita solo una password, verrà utilizzata per entrambi KEYSTORE_KEY_PASSWORD e KEYSTORE_STORE_PASSWORD.

Esempi di azioni GitHub

github/flussi di lavoro/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

Tip

Il tr -d '\n' elimina i caratteri di fine riga per creare una stringa base64 a una 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
• Nessun file di credenziali sui runner
• Accesso facile e controllo delle rotazioni
• Tracce di audit per l'uso dei segreti

Rotazione delle credenziali

Rota regolarmente le tue credenziali:

1. iOS: Genera nuovi certificati e API chiavi ogni anno
2. Android: Cambia le password del keystore ogni anno
3. : Rotazione dopo cambi di squadra: Rotazione 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 ...

Troubleshooting

Nessun credenziale trovato

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

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 che il file delle credenziali esista:

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

“Permesso negato” quando si legge una credenziale

Rendi accessibili i permessi del file:

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

Contenuto non utilizzato

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

Cancella e salva nuovamente le credenziali

Se le credenziali sembrano 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 già utilizzando 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à salvato le credenziali in formato vecchio (singolo BUILD_PROVISION_PROFILE_BASE64Esegui:

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

   Questo converte il formato legacy single-profile in un CAPGO_IOS_PROVISIONING_MAP e rimuove l'antico 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 – condivise con tutti i tuoi progetti
• Locali (con) --local): .capgo-credentials.json in la cartella root del tuo progetto — sovrascrive il file globale per quel progetto

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

Pasaggi successivi

• Getting Started - Crea il tuo primo build
• Build iOS - Configurazione di build specifica per iOS
• Build Android - Configurazione di costruzione specifica per Android
• Risolvere i problemi - Problemi comuni e soluzioni

Aiuto necessario?

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

support@__CAPGO_KEEP_0__.app

Sezione intitolata “Continuate da Gestione delle credenziali” La gestione delle credenziali per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il workflow 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, 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.