Intégration CI/CD

L'intégration de Capgo dans votre pipeline CI/CD vous permet d'automatiser entièrement le processus de build et de déploiement des mises à jour de votre application. En exploitant Capgo CLI et semantic-release, vous garantissez des déploiements cohérents et fiables tout en permettant une itération rapide.

Avantages de l'intégration CI/CD

• Automatisation: Plus aucune étape manuelle ni risque d'erreur humaine. L'intégralité de votre processus de build, de test et de déploiement peut être automatisée de bout en bout.

• Cohérence : Chaque déploiement suit le même ensemble d'étapes, garantissant un processus prévisible et reproductible. C'est particulièrement utile lorsque plusieurs membres de l'équipe contribuent à code.

• Itérations plus rapidesAvec les déploiements automatisés, vous pouvez livrer des mises à jour plus fréquemment et en toute confiance. Plus besoin d'attendre une QA manuelle ou des approbations de release.

Capgo CLI

Le Capgo CLI est la clé pour intégrer Capgo à votre workflow CI/CD. Il fournit des commandes pour envoyer de nouvelles versions de bundles, gérer les canaux, et bien plus encore.

La commande la plus importante pour l'intégration CI/CD est bundle upload:

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

Si vous utilisez le chiffrement, vous devez le fournir de l'une des manières suivantes :

En utilisant le chemin d'un fichier de clé privée :

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

Utilisation directe du contenu de la clé privée (recommandé pour la CI/CD) :

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

En utilisant des variables d'environnement (meilleure pratique pour la CI/CD) :

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

Configuration des variables d'environnement pour le chiffrement

Pour les environnements CI/CD, il est recommandé de stocker votre clé privée sous forme de variable d'environnement plutôt que dans un fichier. Voici comment la configurer :

1. Récupérez le contenu de votre clé privée :

   cat .capgo_key_v2 | pbcopy

   Ceci copie le contenu de la clé dans votre presse-papiers.

2. Ajoutez-l’à votre environnement CI/CD :

   • GitHub Actions GitHub: Ajouter CAPGO_PRIVATE_KEY aux secrets de votre dépôt
   • GitLab CI: Ajoutez-la comme variable masquée dans les paramètres de votre projet
   • CircleCI: Ajoutez-la comme variable d'environnement dans les paramètres de votre projet
   • Jenkins: Ajoutez-la comme un secret text credential

3. Utilisez-la dans votre pipeline :

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

Remarque: Le --key-data-v2 flag vous permet de passer le contenu de la clé privée directement sous forme de chaîne, ce qui est idéal pour les variables d'environnement dans les pipelines CI/CD où vous ne souhaitez pas créer de fichiers temporaires.

Cette commande effectue l'upload du build web actuel vers le canal spécifié. Vous l'exécuterez généralement comme dernière étape de votre pipeline CI/CD, une fois votre build web terminé avec succès.

Configuration de Capgo dans votre pipeline CI/CD

Bien que les étapes exactes varient selon l'outil de CI/CD choisi, le processus général pour intégrer Capgo est le suivant :

1. Générer une clé API: Connectez-vous au dashboard Capgo et créez une nouvelle clé API. Cette clé servira à authentifier le CLI dans votre environnement CI/CD. Gardez-la secrète et ne la commitez jamais dans votre dépôt !

2. Configurer la bundle upload commande: Ajoutez une étape à votre configuration CI/CD qui exécute la bundle upload commande avec les arguments appropriés :

   upload.yml

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

   \n Remplacez Production par le canal que vous souhaitez déployer, ${{ secrets.CAPGO_API_KEY }} avec la variable d'environnement contenant votre clé API, et ajoutez --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" si vous utilisez le chiffrement.

3. Ajoutez l'étape upload après votre build web: Assurez-vous que l'étape upload intervient après la réussite de votre build web. Cela garantit que vous déployez toujours votre dernier code.\nVoici un exemple de configuration pour 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 }}"

Gestion des versions avec Semantic-release

La méthode recommandée pour gérer le versioning avec Capgo est de définir la version dans votre capacitor.config.ts fichier en l'important depuis package.json:

import pkg from './package.json'

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

Cette approche vous permet de :

1. Utiliser semantic-release (ou tout autre outil) pour mettre à jour la package.json version
2. Compiler votre app avec la nouvelle version incluse automatiquement
3. Envoyer le bundle avec la version correcte

Votre workflow CI/CD ressemblerait à ceci :

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

Voici un exemple de .releaserc fichier de configuration pour 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}"
      }
    ]
  ]
}

Cette configuration effectue les actions suivantes :

1. Analyse les messages de commit pour déterminer le numéro de la prochaine version, selon la spec Conventional Commits.
2. Génère les notes de release basées sur les commits depuis la dernière release.
3. Met à jour le CHANGELOG.md fichier avec les nouvelles notes de release.
4. Met à jour le package.json version, qui sera récupérée par votre capacitor.config.
5. Effectue le commit de la CHANGELOG.md, package.json, ainsi que tous les autres fichiers modifiés vers le dépôt.

Assurez-vous d'exécuter semantic-release avant de compiler votre application pour que la version mise à jour de package.json soit incluse dans votre build via le capacitor.config.

Incrémentation automatique si la version locale est déjà sur Capgo

Les noms de bundle doivent être uniques (les versions supprimées occupent toujours leur nom). Si la CI continue d'envoyer la même package.json version, l'upload échoue. Privilégiez l'incrémentation du package.json (par exemple avec semantic-release). Si cela n'est pas pratique, laissez CLI choisir le prochain semver disponible du bundle lié au canal, ou sinon la dernière version de l'app à distance :

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 utilise Capgo Cloudflare Workers AI pour comparer les fichiers du bundle local avec les fichiers delta du précédent Capgo/canal, choisit major | minor | patch | metadataet affiche une courte raison. Sans version Capgo précédente, l'IA est ignorée et l'incrémentation se fait en patch.

Ne combinez pas --auto-bump par --bundle / -b. Voir la bundle upload référence pour la liste complète des options.

Troubleshooting

Si vous rencontrez des problèmes avec votre intégration CI/CD Capgo, voici quelques points à vérifier :

• Clé API: Assurez-vous que votre clé API est valide et possède les permissions nécessaires. Si vous utilisez une variable d'environnement, vérifiez qu'elle est correctement configurée.

• Version CLI: Assurez-vous d'utiliser la dernière version du CLI Capgo. Les versions plus anciennes peuvent présenter des problèmes de compatibilité ou manquer de certaines fonctionnalités.

• Artefacts de build: Confirmez que votre build web génère bien les fichiers de sortie attendus. Le CLI Capgo nécessite un build web valide pour créer un bundle.

• Connectivité réseau: Vérifiez que votre environnement CI/CD a bien accès aux serveurs Capgo. Des problèmes de pare-feu ou de proxy peuvent parfois interférer avec le upload commande.

Si vous rencontrez toujours des difficultés, contactez le support de Capgo pour obtenir de l'aide. Ils pourront vous aider à résoudre tout problème lié à votre configuration spécifique.

Conclusion

L'intégration de Capgo dans votre pipeline CI/CD avec une gestion de version appropriée peut considérablement optimiser votre workflow de développement. En automatisant vos déploiements et votre versionnage via l'approche capacitor.config, vous pouvez livrer des mises à jour plus rapidement et avec plus de confiance.

L'approche recommandée consistant à définir la version dans votre fichier capacitor.config.ts et à utiliser semantic-release pour mettre à jour package.json offre un processus de déploiement robuste et fiable qui vous permet de vous concentrer sur la création de fonctionnalités plutôt que sur les étapes de release manuelles.

Pour plus de détails sur les commandes et options CLI de Capgo, consultez la référence CLI. Et pour approfondir la configuration de semantic-release, consultez la documentation de semantic-release.

Bon déploiement !

Continuer après l'intégration CI/CD

Si vous utilisez Intégration CI/CD pour planifier l'automatisation CI/CD, et le connecter avec CI/CD Capgo pour le workflow produit dans le CI/CD de Capgo, Capgo Native Build pour le workflow produit dans les Native Builds de Capgo, Intégrations Capgo pour le workflow produit dans les intégrations de Capgo, Intégration GitHub Actions pour les détails d'implémentation de l'intégration GitHub Actions, et Intégration GitLab CI/CD pour les détails d'implémentation de l'intégration GitLab CI/CD.