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. Al usar Capgo CLI y semantic-release, garantizas despliegues consistentes y fiables para iterar con rapidez.

Beneficios de la integración CI/CD

• Automatización: Se acabaron los pasos manuales y el error humano. Puedes automatizar todo tu proceso de build, test y deployment de principio a fin.

• Consistencia: Cada deployment sigue los mismos pasos, garantizando un proceso predecible y repetible. Esto es clave cuando varios miembros del equipo contribuyen a code.

• Iteraciones más rápidas: Con deployments automatizados, puedes lanzar actualizaciones con más frecuencia y confianza. Olvídate de esperar por QA manual o aprobaciones de release.

Capgo CLI

El Capgo CLI es la clave para integrar Capgo en tu workflow de CI/CD. Ofrece comandos para subir nuevas versiones de bundles, gestionar channels 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_KEY

Si usas cifrado, puedes 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_PATH

Usando 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_CONTENT

Usando 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"

Configuración de variables de entorno para el cifrado

Para entornos de CI/CD, se recomienda guardar tu clave privada como una variable de entorno en lugar de un archivo. Así es como puedes configurarla:

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

   cat .capgo_key_v2 | pbcopy

   Esto copia el contenido de la clave al portapapeles.

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

   • Acciones de GitHub: Añade CAPGO_PRIVATE_KEY a los secrets de tu repositorio
   • GitLab CI: Añádela como una variable enmascarada en los ajustes de tu proyecto
   • CircleCI: Añádela como una variable de entorno en los ajustes 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: El --key-data-v2 flag permite pasar el contenido de la clave privada directamente como un string, 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, tras completar con éxito el build web.

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

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 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 ocurra después de que tu build web termine con éxito. Esto garantiza que siempre despliegues tu última code.\n\nAquí tienes un ejemplo de configuración para GitHub Actions:\n

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

Gestión de versiones con Semantic-release

La forma recomendada de gestionar el versionado con Capgo es definir la versión en tu capacitor.config.ts archivo importándola desde package.json:

import pkg from './package.json'

const config: CapacitorConfig = {
  // ... other config
  plugins: {
    CapacitorUpdater: {
      version: pkg.version,
    }
  }
}

Con este enfoque podrás:

1. Usar semantic-release (u otra herramienta) para actualizar la package.json versión
2. Buildear tu app con la nueva versión incluida automáticamente
3. Subir el bundle con la versión correcta

Tu workflow 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

Los nombres de los bundles deben ser únicos (las versiones eliminadas siguen ocupando su nombre). Si el CI sigue subiendo la misma package.json version, la subida falla. Es mejor aumentar la versión package.json (por ejemplo con semantic-release). Si esto no es práctico, deja que CLI elija el siguiente semver libre del bundle vinculado al canal, o bien la última versión remota de la app:

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 del bundle local con los archivos delta del canal o Capgo anterior, elegir major | minor | patch | metadata, e imprime un motivo breve. Al no haber una versión Capgo previa, se omite la IA y el bump es patch.

No combines --auto-bump con --bundle / -b. Consulta la bundle upload referencia para ver la lista completa de opciones.

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 del CLI de Capgo. Las versiones antiguas pueden tener problemas de compatibilidad o carecer de funciones.

• Artefactos de build: Confirma que tu web build genera los archivos de salida esperados. El CLI de Capgo necesita un web build válido para crear un bundle.

• Conectividad de red: Comprueba que tu entorno de CI/CD tenga acceso de red a los servidores de Capgo. Los firewalls o proxies pueden interferir con la upload comando.

Si sigues teniendo problemas, contacta con el soporte de Capgo para recibir ayuda. Pueden ayudarte a solucionar cualquier problema con tu configuración específica.

Conclusión

Integrar Capgo en tu pipeline de CI/CD con una gestión de versiones adecuada puede agilizar enormemente tu flujo de trabajo. Al automatizar tus despliegues y el versionado mediante el enfoque capacitor.config, podrás lanzar actualizaciones más rápido y con mayor confianza.

El enfoque recomendado de establecer la versión en tu capacitor.config.ts archivo y usar semantic-release para actualizar package.json ofrece un proceso de despliegue robusto y confiable 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 de 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

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.