Gestión de credenciales

Gestiona tus credenciales de build de iOS y Android localmente para facilitar los builds en la nube.

Resumen

Capgo CLI almacena tus credenciales de build en tu máquina — nunca en los servidores de Capgo. Por defecto, se guardan en un archivo global, ~/.capgo-credentials/credentials.jsoncompartido entre todos tus proyectos. Usa la opción --local para mantenerlas por proyecto en .capgo-credentials.json en su lugar. Al ejecutar un build, las credenciales guardadas se usan automáticamente y se envían de forma segura a Capgo, y se eliminan al terminar el build.

¿Necesitas ayuda para obtener credenciales?

Si aún no tienes tus certificados y credenciales, consulta estas guías completas:

iOS:

• Cómo obtener certificados de iOS - Guía paso a paso
• Guía de certificados de iOS - Tutorial detallado paso a paso
• Blog: Builds automáticos de iOS - Configuración completa de CI/CD

Android:

• Crear un Keystore - Guía paso a paso
• Guía de certificados de Android - Tutorial detallado paso a paso
• Blog: builds automáticos de Android - Configuración completa de CI/CD

Garantía de seguridad

Tus credenciales NUNCA se almacenan permanentemente en los servidores de Capgo:

• ✅ Se usan SOLO durante el proceso de build activo
• ✅ Se eliminan automáticamente al terminar el build
• ✅ Las apps se envían directamente a App Store/Play Store; no guardamos NADA
• ✅ Se transmiten de forma segura por HTTPS

Comandos

Gestión interactiva de credenciales

La forma más rápida de trabajar con tus credenciales guardadas es el gestor interactivo. Abre una TUI (la misma que build init utilizas) donde puedes explorar lo que hay guardado, ver qué está configurado por app y plataforma, exportar un archivo listo para CI/CD, .env o eliminar las credenciales de una plataforma:

bunx @capgo/cli@latest build credentials manage

Opción	Descripción
--appId <appId>	App a gestionar (te pedirá elegir si se omite)
--platform <ios|android>	Plataforma a gestionar (te pedirá elegir si se omite)
--local	Usa la configuración por proyecto .capgo-credentials.json en lugar del archivo global

¿Prefieres comandos únicos y ejecutables mediante scripts? Usa los siguientes comandos individuales.

Guardar credenciales

Guarda tus credenciales de build localmente para usarlas automáticamente:

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

Actualizar credenciales

Actualiza parcialmente las credenciales existentes sin tener que volver a introducirlo todo:

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

El update usos del comando merge aditivo para provisioning profiles — los nuevos perfiles se fusionan con los existentes. Para reemplazar todo el mapa de provisioning, añade --overwrite-ios-provisioning-map.

Ejemplo — añade un perfil de extensión a las credenciales existentes:

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

El comando update acepta las mismas opciones que save pero todas son opcionales — solo se actualizan los campos que proporciones.

Listar credenciales

Ver las credenciales guardadas actualmente (las contraseñas están enmascaradas):

bunx @capgo/cli@latest build credentials list

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

Limpiar credenciales

Elimina las credenciales guardadas de tu máquina local:

# 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

Migrar credenciales

Convierte el formato antiguo de perfil único al nuevo formato multi-target:

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

El comando migrate detecta las antiguas BUILD_PROVISION_PROFILE_BASE64 credenciales, las convierte y CAPGO_IOS_PROVISIONING_MAPelimina las claves heredadas. Ver Migración desde un perfil único para más detalles.

Guardar credenciales de iOS

Nota

¿Aún no tienes certificados de iOS? Consulta la Guía de iOS Builds para instrucciones sobre cómo crear certificados y provisioning profiles.

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

Opciones de iOS

Opción	Descripción	Obligatorio
--certificate <path>	Ruta al archivo de certificado .p12	Sí (release)
--p12-password <password>	Contraseña del certificado .p12	Sí (release)
--ios-provisioning-profile <mapping>	Mapeo de provisioning profiles (bundleId=path). Repetible para apps multi-target. Si solo hay un perfil y no hay prefijo bundleId, CLI lo infiere automáticamente del perfil.	Sí (release)
--apple-key <path>	Ruta de la clave API .p8 de App Store Connect	Ver nota¹
--apple-key-id <id>	Key ID de API de App Store Connect	Ver nota¹
--apple-issuer-id <id>	Issuer ID (UUID) de API de App Store Connect	Ver nota¹
--apple-team-id <id>	Team ID de App Store Connect	Sí
--apple-id <email>	Email de Apple ID para subir contraseñas de aplicación (alternativa a la clave API)	Ver nota²
--apple-app-specific-password <password>	Contraseña de aplicación (xxxx-xxxx-xxxx-xxxx)	Ver nota²
--apple-app-id <id>	ID numérico de la app en App Store Connect (ej. 1234567890)	Ver nota²
--ios-distribution <mode>	Modo de distribución: app_store (por defecto) o ad_hoc	No
--output-upload	Habilita un enlace de descarga de Capgo con tiempo limitado para el build artifact	No (por defecto: false)
--output-retention <seconds>	Retención de outputs del build (p. ej. 3600s)	No (por defecto: 3600s)
--skip-build-number-bump	Omitir el incremento automático del build number	No

¹ Requisitos de la API Key de App Store Connect

• app_store modo (por defecto): las tres opciones de la API key son obligatorias a menos que pases --output-upload o --skip-build-number-bump (lo que evita tener que realizar envíos mediante API).
• ad_hoc modo: Estas opciones son no obligatorias — no se realiza ninguna entrega a la App Store. Ver Modo de distribución Ad-Hoc para más detalles.

² Contraseña específica de la app (no recomendada)

Este método no se recomienda y se desaconseja su uso. Solo existe como vía de compatibilidad para equipos que migran desde Ionic Appflow. Es preferible usar una clave API de App Store Connect (.p8), que es la opción recomendada, más potente y segura para CI/CD. Si debes usarla, las tres opciones (--apple-id, --apple-app-specific-password, y --apple-app-id) son obligatorios en conjunto. El número --apple-app-id (App Store Connect → tu app → App Information → Apple ID) permite ejecutar el upload sin un prompt interactivo de 2FA; con este método, el build number pasa a ser un timestamp porque no se consulta App Store Connect.

Qué se almacena

Al guardar las credenciales de iOS, CLI:

1. Lee los archivos del certificado y del provisioning profile
2. Los convierte a codificación base64
3. Los guarda en ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Almacena contraseñas e IDs como texto plano (solo en archivos locales)

Estructura del archivo almacenado:

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

Guardar credenciales de Android

Nota

¿Aún no tienes un keystore? Consulta la Guía de Android Builds para ver cómo crear un keystore y configurar las credenciales de Play Store.

Ejemplo 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

Opciones de Android

Opción	Descripción	Obligatorio
--keystore <path>	Ruta al archivo .keystore o .jks	Sí (release)
--keystore-alias <alias>	Alias de la clave en el keystore	Sí (release)
--keystore-key-password <password>	Contraseña del alias de la clave	Sí (release)
--keystore-store-password <password>	Contraseña del keystore	Sí (release)
--play-config <path>	Ruta al JSON de la cuenta de servicio de Play Store	Yes (submission)

Qué se almacena

Al guardar las credenciales de Android, CLI:

1. Lee los archivos JSON de la service account y del keystore
2. Los convierte a codificación base64
3. Los guarda en ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Guarda contraseñas y alias en texto plano (solo archivos locales)

Estructura del archivo almacenado:

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

Uso de credenciales guardadas

Una vez guardadas, las credenciales se usarán automáticamente al hacer el build:

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

También puedes sobrescribir las credenciales guardadas usando variables de entorno:

# 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

Orden de precedencia:

1. Variables de entorno (prioridad máxima)
2. Credenciales guardadas (~/.capgo-credentials/credentials.json, o locales .capgo-credentials.json)
3. Sin credenciales (prioridad mínima)

Ver credenciales guardadas

Lista las credenciales que tienes guardadas:

bunx @capgo/cli@latest build credentials list

Ejemplo de salida:

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

Mejores prácticas de seguridad

Seguridad del Local Storage

1. Permisos de archivos

   # 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. Nunca subas credenciales al repo

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

   El archivo global está en tu home, fuera del repo.

3. Separa tus credenciales

   • Usa credenciales distintas para desarrollo local y CI/CD
   • Rota las credenciales con regularidad
   • No compartas credenciales entre miembros del equipo

Uso de CI/CD

Para entornos de CI/CD, es preferible usar variables de entorno en lugar de credenciales guardadas.

Exporta un listo para usar .env (recomendado)

En lugar de codificar cada archivo de credenciales en base64 manualmente (ver abajo), let build credentials manage generará el archivo por ti:

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

Escribe un .env.capgo.<appId>.<platform> archivo (permisos 0600) con cada credencial guardada como una variable de entorno; cada línea es un secreto para tu proveedor de CI/CD. Ambas plataformas se combinan por defecto; añade --platform ios o --platform android para limitarlo a una sola.

Precaución

El archivo exportado contiene tus secretos de firma; añádelo a .gitignore y nunca lo commitees.

Referencia completa de variables de entorno

CLI lee las siguientes variables de entorno para las credenciales:

Credenciales de iOS:

Variable	Descripción	Formato	Obligatorio
BUILD_CERTIFICATE_BASE64	Certificado P12/PKCS12 para la firma de code	Base64	Sí (release)
CAPGO_IOS_PROVISIONING_MAP	Mapa JSON de IDs de bundle a datos de provisioning profile	String JSON	Sí (release)
P12_PASSWORD	Contraseña del certificado P12	Texto plano	Opcional
APPLE_KEY_ID	Key ID de API de App Store Connect	String (ej. “ABC1234567”)	Ver nota¹
APPLE_ISSUER_ID	Issuer ID de API en App Store Connect	String UUID	Ver nota¹
APPLE_KEY_CONTENT	Clave API de App Store Connect (contenido del archivo .p8)	Base64	Ver nota¹
APP_STORE_CONNECT_TEAM_ID	ID de equipo de Apple Developer	String (ej. “XXXXXXXXXX”)	Sí
CAPGO_IOS_DISTRIBUTION	Modo de distribución: app_store (por defecto) o ad_hoc	String	No

Credenciales de Android:

Variable	Descripción	Formato	Obligatorio
ANDROID_KEYSTORE_FILE	Archivo keystore para firmar APK/AAB	Base64	Sí (release)
KEYSTORE_KEY_ALIAS	Alias de la clave en el keystore	String	Sí (release)
KEYSTORE_KEY_PASSWORD	Contraseña del alias de la clave	Texto plano	Sí*
KEYSTORE_STORE_PASSWORD	Contraseña del archivo keystore	Texto plano	Sí*
PLAY_CONFIG_JSON	JSON de la cuenta de servicio de Google Play	Base64	Yes (submission)

*Si solo se proporciona una contraseña, se usará para ambas KEYSTORE_KEY_PASSWORD y KEYSTORE_STORE_PASSWORD.

Ejemplo de GitHub Actions

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

Preparación de valores Base64

Para convertir tus archivos de credenciales a base64 para secretos de 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

Consejo

El tr -d '\n' elimina los saltos de línea para crear un string base64 de una sola línea, lo que facilita su almacenamiento como secreto de CI/CD.

Por qué las variables de entorno son más seguras

Este enfoque es más seguro porque:

• Los secrets se gestionan en tu plataforma CI/CD
• Sin archivos de credenciales en los runners
• Rotación y control de acceso sencillos
• Logs de auditoría para el uso de secrets

Rotación de credenciales

Rota tus credenciales periódicamente:

1. iOS: Genera nuevos certificados y llaves API cada año
2. Android: Cambia las contraseñas del keystore anualmente
3. Tras cambios en el equipo: Rotar al salir miembros del equipo

Actualizar credenciales guardadas:

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

Solución de problemas

“No se encontraron credenciales”

Si el build indica que no se hallaron credenciales:

1. Comprueba si las credenciales están guardadas:

   bunx @capgo/cli@latest build credentials list

2. Guardar credenciales si faltan:

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

3. Verificar que el archivo de credenciales exista:

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

“Permission denied” al leer las credenciales

Corregir los permisos del archivo:

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

Las credenciales no se están usando

Comprueba que se ha especificado la plataforma correcta:

# 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

Borrar y volver a guardar las credenciales

Si las credenciales parecen estar corruptas:

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

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

Migración desde variables de entorno

Si actualmente usas variables de entorno, puedes migrar a credenciales guardadas:

1. Extrae tus variables de entorno actuales

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. Decodifica archivos base64 a su formato original (si es necesario)

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

3. Guarda usando 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"

   Si tienes credenciales guardadas en el formato antiguo (single BUILD_PROVISION_PROFILE_BASE64), ejecuta:

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

   Esto convierte el perfil único antiguo en uno CAPGO_IOS_PROVISIONING_MAP y elimina las antiguas BUILD_PROVISION_PROFILE_BASE64 y APPLE_PROFILE_NAME keys.

4. Prueba el build

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

5. Eliminar variables de entorno (opcional)

   unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

Ubicación del archivo

Las credenciales se guardan en un único archivo JSON:

• Global (por defecto): ~/.capgo-credentials/credentials.json — compartido entre todos tus proyectos
• Local (con --local): .capgo-credentials.json en la raíz de tu proyecto — sobrescribe el archivo global para ese proyecto

El archivo se crea automáticamente la primera vez que guardas credenciales. Añade .capgo-credentials.json a tu .gitignore así las credenciales por proyecto nunca se suben al repositorio.

Próximos pasos

• Primeros pasos - Crea tu primer build
• Builds de iOS - Configuración de build para iOS
• Builds de Android - Configuración de build para Android
• Solución de problemas - Problemas comunes y soluciones

¿Necesitas ayuda?

• 📚 Guía de resolución de problemas
• 💬 Comunidad de Discord
• 📧 Email: support@capgo.app

Continuar desde Gestión de Credenciales

Si estás usando Gestión de credenciales para planificar la automatización de CI/CD, conéctalo con CI/CD de Capgo para el flujo de trabajo del producto en Capgo CI/CD, Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds, Integraciones de Capgo para el flujo de trabajo del producto en Capgo Integraciones, Integración CI/CD para los detalles de implementación de CI/CD Integration, y Integración con GitHub Actions para los detalles de implementación de GitHub Actions Integration.