Administrar Credenciales

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

Resumen

Capgo CLI le permite guardar credenciales de compilación localmente en su máquina en el .capgo-credentials carpeta. Cuando realice una compilación, estas credenciales se utilizan automáticamente y se envían de manera segura a los servidores de compilación de Capgo.

¿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 paso a paso detallado
• Blog: Construcción Automática 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: Construcción automática de Android - Configuración completa de CI/CD

Garantía de seguridad

Sus credenciales NO se almacenan permanentemente en los servidores Capgo:

• ✅ Se utiliza ÚNICAMENTE durante el proceso de construcción activo
• ✅ Se elimina automáticamente después de la finalización del proceso de construcción
• ✅ Retención máxima: 24 horas (incluso si el proceso de construcción falla)
• ✅ Las aplicaciones se envían directamente a App Store/Play Store - no almacenamos NADA
• ✅ Transmitido con seguridad sobre HTTPS

Comandos

Guardar credenciales

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

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

Actualizar credenciales

Actualiza las credenciales existentes de manera parcial sin tener que proporcionar todo de nuevo:

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

La update El comando utiliza la fusión aditiva para los perfiles de provisión — los nuevos perfiles se fusionan con los existentes. Para reemplazar la totalidad de la mapa de perfiles en lugar de eso, agrega Ejemplo — agregar un perfil de extensión a credenciales existentes: Ventana de terminal --overwrite-ios-provisioning-map.

Copiar a portapapeles

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

Lista de credenciales save Sección titulada “Lista de credenciales”

Ejemplo — agregar un perfil de extensión a credenciales existentes: __CAPGO_KEEP_0__

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

npx @capgo/cli build credentials list

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

Borrar credenciales

Eliminar credenciales guardadas de tu máquina local:

# 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

Migrar credenciales

Convertir formato de legado de un solo perfil al nuevo formato de múltiples objetivos:

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

El comando de migración detecta credenciales antiguas, las convierte a BUILD_PROVISION_PROFILE_BASE64 y elimina las claves de legado. Consulte CAPGO_IOS_PROVISIONING_MAPMigración desde un perfil único para obtener más detalles. Guardar credenciales de iOS

Sección titulada “Guardar credenciales de iOS”

¿No tiene certificados de iOS todavía?

Consulte el Guía de compilación de iOS para obtener instrucciones sobre la creación de certificados y perfiles de configuración.

Ejemplo completo

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"

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 provisión (bundleId=path). Repetible para aplicaciones multi-objetivo. Si solo hay un perfil y no hay prefijo de bundleId, CLI se infiere automáticamente desde el perfil.	Sí (lanzamiento)
--apple-key <path>	Ruta de la 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>	ID emisor de App Store Connect API (UUID)	Ver nota¹
--apple-team-id <id>	ID del equipo de App Store Connect	Sí
--ios-distribution <mode>	Modo de distribución: app_store (predeterminado) o ad_hoc	No
--output-upload	Habilitar un enlace de descarga temporal de Capgo para el artefacto de compilación	No (predeterminado: false)
--output-retention <seconds>	¿Cuánto tiempo mantener los resultados de compilación (por ejemplo, 3600s)	No (predeterminado: 3600s)
--skip-build-number-bump	Saltar el incremento automático del número de compilación	No

¹ Requisitos de la Clave de App Store Connect API

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

¿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. Guarda las credenciales en el .capgo-credentials carpeta
4. Almacena contraseñas e IDs como texto plano (solo archivos locales)

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

Guardando 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

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

Opción	Descripción	Requerido
--keystore <path>	Ruta al archivo .keystore o .jks	Sí (lanzamiento)
--keystore-alias <alias>	Alias de la 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 de keystore y JSON de servicio
2. Los convierte a codificación base64
3. Guarda las credenciales en el .capgo-credentials carpeta
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 hayas guardado credenciales, se utilizan automáticamente cuando construyes:

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

También puedes sobreescribir credenciales guardadas utilizando variables de entorno:

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

Orden de precedencia:

1. Variables de entorno (prioridad más alta)
2. Credenciales guardadas en .capgo-credentials carpeta
3. No se han proporcionado credenciales (prioridad más baja)

Ver credenciales guardadas

Muestra las credenciales que has guardado:

npx @capgo/cli 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/

🔒 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 recomendadas de seguridad

Seguridad de almacenamiento local

1. Permisos de archivo

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

2. Nunca cometas credenciales

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

3. Credenciales separadas

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

Uso de CI/CD

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

Referencia completa de variables de entorno

La CLI lee las siguientes variables de entorno para credenciales:

Credenciales de iOS:

Variable	Descripción	Formato	Requerido
BUILD_CERTIFICATE_BASE64	Certificado P12/PKCS12 para firmar 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	Clave de App Store Connect API	Cadena de texto (por ejemplo, “ABC1234567”)	Véase nota¹
APPLE_ISSUER_ID	Emisor de App Store Connect API	cadena de identificador único	Vea la nota¹
APPLE_KEY_CONTENT	clave de App Store Connect API (contenido del archivo .p8)	Base64	Vea la 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	Cadena	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 clave	Texto plano	Sí*
KEYSTORE_STORE_PASSWORD	Contraseña para el archivo del keystore	Texto plano	Sí*
PLAY_CONFIG_JSON	JSON de la cuenta de servicios 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/trabajos/flujos/trabajo.yml

name: Cloud Build

on:
  push:
    branches: [main]

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

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

Consejo

El tr -d '\n' elimina saltos de línea para crear una cadena de base64 de una sola línea, lo que es más fácil de almacenar como un secreto de CI/CD.

¿Por qué 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áciles
• Huellas de auditoría para el uso de secretas

Rotación de credenciales

Rota 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
npx @capgo/cli build credentials save --platform ios --certificate ./new-cert.p12 ...

Solución de problemas

”No credentials found”

Si el build dice que no se encontraron credenciales:

1. Verifique si las credenciales están guardadas:

   npx @capgo/cli build credentials list

2. Guardar credenciales si faltan:

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

3. Verificar que existe la carpeta de credenciales:

   ls -la .capgo-credentials/

“Denegado por permiso” al leer credenciales

Corregir permisos de archivo:

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

No se están utilizando las credenciales

Verifique que se especifique la plataforma correcta:

# 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

Borrar y volver a guardar las credenciales

Si las credenciales parecen estar dañadas:

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

# Save again
npx @capgo/cli 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

   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"

   Si tiene credenciales existentes guardadas en el formato antiguo (simple BUILD_PROVISION_PROFILE_BASE64Ejecuta:

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

   Esto convierte la legado simple-perfil a un CAPGO_IOS_PROVISIONING_MAP y elimina los BUILD_PROVISION_PROFILE_BASE64 y APPLE_PROFILE_NAME llaves.

4. Prueba la compilación

   npx @capgo/cli build 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 el .capgo-credentials carpeta:

• macOS/Linux: .capgo-credentials/ (en el directorio raíz de tu proyecto o directorio de inicio)
• Windows: .capgo-credentials\ (en el directorio raíz de tu proyecto o directorio de inicio)

La carpeta se crea automáticamente cuando guardas las credenciales por primera vez.

Pasos siguientes

• Empezar - Crea tu primer build
• 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 y soluciones comunes

Necesitas ayuda?

• 📚 Guía de solución de problemas
• 💬 comunidad de Discord
• 📧 Correo electrónico: soporte@capgo.app