Amministrazione delle credenziali

Copia un prompt di configurazione con le istruzioni di installazione e la guida markdown completa per questo plugin.

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

Panoramica

Capgo CLI conserva le tue credenziali di costruzione su il tuo computer – mai su Capgo’s server. Di default vivono in un file globale , condiviso da tutti i tuoi progetti. Passa ~/.capgo-credentials/credentials.jsonper mantenerle --local per mantenerle per-progetto in .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.

Comandi

Gestisci Credenziali Interattivamente

La modalità più veloce per lavorare con le tue credenziali salvate è il gestore interattivo. Si apre una finestra del terminale (lo stesso utilizzato) dove puoi esplorare cosa è memorizzato, vedere cosa è configurato per app e piattaforma, esportare un file pronto per la CI/CD, o cancellare le credenziali di una piattaforma: build init Finestra del terminale .env Copia negli appunti

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` Usa il file globale

Preferisci comandi scriptabili, eseguibili una sola volta? Utilizza i comandi individuali di seguito.

Salva Credenziali

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

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

Aggiorna le credenziali

Aggiorna le credenziali esistenti senza doverle fornire nuovamente per intero:

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

Il update comando utilizza l'aggiunta di merge per i profili di provisioning — i nuovi profili vengono uniti a quelli esistenti. Per sostituire l'intera mappa di provisioning al suo posto, 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"

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

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

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 credenziali

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

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

Il comando di migrazione rileva le credenziali vecchie, le converte nel nuovo formato e elimina le chiavi legacy. Vedi BUILD_PROVISION_PROFILE_BASE64 Migrazione da un Profilo Singolo CAPGO_IOS_PROVISIONING_MAPper maggiori informazioni. Salvataggio delle credenziali iOS Sezione intitolata “Salvataggio delle credenziali iOS”

Migrate Credentials

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	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-estende dal profilo.	Sì (rilascio)
`--apple-key <path>`	Percorso del file di chiave .p8 di App Store Connect API	Vedi nota¹
`--apple-key-id <id>`	App Store Connect API ID della chiave	Vedi nota¹
`--apple-issuer-id <id>`	App Store Connect API ID emittente (UUID)	Vedi nota¹
`--apple-team-id <id>`	ID della squadra di App Store Connect	Sì
`--apple-id <email>`	Indirizzo e-mail 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`	Enable a time-limited Capgo download link for the build artifact	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`	Svuota l'aumento automatico del numero di costruzione	No

Cosa viene memorizzato

Quando salvate le credenziali iOS, il CLI:

Legge i file del certificato e del profilo di provisioning
Li converte in codifica base64
Sicuramente li salva ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
Memorizza le password e gli ID in testo puro (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 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 al file JSON del servizio account Play Store	Sì (invio)

Cosa si conserva

Salvando le credenziali Android, il CLI:

Legge il keystore e i file JSON del servizio account
Li converte in codifica base64
Salva in ~/.capgo-credentials/credentials.json o .capgo-credentials.json con --local)
Salva le password e gli alias come testo piano (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:

Variabili di ambiente (priorità più alta)
Credenziali salvate (~/.capgo-credentials/credentials.jsono locale .capgo-credentials.json)
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 migliorative

Sicurezza del Storage locale

Permessi 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

Non commettere 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.
Credenziali separate
- Usa credenziali diverse per lo sviluppo locale vs CI/CD
- Rinnova 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 pronto all'uso `.env` (consigliato)

Invece 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 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 uno.

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ì (rilevazione)
`CAPGO_IOS_PROVISIONING_MAP`	Mappa JSON degli ID pacchetti a dati di profilo di provisioning	Stringa JSON	Sì (rilevazione)
`P12_PASSWORD`	Password per il certificato P12	Testo puro	Facoltativo
`APPLE_KEY_ID`	ID chiave di API di App Store Connect	String (ad esempio, “ABC1234567”)	Vedi nota¹
`APPLE_ISSUER_ID`	ID emittente App Store Connect API	Stringa UUID	Vedi nota¹
`APPLE_KEY_CONTENT`	Chiave App Store Connect API (.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	Richiesto
`ANDROID_KEYSTORE_FILE`	File keystore per la firma APK/AAB	Base64	Sì (rilevamento)
`KEYSTORE_KEY_ALIAS`	Alias della chiave all'interno del keystore	Stringa	Sì (rilevazione)
`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 account	Base64	Sì (invio)

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

GitHub Esempi di azione

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 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'utilizzo dei segreti

Rotazione delle Credenziali

Rotazione regolare delle tue credenziali:

iOS: Genera nuove certificazioni e API chiavi annualmente
Android: Modifica le password del keystore ogni anno
Dopo i cambiamenti della squadra: Ruota 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 ...

Risolvere i problemi

”Non sono stati trovati alcun credenziale”

Se il build indica che non sono stati trovati i credenziali:

Controlla se i 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)

“Rifiutato l'accesso” quando si legge il file delle credenziali

Risolvi i permessi del file:

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

Elimina e risave 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 alle credenziali salvate:

Estrai le tue attuali variabili di ambiente
Finestra 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 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 legato single-profile in un CAPGO_IOS_PROVISIONING_MAP e elimina gli old BUILD_PROVISION_PROFILE_BASE64 e APPLE_PROFILE_NAME chiavi.

Testa la build

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 (impostazione predefinita): ~/.capgo-credentials/credentials.json — condiviso con tutti i tuoi progetti
Locale (con --local): .capgo-credentials.json inserisci il file nella 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.

Passaggi successivi

Avvio - Crea il tuo primo build
Costruzioni iOS - Configurazione di costruzione specifica per iOS
Costruzione di Android - Configurazione di costruzione specifica per Android
Aiuto - Problemi comuni e soluzioni

Hai bisogno di aiuto?

📚 Comunità Discord
💬 📧 Email:
support@__CAPGO_KEEP_0__.app support@capgo.app

Sezione intitolata “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 Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni for the product workflow in Capgo Integrations, per il flusso di lavoro del prodotto in __CAPGO_KEEP_0__ Integrazioni, Integrazione CI/CD GitHub Actions Integration per i dettagli di implementazione in GitHub Azioni di integrazione.

Amministrazione delle credenziali

Panoramica

Comandi

Gestisci Credenziali Interattivamente

Salva Credenziali

Aggiorna le credenziali

Elenco delle credenziali

Cancella le credenziali

Migrare credenziali

Migrate Credentials

Esempio Completo

Opzioni iOS

Cosa viene memorizzato

Salvataggio delle credenziali Android

Esempio Completo

Opzioni Android

Cosa si conserva

Utilizzando le credenziali salvate

Visualizzazione delle Credenziali Salvate

Pratiche di sicurezza migliorative

Sicurezza del Storage locale

Utilizzo CI/CD

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

Riferimento completo alle variabili di ambiente

GitHub Esempi di azione

Preparazione dei valori Base64

Perché le Variabili di Ambiente sono più Sicure

Rotazione delle Credenziali

Risolvere i problemi

”Non sono stati trovati alcun credenziale”

“Rifiutato l'accesso” quando si legge il file delle credenziali

Le credenziali non vengono utilizzate

Elimina e risave le credenziali

Migrazione da Variabili di ambiente

Posizione del file

Passaggi successivi

Hai bisogno di aiuto?

Sezione intitolata “Continua da Gestione delle credenziali”

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