Saltar al contenido

Integración CI/CD

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.

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

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:

Ventana de terminal
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY

Si usas cifrado, debes proporcionarlo de una de estas formas:

Usando la ruta de un archivo de clave privada:

Ventana de terminal
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATH

Usando el contenido de la clave privada directamente (recomendado para CI/CD):

Ventana de terminal
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENT

Usando variables de entorno (mejor práctica para CI/CD):

Ventana de terminal
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"

En entornos CI/CD, se recomienda guardar tu clave privada como variable de entorno en lugar de como archivo. Así se configura:

  1. Obtén el contenido de tu clave privada:

    Ventana de terminal
    cat .capgo_key_v2 | pbcopy

    Esto copia el contenido de la clave a tu portapapeles.

  2. Añádela a tu entorno CI/CD:

    • Acciones de GitHub: Añade CAPGO_PRIVATE_KEY a 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
  3. Ú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.

Aunque los pasos exactos variarán según la herramienta de CI/CD que elijas, el proceso general para integrar Capgo es el siguiente:

  1. 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!

  2. Configurar el bundle upload comando: Añade un paso a tu configuración de CI/CD que ejecute el bundle upload comando con los argumentos adecuados:

    upload.yml
    - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}
    \n Reemplaza Production con 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.

  3. Añade la upload paso después de tu build web: Asegúrate de que el upload paso 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 Capgo
    on:
    push:
    branches: [main]
    jobs:
    deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-node@v6
    with:
    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 }}"

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:

  1. Usar semantic-release (o cualquier otra herramienta) para actualizar el package.json versión
  2. Compilar tu app con la versión actualizada incluida automáticamente
  3. 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:

  1. Analiza los mensajes de commit para determinar el siguiente número de versión, siguiendo la especificación Conventional Commits.
  2. Genera las release notes basándose en los commits realizados desde la última versión.
  3. Actualiza el CHANGELOG.md archivo con las nuevas release notes.
  4. Actualiza el package.json versión, que será detectada por tu capacitor.config.
  5. 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:

Ventana de terminal
npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @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.

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 upload comando.

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.

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!

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.