Gestione delle credenziali

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

Panoramica

Capgo CLI ti consente di salvare le credenziali di costruzione localmente sul tuo computer nel .capgo-credentials Capgo __CAPGO_KEEP_1__ ti consente di salvare le credenziali di costruzione localmente sul tuo computer nel

Aiuto per ottenere le credenziali?

Se non hai ancora le tue certificazioni e credenziali, consulta questi guide esaustive:

iOS:

• Come ottenere le certificazioni iOS - Guida passo dopo passo
• Guida alle certificazioni iOS - Tutorial dettagliato passo dopo passo
• Blog: Costruzione automatica iOS - Configurazione completa CI/CD

Android:

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

Garanzia di Sicurezza

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

• ✅ Utilizzate SOLO durante il processo di costruzione attivo
• ✅ Eliminate automaticamente dopo la conclusione della costruzione
• ✅ Massimo periodo di conservazione: 24 ore (anche se la costruzione fallisce)
• ✅ Le app vengono inviate direttamente su App Store/Play Store - non conserviamo nulla
• ✅ Trasmesse in modo sicuro tramite HTTPS

Comandi

Salva Credenziali

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

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

Aggiorna Credenziali

Aggiorna le credenziali esistenti in parte senza doverle fornire nuovamente tutto:

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

Il comando utilizza la fusione additiva per i profili di provisioning — nuovi profili vengono fusi con quelli esistenti. update Per sostituire l'intero elenco dei profili di provisioning, aggiungi Esempio — aggiungi un profilo di estensione ai credenziali esistenti: Finestra del terminale --overwrite-ios-provisioning-map.

Copia nel portapenne

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

Elenco Credenziali save Sezione intitolata “Elenco Credenziali”

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

Finestra del terminale __CAPGO_KEEP_0__

npx @capgo/cli build credentials list

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

Cancella credenziali

Elimina le credenziali salvate dal tuo computer locale:

# Clear all credentials
npx @capgo/cli build credentials clear

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

Migra credenziali

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

npx @capgo/cli build credentials migrate --platform ios

Il comando migrate rileva le credenziali vecchie, le converte in BUILD_PROVISION_PROFILE_BASE64 e elimina le chiavi legacy. Vedi CAPGO_IOS_PROVISIONING_MAPMigration from Single Profile per i dettagli. Salvataggio delle credenziali iOS

Sezione intitolata “Salvataggio delle credenziali iOS”

Non hai ancora i certificati iOS?

Vedi il guide per le costruzioni iOS Vedi la per istruzioni su come creare certificati e profili di provisioning.

Esempio Completo

npx @capgo/cli 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	Richiesto
--certificate <path>	Percorso del file .p12 del certificato	Sì (rilascio)
--p12-password <password>	Password per il certificato .p12	Sì (rilascio)
--ios-provisioning-profile <mapping>	Mappatura del profilo di provisioning (bundleId=path). Ripetibile per app multi-target. Se solo un profilo e nessun prefisso bundleId, CLI si auto-inferisce dal profilo.	Sì (rilascio)
--apple-key <path>	Percorso della chiave .p8 di App Store Connect API	Nota¹:
--apple-key-id <id>	ID chiave di App Store Connect API	Nota¹:
--apple-issuer-id <id>	ID emittente di App Store Connect API (UUID)	Nota¹:
--apple-team-id <id>	ID team di App Store Connect	Sì
--ios-distribution <mode>	Modalità di distribuzione: app_store (di default) o ad_hoc	No
--output-upload	Abilita un link di download temporaneo Capgo per l'artifact di costruzione	No (di default: false)
--output-retention <seconds>	Quanto tempo mantenere gli output di costruzione (ad esempio 3600s)	No (di default: 3600s)
--skip-build-number-bump	Saltare l'aumento automatico del numero di costruzione	No

¹ Requisiti della chiave App Store Connect API

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

Cosa viene memorizzato

Quando si salvano le credenziali iOS, il CLI:

1. Legge i file dei certificati e dei profili di provisioning
2. Li converte in codifica base64
3. Salva le credenziali nel .capgo-credentials cartella
4. Memorizza le password e gli ID in 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"
  }
}

Salvataggio delle credenziali Android

Nota

Non hai ancora un keystore? Vedi il guida per la creazione di un keystore e la configurazione dei credenziali di Play Store per le istruzioni su come creare un keystore e configurare i credenziali di Play Store.

Esempio Completo

npx @capgo/cli 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ì (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 Play Store	Sì (invio)

Cosa si conserva

Quando salvate le credenziali Android, il CLI:

1. Legge i file keystore e account di servizio JSON
2. Li converte in codifica base64
3. Salva le credenziali nel .capgo-credentials cartella
4. Conserva le password e gli alias come testo normale (solo file locali)

La struttura del file conservato:

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

Utilizza le credenziali salvate

Una volta salvate le credenziali, vengono utilizzate automaticamente quando si costruisce:

# Credentials automatically loaded from .capgo-credentials folder
npx @capgo/cli build 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" \
npx @capgo/cli build com.example.app --platform ios

Ordine di precedenza:

1. Variabili di ambiente (priorità più alta)
2. Credenziali salvate in .capgo-credentials cartella
3. Nessuna credenziale (priorità più bassa)

Visualizzazione dei Credenziali Salvate

Elencare le credenziali che hai salvato:

npx @capgo/cli 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/

🔒 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

   # Ensure credentials folder is not readable by others
   chmod 700 .capgo-credentials
   chmod 600 .capgo-credentials/*

2. Non inserire mai le credenziali

   # Add to .gitignore
   echo ".capgo-credentials/" >> .gitignore

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 di CI/CD

Per ambienti CI/CD, preferare le variabili di ambiente, piuttosto che i credenziali salvate.

Riferimento completo alle variabili di ambiente

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

Credenziali 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 a dati di profilo di provisioning	Stringa JSON	Sì (rilascio)
P12_PASSWORD	Password per il certificato P12	Testo normale	Facoltativo
APPLE_KEY_ID	Chiave ID di App Store Connect API	Stringa (ad esempio, "ABC1234567")	Vedi nota¹
APPLE_ISSUER_ID	ID emittente di App Store Connect API	Stringa UUID	Vedi nota¹
APPLE_KEY_CONTENT	Chiave App Store Connect API (contenuto del file .p8)	Base64	Vedi nota¹
APP_STORE_CONNECT_TEAM_ID	ID del team sviluppatore 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	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 puro	Sì
KEYSTORE_STORE_PASSWORD	Password per il file del keystore	Testo normale	Sì
PLAY_CONFIG_JSON	JSON del servizio Google Play	Base64	Sì (invio)

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

GitHub Actions Example

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: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npx @capgo/cli build 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: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npx @capgo/cli build 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:
npx @capgo/cli build credentials save --platform ios \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  # ... other options
# Then copy CAPGO_IOS_PROVISIONING_MAP from .capgo-credentials 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

Suggerimento

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

Perché le variabili di ambiente sono più sicure

Questa approccio è più sicuro perché:

• Le segrete sono gestite dalla tua piattaforma CI/CD
• Nessun file di credenziali sui runner
• Rotazione facile e controllo degli accessi
• Tracce di audit per l'uso delle segrete

Rotazione delle credenziali

Rota le tue credenziali regolarmente:

1. iOS: Genera nuovi certificati e API chiavi annualmente
2. Android: Cambia le password del keystore ogni anno
3. Dopo le modifiche del team: Ruota quando i membri del team lasciano

Aggiorna le credenziali salvate:

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

Risoluzione dei problemi

”No credentials found”

Se il build dice che non sono state trovate credenziali:

1. Controlla se le credenziali sono salvate:

   npx @capgo/cli build credentials list

2. Salva le credenziali se mancanti:

   npx @capgo/cli build credentials save --platform ios ...

3. Verifica l'esistenza della cartella delle credenziali:

   ls -la .capgo-credentials/

“Rifiutato il permesso” quando si leggono le credenziali

Correggi i permessi del file:

chmod 700 .capgo-credentials
chmod 600 .capgo-credentials/*

Le credenziali non vengono utilizzate

Verifica di aver specificato la piattaforma corretta:

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

Pulisci e salva nuovamente le credenziali

Se le credenziali sembrano essere danneggiate:

# Clear all credentials
npx @capgo/cli build credentials clear

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

Migrazione da Variabili di Ambiente

Se attualmente stai utilizzando 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 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

   npx @capgo/cli 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 esistenti nel formato vecchio (singolo) BUILD_PROVISION_PROFILE_BASE64Esegui:

   npx @capgo/cli build credentials migrate --platform ios

   Questo converte il profilo legacy a un CAPGO_IOS_PROVISIONING_MAP e elimina le vecchie BUILD_PROVISION_PROFILE_BASE64 e APPLE_PROFILE_NAME chiavi.

4. Testa la build

   npx @capgo/cli build 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 nel .capgo-credentials cartella:

• macOS/Linux: .capgo-credentials/ (nella cartella root del tuo progetto o nella directory home)
• Windows: .capgo-credentials\ (nella cartella root del tuo progetto o nella directory home)

La cartella viene creata automaticamente quando salvi le credenziali per la prima volta.

Passaggi successivi

• Inizio - 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

Aiuto richiesto?

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