Integración CI/CD

Integrating Capgo into your CI/CD pipeline allows you to fully automate the process of building and deploying updates to your app. By leveraging the Capgo CLI and semantic-release, you can ensure consistent, reliable deployments and enable rapid iteration.

Beneficios de la Integración de CI/CD

• Automatización: No más pasos manuales ni espacio para errores humanos. Tu proceso de construcción, prueba y despliegue completo puede automatizarse de principio a fin.

• Consistencia: Every deployment follows the same set of steps, ensuring a predictable and repeatable process. This is especially valuable when you have multiple team members contributing code.

• Iteraciones más rápidas: Con despliegues automatizados, puedes enviar actualizaciones con mayor frecuencia y con confianza. No más espera por pruebas manuales o aprobaciones de lanzamiento.

Capgo CLI

La Capgo CLI es la clave para integrar Capgo en tu flujo de trabajo CI/CD. Proporciona comandos para enviar nuevas versiones de paquetes, 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_KEY

Si utilizas cifrado, debes proporcionarlo de una de las siguientes maneras:

Usando la ruta del 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 (buena 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 cifrado

Para entornos de CI/CD, se recomienda almacenar tu clave privada como una variable de entorno en lugar de un archivo. Aquí está cómo configurarlo:

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

   cat .capgo_key_v2 | pbcopy

   Esto copia el contenido de la clave a tu portapapeles.

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

   • GitHub Acciones: Agrega CAPGO_PRIVATE_KEY a tus secretos de repositorio
   • GitLab CI: Agregalo como una variable oculta en tus ajustes de proyecto
   • CircleCI: Agregalo como una variable de entorno en tus ajustes de proyecto
   • Jenkins: Agregalo como un credencial de texto secreto

3. Usalo 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 La bandera permite pasar el contenido de la clave privada directamente como una cadena, lo que la hace perfecta para variables de entorno en pipelines CI/CD donde no deseas crear archivos temporales.

Este comando sube la compilación web actual al canal especificado. Por lo general, ejecutarás este comando como el último paso en tu pipeline CI/CD, después de que la compilación web haya completado con éxito.

Configuración de Capgo en tu Pipeline CI/CD

Mientras que los pasos exactos variarán dependiendo de la herramienta de CI/CD que elijas, el proceso general para integrar Capgo se parece a esto:

1. Genera una clave API: Inicia sesión en la consola de Capgo y crea una nueva clave API. Esta clave se utilizará para autenticar el CLI en tu entorno CI/CD. Manténla en secreto y no la comitas a tu repositorio!

2. Configura el comando bundle upload commandAgregar un paso a la configuración de CI/CD que ejecuta 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 por el canal al que deseas desplegar, ${{ secrets.CAPGO_API_KEY }} por la variable de entorno que contiene tu API clave, y agrega --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" si estás utilizando cifrado.

3. Agrega el upload paso después de tu compilación web: Asegúrate de que el upload paso se ejecute después de que tu compilación web haya finalizado con éxito. Esto garantiza que siempre estás desplegando tu última code.\n Aquí 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 manejar la versión con Capgo es establecer la versión en su archivo importándola desde capacitor.config.ts Copiar al portapapeles package.json:

import pkg from './package.json'

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

Este enfoque te permite:

1. actualice automáticamente con semantic-release (o cualquier otra herramienta) el package.json version
2. Construye tu aplicación con la versión actualizada incluida automáticamente
3. Tu flujo de trabajo de CI/CD sería como este:

Su flujo de trabajo de CI/CD serí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 }}

Gestión de versiones con semantic-release .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 número de versión siguiente, siguiendo la especificación de Conventional Commits.
2. Genera notas de lanzamiento basadas en los commits desde la última versión.
3. Actualiza el CHANGELOG.md archivo con las nuevas notas de lanzamiento.
4. Actualiza el package.json versión, que será capturada por tu capacitor.config.
5. archivo de configuración. CHANGELOG.md, package.jsony cualquier otro archivo modificado de regreso al repositorio.

Asegúrese de ejecutar semantic-release antes de construir su aplicación para que la versión actualizada se refleje. package.json se incluye en tu compilación a través de capacitor.config.

Auto-bump cuando la versión local ya está en Capgo

Nombres de paquetes deben ser únicos (las versiones eliminadas ocupan aún su nombre). Si CI sigue subiendo el mismo package.json La versión, la subida falla. Prefiere actualizar package.json (for example with semantic-release). When that is not practical, let the CLI pick the next free semver from the channel’s linked bundle, or else the latest remote app version:

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 archivos de paquete locales con los archivos delta de canal previos Capgo. major | minor | patch | metadataCon y imprima una breve razón. Sin una versión previa de Capgo, se salta el AI y el bump es no combinar.

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ --auto-bump con --bundle / -b. Consulte la bundle upload referencia para obtener la lista completa de opciones.

Troubleshooting

Si encuentra problemas con la integración de CI/CD de su Capgo, revise lo siguiente:

• API claveAsegúrese de que su clave API sea válida y tenga los permisos necesarios. Si utiliza una variable de entorno, verifique que esté configurada correctamente.

• versión de CLIAsegúrese de utilizar la última versión de los Capgo CLI. Las versiones antiguas pueden tener problemas de compatibilidad o faltar ciertas características.

• Artículos de compilaciónVerifique que su compilación web está generando los archivos de salida esperados. El Capgo CLI requiere una compilación web válida para crear un paquete.

• Conectividad de redVerifique que su entorno de CI/CD tenga acceso a Internet a los servidores Capgo. Problemas con firewalls o proxies pueden interferir ocasionalmente con el upload comando.

Si sigue teniendo problemas, contacte con el soporte de Capgo para obtener asistencia. Ellos pueden ayudar a depurar cualquier problema con su configuración específica.

Conclusión

Integrar Capgo en su pipeline de CI/CD con un manejo de versiones adecuado puede simplificar significativamente su flujo de trabajo de desarrollo. Al automatizar sus despliegues y versionar a través del enfoque capacitor.config, puede enviar actualizaciones más rápido y con más confianza.

El enfoque recomendado de establecer la versión en su capacitor.config.ts archivo y utilizar semantic-release para actualizar package.json proporciona un proceso de despliegue robusto y confiable que le permite enfocarse en crear características excelentes en lugar de preocuparse por los pasos de liberación manuales.

Para obtener más detalles sobre los comandos y opciones de Capgo CLI, consulte el CLI referencia. Y para una inmersión más profunda en la configuración de semantic-release, consulte los documentos de semantic-release.

¡Feliz despliegue!

Sigue adelante desde la Integración CI/CD

Si estás utilizando Integración CI/CD planificar la automatización de CI/CD, conectarla con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD, Capgo Construcción Nativa para el flujo de trabajo del producto en compilaciones nativas Capgo Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones GitHub Acciones de Integración para el detalle de implementación en GitHub Acciones de Integración, y Integración CI/CD de GitLab para el detalle de implementación en Integración CI/CD de GitLab.