Gestionar credenciales

Administre sus credenciales de compilación de iOS y Android localmente para realizar compilaciones en la nube de manera conveniente.

Resumen

Capgo CLI almacena sus credenciales de compilación en su máquina — nunca en los servidores de Capgo . Por defecto, viven en un archivo global que se comparte en todos sus proyectos. Puede ~/.capgo-credentials/credentials.jsonpasarlos --local por proyecto en la configuración de su máquina local para que no se almacenen en los servidores de __CAPGO_KEEP_0__. en su máquina .capgo-credentials.json en lugar de eso. Cuando ejecutes una compilación, los credenciales guardadas se utilizan automáticamente y se envían de manera segura a Capgo, luego se eliminan después de que se complete la compilación.

Necesita Ayuda para Obtener Credenciales?

Si no tiene sus certificados y credenciales aún, consulte estos 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: Compilaciones de iOS Automáticas - Configuración completa de CI/CD

Android:

• Creando un Keystore - Guía paso a paso
• Guía de Certificados de Android - Tutorial detallado paso a paso
• Blog: Construcción automática de Android - Configuración completa de CI/CD

Garantía de Seguridad

Su credencial nunca se almacena permanentemente en los servidores Capgo:

• ✅ Se utiliza SOLO durante el proceso de construcción activo
• ✅ Se elimina automáticamente después de la finalización del proceso de construcción
• ✅ Las aplicaciones se envían directamente a App Store/Play Store - no almacenamos NADA
• ✅ Transmitido con seguridad sobre HTTPS

Comandos

Administrar credenciales de manera interactiva

La forma más rápida de trabajar con sus credenciales guardadas es el administrador interactivo. Abre una IU de terminal (igual que build init uses) donde puede navegar por lo que está almacenado, ver qué está configurado por aplicación 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 para administrar (te pide que elijas si se omite)
--platform <ios|android>	Plataforma para administrar (te pide si se omite)
--local	Utiliza el archivo por proyecto .capgo-credentials.json en lugar del archivo global

Preferir comandos de una sola ejecución, ejecutables desde la terminal? Utiliza los comandos individuales a continuación.

Guardar credenciales

Almacena tus credenciales de compilación localmente para su uso automático:

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

Actualizar credenciales

Actualice parcialmente las credenciales existentes sin reproporcionar todo:

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

El update El comando utiliza mezcla aditiva para perfiles de configuración — nuevos perfiles se fusionan con los existentes. Para reemplazar la configuración de perfiles completa en su lugar, agregue --overwrite-ios-provisioning-map.

Ejemplo — agregar 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 de actualización acepta las mismas opciones que save pero todas son opcionales — solo los campos que proporciona se actualizan.

List Credentials

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

bunx @capgo/cli@latest build credentials list

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

Borrar Credenciales

Eliminar 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

Convertir el formato de perfil único heredado al nuevo formato de múltiples objetivos:

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

El comando de migración detecta credenciales antiguas, las convierte a BUILD_PROVISION_PROFILE_BASE64 , y elimina las claves heredadas. Consulte CAPGO_IOS_PROVISIONING_MAPMigración desde Perfil Único para obtener más detalles. Almacenar credenciales de iOS

Título de la sección “Almacenar credenciales de iOS”

Note: __CAPGO_KEEP_0__

¿No tiene certificados de iOS todavía? Vea el guía de construcción de iOS para obtener instrucciones sobre la creación de certificados y perfiles de configuración.

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	Requerido
--certificate <path>	Ruta del archivo de certificado .p12	Sí (lanzamiento)
--p12-password <password>	Contraseña para el certificado .p12	Sí (lanzamiento)
--ios-provisioning-profile <mapping>	Asignación de perfil de provisión (, ). Repetible para aplicaciones multi-objetivo. Si solo hay un perfil y no hay prefijo de bundleId, __CAPGO_KEEP_0__ se infiere automáticamente desde el perfil.bundleId=path). Repeatable for multi-target apps. If only one profile and no bundleId prefix, CLI auto-infers from the profile.	Ruta del archivo de clave __CAPGO_KEEP_0__ .p8 de App Store Connect
--apple-key <path>	Path to App Store Connect API .p8 key	ID de clave de App Store Connect __CAPGO_KEEP_0__
--apple-key-id <id>	App Store Connect API Key ID	Requerido
--apple-issuer-id <id>	App Store Connect API Identificador del emisor (UUID)	Vea nota¹
--apple-team-id <id>	Identificador del equipo de App Store Connect	Sí
--apple-id <email>	Correo electrónico de Apple ID para subir contraseña de aplicación específica (alternativa a la API clave)	Vea nota²
--apple-app-specific-password <password>	Contraseña de aplicación específica (xxxx-xxxx-xxxx-xxxx)	Vea nota²
--apple-app-id <id>	ID numérico de aplicación de App Store Connect (por ejemplo, 1234567890)	Vea nota²
--ios-distribution <mode>	Modo de distribución: app_store (por defecto) o ad_hoc	No
--output-upload	Habilitar un enlace de descarga temporal de Capgo para el artefacto de compilación	No (por defecto: false)
--output-retention <seconds>	¿Cuánto tiempo mantener los resultados de compilación (por ejemplo 3600s)	No (por defecto: 3600s)
--skip-build-number-bump	Saltar el incremento automático del número de compilación	No

¹ Requisitos de la clave API de App Store Connect

• app_store modo (por defecto): Todas las tres opciones de clave API son requeridas a menos que se pase --output-upload o --skip-build-number-bump (lo que evita la necesidad de una API-impulsada presentación).
• ad_hoc modo: Estas opciones son no son necesarias — no se lleva a cabo ninguna presentación en la Tienda de Aplicaciones. Consulte Modo de Distribución Ad-Hoc para obtener más detalles.

² Contraseña específica de la aplicación (no recomendada)

Este método se desaconseja y se le aconseja en contra. Solo existe como un camino de compatibilidad para equipos que migran desde Ionic Appflow. Prefiere una clave de App Store Connect API (.p8) que es la opción recomendada, más capaz y más segura para CI/CD. Si debes usarla, todas las tres opciones (--apple-id, --apple-app-specific-password, y --apple-app-id) son necesarias juntas. El número numérico --apple-app-id (App Store Connect → tu aplicación → Información de la App → ID de Apple) permite que la carga se ejecute sin una solicitud interactiva de 2FA; con este método el número de compilación vuelve a un timestamp porque App Store Connect no se consulta.

¿Qué se Almacena

Cuando guardas credenciales de iOS, el CLI:

1. Lee los archivos de certificado y perfil de provisión
2. Los convierte a codificación base64
3. Los almacena en ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Almacena contraseñas e IDs como texto plano (solo 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

¿No tienes un keystore todavía? Consulte el guía de compilación de Android para obtener instrucciones sobre la creación de un keystore y la configuración de 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	Requerido
--keystore <path>	Ruta al archivo .keystore o .jks	Sí (lanzamiento)
--keystore-alias <alias>	Alias de clave en el keystore	Sí (lanzamiento)
--keystore-key-password <password>	Contraseña para el alias de la clave	Sí (lanzamiento)
--keystore-store-password <password>	Contraseña para el keystore	Sí (lanzamiento)
--play-config <path>	Ruta al archivo JSON de servicio de Play Store	Sí (envío)

¿Qué se almacena?

Cuando guardas credenciales de Android, el CLI:

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

La estructura del archivo almacenado:

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

Usando credenciales guardadas

Una vez que has guardado las credenciales, se utilizan automáticamente cuando construyes:

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

También puedes sobreescribir las credenciales guardadas utilizando 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ás alta)
2. Credenciales guardadas (~/.capgo-credentials/credentials.json, o local .capgo-credentials.json)
3. No hay credenciales (prioridad más baja)

Ver Credenciales Guardadas

Mostrar las credenciales que has guardado:

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.

Prácticas de seguridad recomendadas

Seguridad de almacenamiento local

1. Permisos de archivo

   # 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 cometas credenciales

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

   El archivo global vive en tu directorio de inicio, fuera del repositorio.

3. Credenciales Protegidas

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

Uso de CI/CD

prefiere variables de entorno sobre credenciales guardadas. Exporta un archivo listo para usar

(recomendado) .env __CAPGO_KEEP_0__

En lugar de codificar cada archivo de credenciales en base64 a mano (consulte abajo), permita build credentials manage que genere el archivo por usted:

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

Escribe un .env.capgo.<appId>.<platform> archivo (permisos 0600) que contiene cada credencial guardada como una variable de entorno — cada línea es un secreto para agregar a su proveedor de CI/CD. Por defecto, se combinan ambas plataformas; agregue --platform ios o --platform android para limitarlo a una.

Precaución

El archivo exportado contiene tus secretos de firma — agrégalo a .gitignore y nunca lo comites.

Referencia completa de variables de entorno

El CLI lee las siguientes variables de entorno para credenciales:

Datos de iOS:

Variable	Descripción	Formato	Requerido
BUILD_CERTIFICATE_BASE64	Certificado P12/PKCS12 para code de firma	Base64	Sí (lanzamiento)
CAPGO_IOS_PROVISIONING_MAP	Mapa JSON de IDs de paquetes a datos de perfil de provisión	Cadena JSON	Sí (lanzamiento)
P12_PASSWORD	Contraseña para el certificado P12	Texto plano	Opcional
APPLE_KEY_ID	ID de clave de App Store Connect para API	Cadena de texto (por ejemplo, “ABC1234567”)	Consulte la nota¹
APPLE_ISSUER_ID	App Store Connect API Identificador de emisor	UUID string	Vea nota¹
APPLE_KEY_CONTENT	App Store Connect API clave (.p8 archivo de contenido)	Base64	Vea nota¹
APP_STORE_CONNECT_TEAM_ID	Identificador del equipo de desarrollador de Apple	Cadena de texto (por ejemplo, “XXXXXXXXXX”)	Sí
CAPGO_IOS_DISTRIBUTION	Modo de distribución: app_store (por defecto) o ad_hoc	Cadena de texto	No

Credenciales de Android:

Variable	Descripción	Formato	Requerido
ANDROID_KEYSTORE_FILE	Archivo de keystore para firmar APK/AAB	Base64	Sí (lanzamiento)
KEYSTORE_KEY_ALIAS	Alias de clave dentro del keystore	Cadena de texto	Sí (lanzamiento)
KEYSTORE_KEY_PASSWORD	Contraseña para el alias de la clave	Texto plano	Sí*
KEYSTORE_STORE_PASSWORD	Contraseña para el archivo del keystore	Texto plano	Sí*
PLAY_CONFIG_JSON	JSON de cuenta de servicio de Google Play	Base64	Sí (envío)

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

GitHub Ejemplo de acciones

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

Preparando valores Base64

Para convertir tus archivos de credenciales a base64 para secretos 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 saltos de línea para crear una cadena de base64 de una sola línea, lo que facilita su almacenamiento como un secreto CI/CD.

Why las Variables de Entorno Son Más Seguras

Esta aproximación es más segura porque:

• Las secretas están gestionadas por tu plataforma CI/CD
• No hay archivos de credenciales en ejecutores
• Rotación y control de acceso fácil
• Historial de auditoría para el uso de secretas

Rotación de Credenciales

Rotar tus credenciales regularmente:

1. iOS: Genera nuevos certificados y API claves anualmente
2. Android: Cambie las contraseñas del keystore anualmente
3. Después de cambios en el equipo: Rotar cuando los miembros del equipo dejen

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 dice que no se encontraron credenciales:

1. Verificar si se han guardado las credenciales:

   bunx @capgo/cli@latest build credentials list

2. Guardar credenciales si faltan:

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

3. Verificar la existencia del archivo de credenciales:

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

“Denegado el acceso” al leer credenciales

Corregir permisos de archivo:

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

No se están utilizando las credenciales

Verificar que se especifique 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 dañadas:

# 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 estás utilizando variables de entorno, puedes migrar a credenciales guardadas:

1. Extrae tus variables de entorno actuales

   echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

2. Decodificar archivos base64 de vuelta a archivos originales (si es necesario)

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

3. Guardar utilizando el 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 existentes guardadas en el formato antiguo (simple BUILD_PROVISION_PROFILE_BASE64), ejecuta:

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

   Esta convierte la legado simple a un CAPGO_IOS_PROVISIONING_MAP y elimina los antiguos BUILD_PROVISION_PROFILE_BASE64 y APPLE_PROFILE_NAME llaves.

4. Prueba la compilación

   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 almacenan en un archivo JSON único:

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

El archivo se crea automáticamente la primera vez que guardas credenciales. Agrega .capgo-credentials.json a tu .gitignore así que las credenciales por proyecto nunca se comiten.

Pasos siguientes

• Empezar - Crea tu primera compilación
• Compilaciones de iOS - Configuración de compilación específica de iOS
• Compilaciones de Android - Configuración de compilación específica de Android
• Resolución de Problemas - Problemas comunes y soluciones

Necesita Ayuda?

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

Siga adelante desde Gestión de Credenciales

Si está utilizando Gestión de Credenciales planificar la automatización de CI/CD, conectarla con Capgo automatización de CI/CD para el flujo de trabajo del producto en Capgo automatización de CI/CD Capgo compilaciones nativas para el flujo de trabajo del producto en Capgo compilaciones nativas Capgo integraciones para el flujo de trabajo del producto en Capgo integraciones integración de CI/CD para el detalle de implementación en integración de CI/CD, y GitHub integración de acciones para el detalle de implementación en GitHub integración de acciones