Gestione delle credenziali

Copia una promessa di installazione con i passaggi di installazione e la guida markdown completa per questo plugin.

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

Riepilogo

Capgo CLI conserva le credenziali di build sulla tua macchina — mai sui server di Capgo. Di default vivono in un file unico globale, ~/.capgo-credentials/credentials.json, condiviso da tutti i tuoi progetti. Passa --local per tenerle per-progetto in .capgo-credentials.json al posto. Quando esegui una build, le credenziali salvate vengono utilizzate automaticamente e inviate in modo sicuro a Capgo, quindi cancellate dopo la completamento della build.

Comandi

Gestisci Credenziali Interattivamente

Il modo più veloce per lavorare con le tue credenziali salvate è il gestore interattivo. Apre una finestra di comando (lo stesso utilizzato per il terminale) dove puoi esplorare cosa è memorizzato, vedere cosa è configurato per app e piattaforma, esportare un file pronto per il CI/CD, o cancellare le credenziali di una piattaforma: build init Finestra del terminale .env Copia nel portapenna

bunx @capgo/cli@latest build credentials manage

Applicazione da gestire (ti chiede di scegliere se omesso)	App to manage (prompts you to pick if omitted) __CAPGO_KEEP_0__
`--appId <appId>`	The quickest way to work with your saved credentials is the interactive manager. It opens a TUI (the same one __CAPGO_KEEP_0__ uses) where you can browse what’s stored, see what’s configured per app and platform, export a CI/CD-ready __CAPGO_KEEP_0__ file, or delete a platform’s credentials: __CAPGO_KEEP_0__
`--platform <ios\|android>`	Piattaforma per la gestione (promuove se omesso)
`--local`	Usa il file per progetto `.capgo-credentials.json` Usa il file per progetto invece del file globale

Preferisci comandi scriptabili, da eseguire una sola volta? Usa i comandi individuali di seguito.

Salva Credenziali

Memorizza 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 riinserire tutte:

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

Il update il comando utilizza l'incorporamento cumulativo per i profili di provisioning — i nuovi profili vengono incorporati 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.

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 cancellate

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 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 credenziali vecchie BUILD_PROVISION_PROFILE_BASE64 , le converte in CAPGO_IOS_PROVISIONING_MAP, e rimuove le chiavi legacy. Vedi Migrazione da Profilo Singolo per i dettagli.

Salvataggio delle credenziali iOS

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	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=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 del file di 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)	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 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 dell'app di App Store Connect (ad esempio `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'artifact di costruzione per il valore Capgo	No (predefinito: `false`)
`--output-retention <seconds>`	Quanto tempo mantenere gli output di costruzione (ad esempio `3600s`)	No (predefinito: `3600s`)
`--skip-build-number-bump`	Saltare l'aumento automatico del numero di costruzione	No

(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.

When you save iOS credentials, the CLI:

Quando si salvano le credenziali iOS, il __CAPGO_KEEP_0__:
Legge i file del certificato e del profilo di provisioning
Li converte in codifica base64 ~/.capgo-credentials/credentials.json Li salva in .capgo-credentials.json (o con --local)
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

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	Sì (invio)

Cosa si conserva

Quando si salvano le credenziali Android, il CLI:

Legge i file del keystore e del servizio account JSON
Li converte in codifica base64
Li salva ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
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": "..."
  }
}

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

Variabili di ambiente (priorità più alta)
Credenziali salvate (~/.capgo-credentials/credentials.json, o locale) .capgo-credentials.json)
Nessuna credenziale (priorità più bassa)

Visualizzazione 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

Sicurezza del Local Storage

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

Non commitare mai le credenziali
Finestra del terminale
```
# Ignore the per-project credentials file (used with --local)
echo ".capgo-credentials.json" >> .gitignore
```
Il file globale vive nella directory home, fuori dal repository.
Separate Credenziali
- Utilizzare credenziali diverse per lo sviluppo locale vs CI/CD
- Rotare le credenziali regolarmente
- Non condividere le credenziali tra membri del team

Utilizzo di CI/CD

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

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

Al posto di codificare manualmente ogni file di credenziali in base64 (vedi di seguito), lascia build credentials manage generare 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 una 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.

Riferimento completo alle variabili di ambiente

Il CLI legge le seguenti variabili di ambiente per le 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	string di identificazione univoca	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

Android Credentials:

Variabile	Descrizione	Formato	Obbligatorio
`ANDROID_KEYSTORE_FILE`	File keystore per la firma APK/AAB	Base64	Sì (rilascio)
`KEYSTORE_KEY_ALIAS`	Cognome chiave all'interno del keystore	Stringa	Sì (rilascio)
`KEYSTORE_KEY_PASSWORD`	Password per il cognome 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	Sì (invio)

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

GitHub Esempio di azione di Capgo

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

Perché le variabili d'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
Rotazione facile e controllo degli accessi
Tracce di audit per l'utilizzo dei segreti

Rotazione delle credenziali

Rota regolarmente le tue credenziali:

iOSGenera nuovi certificati e API chiavi ogni anno
Android: Cambia le password del keystore ogni anno
Dopo le modifiche 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 ...

Risoluzione dei problemi

”Nessuna credenziale trovata”

Se il build dice che non sono state trovate credenziali:

Controlla se le credenziali sono salvate:
Finestra del terminale
```
bunx @capgo/cli@latest build credentials list
```

Salva le credenziali se mancanti:

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

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

Le credenziali non vengono utilizzate

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 risalva 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 Environment Variables

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

Estrai le tue attuali variabili di ambiente
Fenestra del terminale
```
echo $BUILD_CERTIFICATE_BASE64  # Verify they exist
```

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

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 credenziali esistenti salvate nel formato vecchio (singolo BUILD_PROVISION_PROFILE_BASE64), esegui:

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

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

Verifica la compilazione

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

Elimina le variabili di ambiente (facoltativo)
Finestra del terminale
```
unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64
```

Posizione del file

I credenziali sono memorizzate in un unico file JSON:

Globale (predefinito): ~/.capgo-credentials/credentials.json — condiviso tra tutti i tuoi progetti
Locale (con --local): .capgo-credentials.json all'interno della cartella del progetto — sovrascrive il file globale per quel progetto

The file viene creato automaticamente la prima volta che si salvano le credenziali. Aggiungi .capgo-credentials.json alle tue .gitignore così le credenziali per progetto non vengono mai commit.

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

Avete bisogno di aiuto?

Continuate da Gestione delle credenziali

Se stai utilizzando Gestione delle credenziali per pianificare l'automazione CI/CD, connettetela con Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, Integrazione CI/CD per il dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione di azioni per il dettaglio di implementazione in GitHub Integrazione di azioni.