Integración CI/CD
Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.
Integrar Capgo en tu pipeline de CI/CD te permite automatizar por completo el proceso de build y despliegue de actualizaciones en tu app. Aprovechando Capgo CLI y semantic-release, puedes garantizar despliegues consistentes y fiables, y permitir iterar rápidamente.
Beneficios de la integración CI/CD
Sección titulada “Beneficios de la integración CI/CD”-
Automatización: Se acabaron los pasos manuales y el margen de error humano. Puedes automatizar de principio a fin todo tu proceso de build, test y despliegue.
-
Consistencia: Cada despliegue sigue los mismos pasos, lo que garantiza un proceso predecible y repetible. Esto es especialmente útil cuando varios miembros del equipo contribuyen a code.
-
Iteraciones más rápidas: Con despliegues automatizados, puedes publicar actualizaciones con más frecuencia y confianza. Se acabó esperar QA manual o aprobaciones de release.
Capgo CLI
Sección titulada “Capgo CLI”El Capgo CLI es la clave para integrar Capgo en tu workflow de CI/CD. Proporciona comandos para publicar nuevas versiones de bundles, gestionar canales y más.
El comando más importante para la integración CI/CD es bundle upload:
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEYSi usas cifrado, debes proporcionarlo de una de estas formas:
Usando la ruta de un archivo de clave privada:
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATHUsando el contenido de la clave privada directamente (recomendado para CI/CD):
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENTUsando variables de entorno (mejor práctica para CI/CD):
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"Configurar variables de entorno para el cifrado
Sección titulada “Configuración de variables de entorno para el cifrado”En entornos CI/CD, se recomienda guardar tu clave privada como variable de entorno en lugar de como archivo. Así se configura:
-
Obtén el contenido de tu clave privada:
Ventana de terminal cat .capgo_key_v2 | pbcopyEsto copia el contenido de la clave a tu portapapeles.
-
Añádela a tu entorno CI/CD:
- Acciones de GitHub: Añade
CAPGO_PRIVATE_KEYa los secretos de tu repositorio - GitLab CI: Añádela como una variable enmascarada en la configuración de tu proyecto
- CircleCI: Añádela como una variable de entorno en la configuración de tu proyecto
- Jenkins: Añádela como una credencial de tipo secret text
- Acciones de GitHub: Añade
-
Úsala en tu pipeline:
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"
Nota: La --key-data-v2 el flag te permite pasar el contenido de la clave privada directamente como un string, lo que es ideal para variables de entorno en pipelines de CI/CD donde no quieres crear archivos temporales.
Este comando sube el build web actual al channel especificado. Normalmente lo ejecutarás como el último paso de tu pipeline de CI/CD, una vez que el build web haya finalizado con éxito.
Configura Capgo en tu pipeline de CI/CD
Sección titulada “Configuración de Capgo en tu pipeline de CI/CD”Aunque los pasos exactos variarán según la herramienta de CI/CD que elijas, el proceso general para integrar Capgo es el siguiente:
-
Generar una clave de API: Inicia sesión en el dashboard de Capgo y crea una nueva clave API. Esta clave se usará para autenticar el CLI en tu entorno de CI/CD. ¡Manténla en secreto y nunca la incluyas en tu repositorio!
-
Configurar el
bundle uploadcomando: Añade un paso a tu configuración de CI/CD que ejecute elbundle uploadcomando con los argumentos adecuados:\n Reemplazaupload.yml - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}Productioncon el channel al que quieras hacer deploy,${{ secrets.CAPGO_API_KEY }}con la variable de entorno que contiene tu clave de API, y añade--key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"si usas cifrado. -
Añade la
uploadpaso después de tu build web: Asegúrate de que eluploadpaso se ejecute después de que tu build web se haya completado correctamente. Esto garantiza que siempre estés desplegando tu última versión de code. Aquí tienes un ejemplo de configuración para GitHub Actions:upload.yml name: Deploy to Capgoon:push:branches: [main]jobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v6- uses: actions/setup-node@v6with:node-version: '24'- run: npm ci- run: npm run build- run: npm install -g @capgo/cli- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"
Gestión de versiones con Semantic-release
Sección titulada “Gestión de versiones con Semantic-release”La forma recomendada de gestionar las versiones con Capgo es establecer la versión en tu capacitor.config.ts archivo importándolo desde package.json:
import pkg from './package.json'
const config: CapacitorConfig = { // ... other config plugins: { CapacitorUpdater: { version: pkg.version, } }}Este enfoque te permite:
- Usar semantic-release (o cualquier otra herramienta) para actualizar el
package.jsonversión - Compilar tu app con la versión actualizada incluida automáticamente
- Subir el bundle con la versión correcta
Tu flujo de CI/CD se vería así:
- run: npm ci- run: npx semantic-release # Updates package.json version- run: npm run build # Builds with new version from capacitor.config- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}Aquí tienes un ejemplo de .releaserc archivo de configuración para semantic-release:
{ "branches": [ "main", { "name": "beta", "prerelease": true } ], "plugins": [ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/changelog", [ "@semantic-release/git", { "assets": ["CHANGELOG.md", "package.json"], "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" } ] ]}Esta configuración hace lo siguiente:
- Analiza los mensajes de commit para determinar el siguiente número de versión, siguiendo la especificación Conventional Commits.
- Genera las release notes basándose en los commits realizados desde la última versión.
- Actualiza el
CHANGELOG.mdarchivo con las nuevas release notes. - Actualiza el
package.jsonversión, que será detectada por tu capacitor.config. - Hace commit de los archivos actualizados
CHANGELOG.md,package.jsony de cualquier otro archivo modificado en el repositorio.
Asegúrate de ejecutar semantic-release antes de buildear tu app para que la nueva versión de package.json se incluya en tu build mediante la capacitor.config.
Auto-bump cuando la versión local ya está en Capgo
Sección titulada “Auto-bump cuando la versión local ya está en Capgo”Los nombres de bundle deben ser únicos (las versiones eliminadas siguen ocupando su nombre). Si CI sigue subiendo el mismo package.json versión, la subida falla. Es preferible hacer un bump package.json (por ejemplo, con semantic-release). Cuando no es práctico, deja que CLI elija el siguiente semver libre desde el bundle vinculado al canal, o la última versión remota de la app:
npx @capgo/cli@latest bundle upload --channel=production --auto-bumpnpx @capgo/cli@latest bundle upload --auto-bump majornpx @capgo/cli@latest bundle upload --auto-bump minor # default when the flag has no valuenpx @capgo/cli@latest bundle upload --auto-bump patch # alias: fixnpx @capgo/cli@latest bundle upload --auto-bump metadatanpx @capgo/cli@latest bundle upload --channel=production --auto-bump ai--auto-bump ai usa Capgo Cloudflare Workers AI para comparar los archivos locales del bundle con los archivos delta de la versión anterior de Capgo/canal, elige major | minor | patch | metadata, e imprime una razón breve. Sin una versión previa de Capgo, se omite la IA y el bump es parche.
No combines --auto-bump con --bundle / -b. Consulta la bundle upload referencia para ver la lista completa de opciones.
Solución de problemas
Sección titulada “Solución de problemas”Si tienes problemas con tu integración de CI/CD de Capgo, revisa lo siguiente:
-
clave de API: Asegúrate de que tu clave de API sea válida y tenga los permisos necesarios. Si usas una variable de entorno, verifica que esté bien configurada.
-
Versión de CLI: Asegúrate de usar la última versión de Capgo CLI. Las versiones antiguas pueden tener problemas de compatibilidad o carecer de ciertas funciones.
-
Artefactos de build: Confirma que tu web build genera los archivos de salida esperados. El Capgo CLI necesita un web build válido para crear un bundle.
-
Conectividad de red: Asegúrate de que tu entorno de CI/CD tenga acceso de red a los servidores de Capgo. Los firewalls o proxies pueden interferir con el
uploadcomando.
Si sigues teniendo problemas, contacta con el soporte de Capgo para recibir ayuda. Pueden ayudarte a diagnosticar cualquier problema con tu configuración específica.
Conclusión
Sección titulada “Conclusión”Integrar Capgo en tu pipeline CI/CD con una gestión de versiones adecuada puede simplificar enormemente tu flujo de trabajo de desarrollo. Al automatizar tus despliegues y el versionado mediante el enfoque capacitor.config, puedes publicar actualizaciones más rápido y con mayor confianza.
El enfoque recomendado de definir la versión en tu capacitor.config.ts archivo y usar semantic-release para actualizar package.json proporciona un proceso de despliegue robusto y fiable que te permite centrarte en crear grandes funcionalidades en lugar de preocuparte por los pasos manuales de lanzamiento.
Para más detalles sobre los comandos y opciones de Capgo CLI, consulta la referencia a CLI. Y para profundizar en la configuración de semantic-release, consulta la documentación de semantic-release.
¡Feliz despliegue!
Continuar desde la integración de CI/CD
Sección titulada “Continuar desde la integración de CI/CD”Si estás usando Integración CI/CD 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 con GitHub Actions para el detalle de implementación en la integración con GitHub Actions, y Integración con GitLab CI/CD para el detalle de implementación en la integración con GitLab CI/CD.