Managing Credentials

Manage your iOS and Android build credentials locally for convenient cloud builds.

Overview

Capgo CLI allows you to save build credentials locally on your machine in the .capgo-credentials folder. When you run a build, these credentials are automatically used and sent securely to Capgo’s build servers.

Need Help Getting Credentials?

If you don’t have your certificates and credentials yet, check these comprehensive guides:

iOS:

• How to Get iOS Certificates - Step-by-step guide
• iOS Certificates Guide - Detailed step-by-step tutorial
• Blog: Automatic iOS Builds - Complete CI/CD setup

Android:

• Creating a Keystore - Step-by-step guide
• Android Certificates Guide - Detailed step-by-step tutorial
• Blog: Automatic Android Builds - Complete CI/CD setup

Security Guarantee

Your credentials are NEVER stored permanently on Capgo servers:

• ✅ Used ONLY during the active build process
• ✅ Automatically deleted after build completion
• ✅ Maximum retention: 24 hours (even if build fails)
• ✅ Apps are sent directly to App Store/Play Store - we store NOTHING
• ✅ Transmitted securely over HTTPS

Commands

Save Credentials

Store your build credentials locally for automatic use:

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

Update Credentials

Partially update existing credentials without re-providing everything:

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

The update command uses additive merge for provisioning profiles — new profiles are merged with existing ones. To replace the entire provisioning map instead, add --overwrite-ios-provisioning-map.

Example — add an extension profile to existing credentials:

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

The update command accepts the same options as save but all are optional — only the fields you provide are updated.

List Credentials

View currently saved credentials (passwords are masked):

npx @capgo/cli build credentials list

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

Clear Credentials

Remove saved credentials from your local machine:

# 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

Migrate Credentials

Convert legacy single-profile format to the new multi-target format:

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

The migrate command detects old BUILD_PROVISION_PROFILE_BASE64 credentials, converts them to CAPGO_IOS_PROVISIONING_MAP, and removes the legacy keys. See Migration from Single Profile for details.

Saving iOS Credentials

Note

Don’t have iOS certificates yet? See the iOS Builds guide for instructions on creating certificates and provisioning profiles.

Complete Example

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"

iOS Options

Option	Description	Required
--certificate <path>	Path to .p12 certificate file	Yes (release)
--p12-password <password>	Password for the .p12 certificate	Yes (release)
--ios-provisioning-profile <mapping>	Provisioning profile mapping (bundleId=path). Repeatable for multi-target apps. If only one profile and no bundleId prefix, CLI auto-infers from the profile.	Yes (release)
--apple-key <path>	Path to App Store Connect API .p8 key	See note¹
--apple-key-id <id>	App Store Connect API Key ID	See note¹
--apple-issuer-id <id>	App Store Connect API Issuer ID (UUID)	See note¹
--apple-team-id <id>	App Store Connect Team ID	Yes
--ios-distribution <mode>	Distribution mode: app_store (default) or ad_hoc	No
--output-upload	Enable a time-limited Capgo download link for the build artifact	No (default: false)
--output-retention <seconds>	How long to keep build outputs (e.g. 3600s)	No (default: 3600s)
--skip-build-number-bump	Skip automatic build-number increment	No

¹ App Store Connect API Key Requirements

• app_store mode (default): All three API key options are required unless you pass --output-upload or --skip-build-number-bump (which bypass the need for API-driven submission).
• ad_hoc mode: These options are not required — no App Store submission takes place. See Ad-Hoc Distribution Mode for details.

What Gets Stored

When you save iOS credentials, the CLI:

1. Reads the certificate and provisioning profile files
2. Converts them to base64 encoding
3. Saves the credentials to the .capgo-credentials folder
4. Stores passwords and IDs as plain text (local files only)

The stored file structure:

{
  "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"
  }
}

Saving Android Credentials

Note

Don’t have a keystore yet? See the Android Builds guide for instructions on creating a keystore and setting up Play Store credentials.

Complete Example

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

Android Options

Option	Description	Required
--keystore <path>	Path to .keystore or .jks file	Yes (release)
--keystore-alias <alias>	Key alias in the keystore	Yes (release)
--keystore-key-password <password>	Password for the key alias	Yes (release)
--keystore-store-password <password>	Password for the keystore	Yes (release)
--play-config <path>	Path to Play Store service account JSON	Yes (submission)

What Gets Stored

When you save Android credentials, the CLI:

1. Reads the keystore and service account JSON files
2. Converts them to base64 encoding
3. Saves the credentials to the .capgo-credentials folder
4. Stores passwords and alias as plain text (local files only)

The stored file structure:

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

Using Saved Credentials

Once you’ve saved credentials, they’re automatically used when you build:

# Credentials automatically loaded from .capgo-credentials folder
npx @capgo/cli build com.example.app --platform ios

You can also override saved credentials using environment variables:

# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
npx @capgo/cli build com.example.app --platform ios

Precedence order:

1. Environment variables (highest priority)
2. Saved credentials in .capgo-credentials folder
3. No credentials (lowest priority)

Viewing Saved Credentials

List what credentials you have saved:

npx @capgo/cli build credentials list

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

Security Best Practices

Local Storage Security

1. File Permissions

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

2. Never Commit Credentials

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

3. Separate Credentials

   • Use different credentials for local development vs CI/CD
   • Rotate credentials regularly
   • Don’t share credentials between team members

CI/CD Usage

For CI/CD environments, prefer environment variables over saved credentials.

Complete Environment Variables Reference

The CLI reads the following environment variables for credentials:

iOS Credentials:

Variable	Description	Format	Required
BUILD_CERTIFICATE_BASE64	P12/PKCS12 certificate for code signing	Base64	Yes (release)
CAPGO_IOS_PROVISIONING_MAP	JSON map of bundle IDs to provisioning profile data	JSON string	Yes (release)
P12_PASSWORD	Password for the P12 certificate	Plain text	Optional
APPLE_KEY_ID	App Store Connect API Key ID	String (e.g., “ABC1234567”)	See note¹
APPLE_ISSUER_ID	App Store Connect API Issuer ID	UUID string	See note¹
APPLE_KEY_CONTENT	App Store Connect API key (.p8 file content)	Base64	See note¹
APP_STORE_CONNECT_TEAM_ID	Apple Developer Team ID	String (e.g., “XXXXXXXXXX”)	Yes
CAPGO_IOS_DISTRIBUTION	Distribution mode: app_store (default) or ad_hoc	String	No

Android Credentials:

Variable	Description	Format	Required
ANDROID_KEYSTORE_FILE	Keystore file for signing APK/AAB	Base64	Yes (release)
KEYSTORE_KEY_ALIAS	Key alias within the keystore	String	Yes (release)
KEYSTORE_KEY_PASSWORD	Password for the key alias	Plain text	Yes*
KEYSTORE_STORE_PASSWORD	Password for the keystore file	Plain text	Yes*
PLAY_CONFIG_JSON	Google Play service account JSON	Base64	Yes (submission)

*If only one password is provided, it will be used for both KEYSTORE_KEY_PASSWORD and KEYSTORE_STORE_PASSWORD.

GitHub Actions Example

.github/workflows/build.yml

name: Cloud Build

on:
  push:
    branches: [main]

jobs:
  build-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - 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@v4
      - 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 }}

Preparing Base64 Values

To convert your credential files to base64 for CI/CD secrets:

# 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

Astuce

The tr -d '\n' removes newlines to create a single-line base64 string, which is easier to store as a CI/CD secret.

Why Environment Variables Are More Secure

This approach is more secure because:

• Secrets are managed by your CI/CD platform
• No credential files on runners
• Easy rotation and access control
• Audit trails for secret usage

Credential Rotation

Regularly rotate your credentials:

1. iOS: Generate new certificates and API keys yearly
2. Android: Change keystore passwords annually
3. After team changes: Rotate when team members leave

Update saved credentials:

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

Troubleshooting

”No credentials found”

If the build says no credentials were found:

1. Check if credentials are saved:

   npx @capgo/cli build credentials list

2. Save credentials if missing:

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

3. Verify credentials folder exists:

   ls -la .capgo-credentials/

“Permission denied” when reading credentials

Fix file permissions:

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

Credentials not being used

Check that the correct platform is specified:

# 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

Clear and re-save credentials

If credentials seem corrupted:

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

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

Migration from Environment Variables

If you’re currently using environment variables, you can migrate to saved credentials:

1. Extract your current environment variables

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. Decode base64 files back to original files (if needed)

   echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
   echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

3. Save using the 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"

   If you have existing credentials saved in the old format (single BUILD_PROVISION_PROFILE_BASE64), run:

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

   This converts the legacy single-profile to a CAPGO_IOS_PROVISIONING_MAP and removes the old BUILD_PROVISION_PROFILE_BASE64 and APPLE_PROFILE_NAME keys.

4. Test the build

   npx @capgo/cli build com.example.app --platform ios

5. Remove environment variables (optional)

   unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

File Location

Credentials are stored in the .capgo-credentials folder:

• macOS/Linux: .capgo-credentials/ (in your project root or home directory)
• Windows: .capgo-credentials\ (in your project root or home directory)

The folder is automatically created when you save credentials for the first time.

Next Steps

• Getting Started - Create your first build
• iOS Builds - iOS-specific build configuration
• Android Builds - Android-specific build configuration
• Troubleshooting - Common issues and solutions

Need Help?

• 📚 Troubleshooting guide
• 💬 Discord community
• 📧 Email: support@capgo.app