Gestionar credenciales

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

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 file, ~/.capgo-credentials/credentials.jsonCompartido en todos tus proyectos. --local por proyecto Overview en español .capgo-credentials.json en su lugar. 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 aún no tiene sus certificados y credenciales, 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:

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

Garantía de seguridad

Sus credenciales NO se almacenan permanentemente en los servidores de Capgo:

• ✅ Utilizado SOLO durante el proceso de construcción activo
• ✅ Automatically deleted after build completion
• ✅ Las aplicaciones se envían directamente a la Tienda de App/Play Store - no almacenamos NADA
• ✅ Se transmite de manera segura sobre HTTPS

Comandos

Gestionar credenciales de manera interactiva

La forma más rápida de trabajar con sus credenciales guardadas es el administrador interactivo. Abre una ventana de terminal (la misma que build init credenciales) donde puedes navegar por lo que está almacenado, ver qué está configurado por aplicación y plataforma, exportar un CI/CD listo para producción .env file, or delete a platform’s credentials:

bunx @capgo/cli@latest build credentials manage

Option	Descripción
--appId <appId>	Aplicación para gestionar (te pide que elijas si se omite)
--platform <ios|android>	Plataforma para gestionar (te pide si se omite)
--local	Utiliza el archivo por proyecto .capgo-credentials.json en lugar del archivo global

Preferir comandos scriptables y de una sola ejecución? Utiliza los comandos individuales debajo.

Guardar credenciales

Almacena tus credenciales de construcció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 tener que proporcionar todo de nuevo:

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

La update El comando utiliza la fusión aditiva para perfiles de configuración — los nuevos perfiles se fusionan con los existentes. Para reemplazar la totalidad del mapa de configuración 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 todos son opcionales — solo los campos que proporcionas se actualizan.

Lista de credenciales

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

Eliminar 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

Convirta el formato de perfil único legado al nuevo formato de múltiples objetivos:

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

La orden migrate detecta credenciales antiguas BUILD_PROVISION_PROFILE_BASE64 y elimina las llaves de legado. Consulte CAPGO_IOS_PROVISIONING_MAPMigración desde un perfil único para obtener más detalles. Almacenando credenciales de iOS

Sección titulada “Almacenando credenciales de iOS”

Nota

¿No tienes certificados de iOS todavía? Ver el guía de construcción de iOS Instrucciones para crear 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 al archivo de certificado .p12	Sí (lanzamiento)
--p12-password <password>	Contraseña para el certificado .p12	Sí (lanzamiento)
--ios-provisioning-profile <mapping>	Mapeo de perfil de provisionamiento (bundleId=pathSi solo hay un perfil y no hay un prefijo bundleId, CLI se infiere automáticamente desde el perfil.	Sí (lanzamiento)
--apple-key <path>	Ruta al archivo de clave .p8 de App Store Connect API	Ver nota¹
--apple-key-id <id>	ID de clave de App Store Connect API	Ver nota¹
--apple-issuer-id <id>	App Store Connect API Identificador de emisor (UUID)	Ver nota¹
--apple-team-id <id>	App Store Connect Identificador de equipo	Sí
--apple-id <email>	Correo electrónico de ID de Apple para subir contraseña de aplicación (alternativa al API clave)	Ver nota²
--apple-app-specific-password <password>	Contraseña de aplicación específica (xxxx-xxxx-xxxx-xxxx)	Ver nota²
--apple-app-id <id>	Numeric App Store Connect app ID (e.g. 1234567890)	Ver 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>	How long to keep build outputs (e.g. 3600s)	No (por defecto: 3600s)
--skip-build-number-bump	Skip automatic build-number increment	No

¹ Requisitos de la clave de App Store Connect API

• app_store modo (por defecto): Todas las tres opciones de clave API son requerido a menos que pases --output-upload o --skip-build-number-bump (excluyendo la necesidad de una API-impulsada presentación).
• ad_hoc modeno son requeridas no es requerido — no App Store submission takes place. See para obtener más detalles. para más detalles.

o (que evita la necesidad de __CAPGO_KEEP_0__-driven envío).

Este método se desaconseja y se le aconseja evitar. Solo existe como camino de compatibilidad para equipos que migran desde Ionic Appflow. Prefiera una clave API de App Store Connect (.p8), que es la opción recomendada, más capaz y más segura para CI/CD. Si debe usarlo, todas las tres opciones (--apple-id, --apple-app-specific-passwordy --apple-app-idLos números son requeridos conjuntamente. --apple-app-id (App Store Connect → your app → App Information → Apple ID) lets the upload run without an interactive 2FA prompt; with this method the build number falls back to a timestamp because App Store Connect is not queried.

Sección titulada “¿Qué se Almacena”

Cuando guardes las credenciales de iOS, el CLI:

1. Lee los archivos de certificado y perfil de provisión
2. Convierte a codificación base64
3. Almacena en ellos ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local)
4. Almacena contraseñas e IDs como texto plano (solo archivos locales)

La estructura de archivo almacenada:

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

Almacenando credenciales de Android

Nota

No tienes un keystore todavía? Consulte el Guía de construcción de Android Instrucciones para crear un keystore y configurar credenciales de Google Play.

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

Option	Opción	Descripción
--keystore <path>	Ruta al archivo .keystore o .jks	Sí (versión de lanzamiento)
--keystore-alias <alias>	Alias de clave en el keystore	Sí (lanzamiento)
--keystore-key-password <password>	Contraseña para la clave de alias	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	Yes (submission)

¿Qué se almacena?

Al guardar credenciales de Android, el CLI:

1. Lee los archivos keystore y JSON de servicio
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 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 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 puede 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 locales) .capgo-credentials.json)
3. Sin credenciales (prioridad más baja)

Ver credenciales guardadas

Muestra las credenciales que has guardado:

bunx @capgo/cli@latest build credentials list

__CAPGO_KEEP_0__

📋 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

Seguridad en 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. No cometer credenciales

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

   La archivo global se encuentra en tu directorio de inicio, fuera del repositorio.

3. Credenciales separadas

   • Usar credenciales diferentes para el desarrollo local vs CI/CD
   • Rotar credenciales con regularidad
   • No compartir credenciales entre miembros del equipo

Uso de CI/CD

Para entornos de CI/CD, prefiere variables de entorno antes que credenciales guardadas.

Exportar listo para usar .env (recomendado)

En lugar de codificar manualmente cada archivo de credenciales en base64 (consulte abajo) build credentials manage genera el archivo para ti:

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

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

Advertencia

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

Referencia completa de variables de entorno

El CLI lee las siguientes variables de entorno para credenciales:

Credenciales de iOS:

Variable	Descripción	Formato	Requerido
BUILD_CERTIFICATE_BASE64	Certificado P12/PKCS12 para la firma de code	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”)	Ver nota¹
APPLE_ISSUER_ID	App Store Connect API Identificador de emisor	cadena de UUID	Ver nota¹
APPLE_KEY_CONTENT	App Store Connect API clave (contenido del archivo .p8)	Base64	Ver nota¹
APP_STORE_CONNECT_TEAM_ID	ID de equipo de desarrollador de Apple	cadena (por ejemplo, ‘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	Requerido
ANDROID_KEYSTORE_FILE	Archivo de keystore para firmar APK/AAB	Base64	Sí (versión de lanzamiento)
KEYSTORE_KEY_ALIAS	Alias de clave dentro del keystore	String	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	Yes (submission)

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

GitHub Acciones de ejemplo

.github/flujos de trabajo/compilar.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 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 saltos de línea para crear una cadena base64 de una sola línea, lo que facilita su almacenamiento como secreto CI/CD.

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

Esta aproximación es más segura porque:

• Los secretos están gestionados por tu plataforma CI/CD
• No hay archivos de credenciales en ejecutores
• Control de acceso y rotación fáciles
• Registros de auditoría para el uso de secretos

Rotación de credenciales

Rota tus credenciales regularmente:

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

: Actualiza 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 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 existe:

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

“Denegado de permiso” 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 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 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. Descodifica 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. Guarda 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 (singular) BUILD_PROVISION_PROFILE_BASE64Corre:

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

   Esto convierte la legado de perfil único a un CAPGO_IOS_PROVISIONING_MAP y elimina el viejo BUILD_PROVISION_PROFILE_BASE64 y APPLE_PROFILE_NAME keys.

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

Los credenciales se almacenan en un archivo JSON único.

• (por defecto): (default): ~/.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 Las credenciales por proyecto nunca se cometen.

Pasos siguientes

• Getting Started - Crea tu primer build
• iOS Builds - Configuración de compilación específica de iOS
• Compilaciones de Android - Configuración de construcción específica de Android
• Solución de problemas Configuración de construcción específica de Android

¿Necesita ayuda?

• 📚 Sección titulada “¿Necesita ayuda?”
• 💬 Guía de solución de problemas
• 📧 Email: soporte@capgo.app

support@__CAPGO_KEEP_0__.app

Si estás utilizando Administración de credenciales planificar la automatización de CI/CD, conectarla con Capgo CI/CD para el flujo de trabajo del producto en Capgo 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 los detalles de implementación en Integración de CI/CD, y GitHub integración de acciones para los detalles de implementación en GitHub integración de acciones.