Zum Inhalt springen

Credentials verwalten

Verwalten Sie Ihre iOS- und Android-Build-Credentials lokal für bequeme Cloud-Builds.

Capgo CLI speichert deine Build-Credentials lokal auf deinem Rechner — niemals auf den Servern von Capgo. Standardmäßig liegen sie in einer globalen Datei, ~/.capgo-credentials/credentials.jsondie für alle deine Projekte gilt. Nutze --local um sie zu behalten pro Projekt in einem .capgo-credentials.json stattdessen. Wenn du einen Build startest, werden die gespeicherten Credentials automatisch verwendet, sicher an Capgo gesendet und nach Abschluss des Builds gelöscht.

Der schnellste Weg, mit deinen gespeicherten Credentials zu arbeiten, ist der interaktive Manager. Er öffnet eine TUI (dieselbe, die auch build init verwendet wird), in der du gespeicherte Daten durchsuchen, die Konfiguration pro App und Plattform einsehen, eine CI/CD-fähige .env Datei oder die Credentials einer Plattform löschen:

Terminalfenster
bunx @capgo/cli@latest build credentials manage
OptionBeschreibung
--appId <appId>App zum Verwalten (fragt nach, falls nicht angegeben)
--platform <ios|android>Plattform zum Verwalten (wird abgefragt, wenn weggelassen)
--localNutze die projektspezifischen .capgo-credentials.json anstelle der globalen Datei

Eher Einmalbefehle, die sich skripten lassen? Verwende die einzelnen Befehle unten.

Speichere deine Build-Credentials lokal für die automatische Verwendung:

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

Aktualisiere vorhandene Credentials teilweise, ohne alles erneut anzugeben:

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

Der update Befehl verwendet additiver Merge für Provisioning-Profile – neue Profile werden mit vorhandenen zusammengeführt. Um stattdessen die gesamte Provisioning-Map zu ersetzen, fügen Sie hinzu --overwrite-ios-provisioning-map.

Beispiel – ein Extension-Profil zu vorhandenen Credentials hinzufügen:

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

Der update-Befehl akzeptiert dieselben Optionen wie save aber alle sind optional – nur die Felder, die Sie angeben, werden aktualisiert.

Aktuell gespeicherte Credentials anzeigen (Passwörter werden maskiert):

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

Gespeicherte Credentials von deinem lokalen Rechner entfernen:

Terminalfenster
# 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

Das alte Single-Profile-Format in das neue Multi-Target-Format konvertieren:

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

Der migrate-Befehl erkennt alte BUILD_PROVISION_PROFILE_BASE64 Credentials, konvertiert sie zu CAPGO_IOS_PROVISIONING_MAPund entfernt die Legacy-Keys. Siehe Migration vom Single Profile für Details.

Terminalfenster
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"
OptionBeschreibungErforderlich
--certificate <path>Pfad zur .p12-ZertifikatsdateiJa (Release)
--p12-password <password>Passwort für das .p12-ZertifikatJa (Release)
--ios-provisioning-profile <mapping>Provisioning-Profil-Mapping (bundleId=path). Wiederholbar für Multi-Target-Apps. Bei nur einem Profil ohne bundleId-Präfix wird es von CLI automatisch aus dem Profil abgeleitet.Ja (Release)
--apple-key <path>Pfad zum App Store Connect API .p8-SchlüsselSiehe Hinweis¹
--apple-key-id <id>App Store Connect API Key IDSiehe Hinweis¹
--apple-issuer-id <id>App Store Connect API Issuer ID (UUID)Siehe Hinweis¹
--apple-team-id <id>App Store Connect Team-IDJa
--apple-id <email>Apple-ID-E-Mail für den Upload des app-spezifischen Passworts (Alternative zum API-Key)Siehe Hinweis²
--apple-app-specific-password <password>App-spezifisches Passwort (xxxx-xxxx-xxxx-xxxx)Siehe Hinweis²
--apple-app-id <id>Numerische App Store Connect App-ID (z. B. 1234567890)Siehe Hinweis²
--ios-distribution <mode>Distribution-Modus: app_store (Standard) oder ad_hocNein
--output-uploadZeitlich begrenzten Capgo-Download-Link für das Build-Artefakt aktivierenNein (Standard: false)
--output-retention <seconds>Wie lange Build-Outputs aufbewahrt werden (z. B. 3600s)Nein (Standard: 3600s)
--skip-build-number-bumpAutomatische Erhöhung der Build-Nummer überspringenNein

Beim Speichern der iOS-Credentials macht CLI Folgendes:

  1. Liest die Zertifikats- und Provisioning-Profile-Dateien ein
  2. Konvertiert sie in die Base64-Kodierung
  3. Speichert sie unter ~/.capgo-credentials/credentials.json (oder .capgo-credentials.json mit --local)
  4. Speichert Passwörter und IDs als Klartext (nur lokale Dateien)

Die gespeicherte Dateistruktur:

{
"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"
}
}
Terminalfenster
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
OptionBeschreibungErforderlich
--keystore <path>Pfad zur .keystore- oder .jks-DateiJa (Release)
--keystore-alias <alias>Key-Alias im KeystoreJa (Release)
--keystore-key-password <password>Passwort für den Key-AliasJa (Release)
--keystore-store-password <password>Passwort für den KeystoreJa (Release)
--play-config <path>Pfad zur Play Store Service-Account-JSONJa (Einreichung)

Wenn Sie Android-Credentials speichern, CLI:

  1. Liest die Keystore- und Service-Account-JSON-Dateien
  2. Konvertiert sie in die Base64-Kodierung
  3. Speichert sie unter ~/.capgo-credentials/credentials.json (oder .capgo-credentials.json mit --local)
  4. Speichert Passwörter und Alias als Klartext (nur lokale Dateien)

Die gespeicherte Dateistruktur:

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

Gespeicherte Zugangsdaten verwenden

Section titled “Using Saved Credentials”

Sobald Sie Zugangsdaten gespeichert haben, werden sie beim Build automatisch verwendet:

Terminalfenster
# Credentials automatically loaded from ~/.capgo-credentials/credentials.json
bunx @capgo/cli@latest build request com.example.app --platform ios

Sie können gespeicherte Zugangsdaten auch über Umgebungsvariablen überschreiben:

Terminalfenster
# 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

Prioritätsreihenfolge:

  1. Umgebungsvariablen (höchste Priorität)
  2. Gespeicherte Anmeldeinformationen (~/.capgo-credentials/credentials.json, oder lokal .capgo-credentials.json)
  3. Keine Anmeldeinformationen (niedrigste Priorität)

Gespeicherte Anmeldeinformationen anzeigen

Section titled “Viewing Saved Credentials”

Liste der gespeicherten Anmeldeinformationen:

Terminalfenster
bunx @capgo/cli@latest build credentials list

Beispielausgabe:

📋 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.
  1. Dateiberechtigungen

    Terminalfenster
    # 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. Credentials niemals committen

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

    Die globale Datei liegt in deinem Home-Verzeichnis, außerhalb des Repos.

  3. Credentials trennen

    • Nutze unterschiedliche Credentials für lokale Entwicklung vs. CI/CD
    • Credentials regelmäßig rotieren
    • Credentials nicht im Team teilen

Für CI/CD-Umgebungen sollten Umgebungsvariablen bevorzugt werden statt gespeicherter Credentials.

Anstatt jede Credential-Datei manuell base64 zu kodieren (siehe unten), lass build credentials manage die Datei für dich erstellen:

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

Es schreibt eine .env.capgo.<appId>.<platform> Datei (Berechtigungen 0600) mit allen gespeicherten Credentials als Umgebungsvariablen – jede Zeile entspricht einem Secret für deinen CI/CD-Provider. Standardmäßig werden beide Plattformen kombiniert; füge --platform ios oder --platform android hinzu, um es auf eine zu beschränken.

Das CLI liest die folgenden Umgebungsvariablen für die Credentials aus:

iOS-Anmeldedaten:

VariabelBeschreibungFormatErforderlich
BUILD_CERTIFICATE_BASE64P12/PKCS12-Zertifikat für das Signing mit codeBase64Ja (Release)
CAPGO_IOS_PROVISIONING_MAPJSON-Map von Bundle-IDs zu Provisioning-Profil-DatenJSON-StringJa (Release)
P12_PASSWORDPasswort für das P12-ZertifikatKlartextOptional
APPLE_KEY_IDApp Store Connect API Key IDString (z. B. „ABC1234567“)Siehe Hinweis¹
APPLE_ISSUER_IDApp Store Connect API Issuer IDUUID-StringSiehe Hinweis¹
APPLE_KEY_CONTENTApp Store Connect API Key (.p8-Dateiinhalt)Base64Siehe Hinweis¹
APP_STORE_CONNECT_TEAM_IDApple-Developer-Team-IDString (z. B. „XXXXXXXXXX“)Ja
CAPGO_IOS_DISTRIBUTIONDistribution-Modus: app_store (Standard) oder ad_hocStringNein

Android-Zugangsdaten:

VariabelBeschreibungFormatErforderlich
ANDROID_KEYSTORE_FILEKeystore-Datei zum Signieren von APK/AABBase64Ja (Release)
KEYSTORE_KEY_ALIASKey-Alias im KeystoreStringJa (Release)
KEYSTORE_KEY_PASSWORDPasswort für den Key-AliasKlartextJa*
KEYSTORE_STORE_PASSWORDPasswort für die Keystore-DateiKlartextJa*
PLAY_CONFIG_JSONGoogle Play Service Account JSONBase64Ja (Einreichung)

*Wird nur ein Passwort angegeben, wird dieses für beide verwendet KEYSTORE_KEY_PASSWORD und KEYSTORE_STORE_PASSWORD.

.github/workflows/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 }}

Um deine Credential-Dateien für CI/CD-Secrets in Base64 umzuwandeln:

Terminalfenster
# 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

Dieser Ansatz ist sicherer, weil:

  • Secrets werden von deiner CI/CD-Plattform verwaltet
  • Keine Credential-Dateien auf den Runnern
  • Einfache Rotation und Zugriffskontrolle
  • Audit-Logs für die Nutzung von Secrets

Rotiere deine Credentials regelmäßig:

  1. iOS: Generiere jährlich neue Zertifikate und API Keys
  2. Android: Ändere jährlich die Keystore-Passwörter
  3. Nach Team-Änderungen: Rotieren, wenn Teammitglieder das Team verlassen

Gespeicherte Credentials aktualisieren:

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

Falls der Build meldet, dass keine Credentials gefunden wurden:

  1. Prüfen, ob die Credentials gespeichert sind:

    Terminalfenster
    bunx @capgo/cli@latest build credentials list
  2. Credentials speichern, falls nicht vorhanden:

    Terminalfenster
    bunx @capgo/cli@latest build credentials save --platform ios ...
  3. Prüfen, ob die Credentials-Datei existiert:

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

Dateiberechtigungen korrigieren:

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

Stellen Sie sicher, dass die richtige Plattform angegeben ist:

Terminalfenster
# 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

Falls die Credentials beschädigt zu sein scheinen:

Terminalfenster
# Clear all credentials
bunx @capgo/cli@latest build credentials clear
# Save again
bunx @capgo/cli@latest build credentials save --platform ios ...

Wenn Sie derzeit Umgebungsvariablen verwenden, können Sie zu gespeicherten Anmeldeinformationen migrieren:

  1. Aktuelle Umgebungsvariablen extrahieren

    Terminalfenster
    echo $BUILD_CERTIFICATE_BASE64 # Verify they exist
  2. Base64-Dateien zurück in die Originaldateien dekodieren (falls nötig)

    Terminalfenster
    echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
    echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision
  3. Mit CLI speichern

    Terminalfenster
    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"

    Falls du vorhandene Credentials im alten Format gespeichert hast (einzelne BUILD_PROVISION_PROFILE_BASE64), führe aus:

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

    Dies wandelt das Legacy-Einzelprofil in ein CAPGO_IOS_PROVISIONING_MAP um und entfernt die alten BUILD_PROVISION_PROFILE_BASE64 und APPLE_PROFILE_NAME Keys.

  4. Build testen

    Terminalfenster
    bunx @capgo/cli@latest build request com.example.app --platform ios
  5. Umgebungsvariablen entfernen (optional)

    Terminalfenster
    unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

Credentials werden in einer einzigen JSON-Datei gespeichert:

  • Global (Standard): ~/.capgo-credentials/credentials.json — gilt für alle deine Projekte
  • Lokal (mit --local): .capgo-credentials.json in deinem Projekt-Root — überschreibt die globale Datei für dieses Projekt

Die Datei wird automatisch erstellt, wenn du zum ersten Mal Credentials speicherst. Füge .capgo-credentials.json in deine .gitignore so werden projektbezogene Credentials niemals committet.

Wenn du es nutzt Credentials verwalten um CI/CD-Automatisierung zu planen, verbinde es mit Capgo CI/CD für den Produkt-Workflow in Capgo CI/CD, Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds, Capgo Integrationen für den Produkt-Workflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in der CI/CD-Integration und GitHub Actions-Integration für die Implementierungsdetails in der GitHub Actions-Integration.