GitHub Actions

Copiez un prompt de configuration avec les étapes d'installation et le guide Markdown complet pour ce plugin.

Automatisez vos builds iOS et Android directement à partir de votre GitHub repository. Avec un fichier de workflow unique et quelques secrets de repository, chaque push, balise ou déclencheur manuel peut produire des applications signées et prêtes à être stockées — sans qu'aucun membre de l'équipe n'ait besoin d'un Mac, d'Xcode ou d'Android Studio installés.

Ce Que Vous Obtenez

Lancements sans Contact

Marquez une version dans Git et vos binaires iOS et Android signés sont soumis automatiquement à TestFlight et Play Store.

Aucune Installation Locale

Les contributeurs sous Windows ou Linux peuvent déclencher les builds iOS. Aucun Xcode, aucun problème de provisionnement, aucune certificat de signature partagé flottant sur les ordinateurs portables.

Secrets Étendus

Les informations de connexion vivent dans les secrets de GitHub repository, étendus à votre repository et visibles uniquement par le déclencheur de workflow. Facile à mettre à jour, facile à auditer.

Lancements Parallèles

Construirez iOS et Android en même temps avec un travail de matrice. Une mise en production typique se termine en moins de 10 minutes.

Prérequis

Avant de configurer le flux de travail, assurez-vous d'avoir :

Un compte Capgo avec une abonnement actif et un Capgo API clé
Votre application enregistrée sur Capgo (bunx @capgo/cli@latest app add si ce n'est pas le cas)
Les informations de build configurées localement avec bunx @capgo/cli@latest build init — voir Gestion des informations de connexion pour la procédure guidée du wizard
Une build locale réussie (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug — Le CI n'est pas le lieu pour déboguer votre première build
La GitHub CLI (gh) installé et authentifié (gh auth login)

Configuration

Le Capgo CLI peut exporter vos informations d'identification locales sous forme de fichier prêt à l'emploi. .env fichier. Associé à gh secret set -fCette commande transforme l'ensemble de la configuration CI/CD en trois commandes — pas de codage base64 manuel, pas de manipulation de JSON, pas de copie-coller de secrets.

Ajoutez votre clé Capgo API en tant que secret de dépôt

La clé API n'est pas partie de la base de données de crédentiels par application, ajoutez-la donc manuellement :
Fenêtre de terminal
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Générez la clé dans le tableau de bord Capgo avec l'envoi des permissions ou supérieures.
Exportez vos informations d'identification dans un .env fichier

Exécutez le gestionnaire interactif de mots de passe :
Fenêtre de terminal
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Dans la TUI, sélectionnez Exporter vers .envLe CLI écrit .env.capgo.<appId> dans votre répertoire actuel avec mode 0600 (seulement lisible par le propriétaire) — par exemple, .env.capgo.com.example.appLorsque les deux iOS et Android sont configurés, les secrets de tous les deux plateformes se trouvent dans le même fichier sous # === IOS === et # === ANDROID === les titres de section. Les noms de variables d'environnement iOS et Android sont disjointes, donc les combiner est sans conflit.

Passer --platform ios (ou --platform android) pour scoper le gestionnaire à une plateforme. L'export produit ensuite un fichier par plateforme comme .env.capgo.com.example.app.iosCela est utile lorsque les secrets iOS et Android vivent dans des dépôts ou des environnements différents.

Un certain nombre de paramètres de configuration (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) peuvent être stockés sous chaque plateforme de manière independante et peuvent s'être éloignés. Si le gestionnaire détecte des différences, il imprime les clés en conflit, demande une confirmation explicite avant d'écrire et insère la liste des conflits sous forme de commentaire en haut du fichier. Ré-exportez avec --platform si vous avez besoin de conserver les valeurs par plateforme.
Pousser le .env fichier vers GitHub Secrets d'actions

La commande lit un fichier dotenv et crée un secret de repository par ligne : gh secret set -f Fenêtre de terminal KEY=value Copier dans le presse-papier
C'est tout — tous les secrets dont votre workflow a besoin sont maintenant dans __CAPGO_KEEP_0__. Vérifiez avec
```
gh secret set -f .env.capgo.com.example.app
```
That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.
Fenêtre de terminal
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Ré-exportez à tout moment si vous devez faire pivoter les informations d'identification — le fichier n'est pas un artefact à long terme.
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Copier dans le presse-papier
Créez le fichier de workflow

Ajoutez .github/workflows/capgo-build.yml à votre dépôt. Choisissez l'un des trois modèles de déclencheur ci-dessous en fonction de la manière dont vous souhaitez déclencher les builds.

Ce qui se retrouve dans vos secrets

Pour référence, gh secret set -f créera ces secrets de dépôt (votre fichier YAML de workflow les référence par ces noms exacts) :

Plateforme	Secrets créés
iOS	`BUILD_CERTIFICATE_BASE64`, `P12_PASSWORD`, `CAPGO_IOS_PROVISIONING_MAP_BASE64`, `APPLE_KEY_ID`, `APPLE_ISSUER_ID`, `APPLE_KEY_CONTENT`, `APP_STORE_CONNECT_TEAM_ID`
Android	`ANDROID_KEYSTORE_FILE`, `KEYSTORE_KEY_ALIAS`, `KEYSTORE_KEY_PASSWORD`, `KEYSTORE_STORE_PASSWORD`, `PLAY_CONFIG_JSON`
(ajoutés manuellement)	`CAPGO_TOKEN`

Vous n'avez pas besoin de les retenir en mémoire — les exemples de workflow ci-dessous référencent déjà tous les éléments.

Exemples de workflow

Les trois exemples ci-dessous couvrent les modèles les plus courants. Ils utilisent tous la même forme : consultez le dépôt, installez les dépendances, construisez les actifs web, synchronisez avec le natif, puis appelez Capgo Build avec les variables d'environnement transmises.

1. Déclencheur manuel

Permet à tout utilisateur disposant d'accès en écriture de déclencher une construction depuis la Actions rubrique dans GitHub avec un menu déroulant de plateforme. Utile pour les constructions de test ad-hoc ou pour lancer une mise à jour à la demande.

name: Capgo Build (Manual)

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Platform to build'
        required: true
        default: 'android'
        type: choice
        options: [ios, android, both]
      mode:
        description: 'Build mode'
        required: true
        default: 'debug'
        type: choice
        options: [debug, release]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync

      - name: Trigger Capgo Build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ inputs.platform }} \
            --build-mode ${{ inputs.mode }}

Remplacer com.example.app avec votre ID d'application. Une fois commit, allez à Actions → Capgo Build (manuel) → Exécution de workflow pour le déclencher.

2. Lancement sur Tag

Construit et expédie les deux plateformes en parallèle chaque fois que vous poussez une étiquette de version comme v1.4.0C'est la configuration de production la plus courante — git tag v1.4.0 && git push --tags devient votre commande de lancement.

name: Capgo Build (Release)

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}

      - name: Build ${{ matrix.platform }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          # iOS
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          # Android
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode release

La matrice exécute iOS et Android en parallèle sur des exécutables séparés. Définir fail-fast: false signifie qu'une erreur de construction iOS ne sera pas annulée par la construction en cours d'Android (et vice versa) — utile lorsque l'une des plateformes a une question de signature transitoire.

3. Lancer le build en mode débogage lors de la mise en ligne principale

Permet de détecter les régressions de build natif en amont en produisant un build Android en mode débogage à chaque push vers mainCout peu élevé, feedback rapide, et vous pouvez ignorer l'upload vers la Play Store pour le conserver uniquement en tant que test de fumée.

name: Capgo Build (Main)

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'android/**'
      - 'ios/**'
      - 'package.json'
      - 'capacitor.config.*'

jobs:
  smoke-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync android

      - name: Smoke build (Android debug)
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform android \
            --build-mode debug \
            --no-playstore-upload \
            --output-upload

Le filtre s'assure que le flux de travail ne s'exécute pas sur les modifications uniquement documentaires. paths s'ignore la soumission de la Play Store (pas --no-playstore-upload nécessaire), et PLAY_CONFIG_JSON produit une URL de téléchargement pour le fichier APK résultant afin que vous puissiez l'installer sur un appareil de test. --output-upload Modèles courants

Section intitulée “Modèles courants”

Section intitulée “Ignorer la soumission de la Play Store / TestFlight”

; pour iOS, construire en mode ad-hoc avec --no-playstore-upload(ce qui ne soumet jamais à l'App Store). Combinez l'un ou l'autre avec --ios-distribution ad_hoc Les --output-upload pour obtenir une URL de téléchargement temporairement valide pour le binaire.

Lisez l'URL de sortie de la construction et le QR code

Passer --output-record <path> pour persister l'URL de l'artifact de construction et le QR code sur le disque lorsque la construction réussit, puis les lire à nouveau dans les étapes ultérieures avec build last-outputAucune récupération de journaux, aucune regex.

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform android --build-mode debug \
      --output-upload --output-retention 1d \
      --output-record /tmp/build.json

- name: Comment on PR with build URL
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    URL=$(bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl)
    if [ -n "$URL" ]; then
      gh pr comment ${{ github.event.pull_request.number }} \
        --body "Debug build ready: $URL"
    fi

--output-record /tmp/build.json écrit un enregistrement JSON (avec jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) et un PNG QR code à côté de /tmp/build.json.qr.png. build last-output lisez-le à nouveau :

--field outputUrl imprime uniquement l'URL de téléchargement (terminée par retour chariot ; sécurisée pour URL=$(...)).
--field qrCodePngPath imprime le chemin du PNG afin que vous puissiez le télécharger en tant qu'attache de PR.
--qr imprime le code ASCII QR — insérez-le à l'intérieur d'un code Markdown pour une scannabilité inline.

Ignorer l'incrémentation du numéro de build

Par défaut, chaque build de version augmente le numéro de build. Pour le fixer à une valeur que vous contrôlez (par exemple, la balise Git), passez --skip-build-number-bump:

- name: Set version from tag
  run: |
    VERSION="${GITHUB_REF#refs/tags/v}"
    # Update package.json or your version source here
    bun pm version "$VERSION" --no-git-tag-version

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform ios --build-mode release \
      --skip-build-number-bump

Cachez les dépendances

bun install est déjà suffisamment rapide pour que le cache de dépendances JS ne rapporte rarement, mais les dépendances natives de Capacitor (CocoaPods, Gradle) sont dignes d'être mises en cache pour les projets plus importants :

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

Résolution des problèmes

Cause probable	Le secret n'a pas été ajouté, ou le job n'a pas accès à celui-ci (vérifiez les protections d'environnement/branches)
`CAPGO_TOKEN is not set`	Erreurs de credenciaux iOS / Android manquants
n'a pas été exécuté, ou a été exécuté contre un dépôt différent. Vérifiez avec	`gh secret set -f` échoue en CI mais fonctionne localement `gh secret list`
`cap sync` Un plugin natif n'est pas dans	, ou vous avez oublié `package.json`Résolution des problèmes `bun install` avant `cap sync`
La construction réussit mais aucune application n'apparaît dans App Store Connect	L'ID d'équipe est incorrect, ou le record d'application n'existe pas encore dans App Store Connect. Vérifiez localement avec `bunx @capgo/cli@latest build credentials manage`
La construction est bloquée après « Téléchargement du projet »	L'archive du projet est inhabituellement grande — vérifiez que `node_modules` n'est pas téléchargé (ce n'est pas la norme par défaut)
`Provisioning profile doesn't match bundle ID`	La carte de provisionnement pointe vers un ID de bundle différent de celui que Xcode signe. Re-run `build init` pour rafraîchir le profil, puis ré-export avec `build credentials manage`
Les informations d'identification ont changé localement mais CI échoue toujours	N'oubliez pas de ré-exporter et de ré-pousser : `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
Le gestionnaire refuse d'écrire le fichier combiné	Les clés de configuration partagées diffèrent entre plateformes — le gestionnaire avertit et demande confirmation. Confirmez pour écraser l'un des deux, ou ré-exportez par plateforme avec `--platform ios` / `--platform android`
`build last-output` imprime une URL vide	La construction n'a pas réussi `--output-upload`ou elle a échoué avant de produire un artefact. `outputUrl` sera `null` au registre. Brancher sur `[ -n "$URL" ]` avant de l'utiliser
`build last-output` avec des erreurs `Unsupported record schemaVersion`	Le runner est sur une version plus ancienne de CLI que celle qui a écrit le registre. Fixer la même version explicite (par exemple `bunx @capgo/cli@7.104.0 …` sur les deux côtés) plutôt que `@latest`, qui flotte et peut dériver entre les tâches

Pour les échecs de construction spécifiques au plateforme, voir le guide de dépannage.

Étapes suivantes

Configuration des identifiants Référence complète pour la préparation des identifiants iOS et Android en tant que secrets base64.

Construction d'applications iOS Guide plus approfondi sur les certificats, les profils et la soumission sur l'App Store.

Construction d'applications Android Configuration de la clé de stockage, des comptes de service Play Store et gestion des saveurs.

Options de configuration Toutes les CLI options de drapeau et variables d'environnement pour une personnalisation fine de vos constructions.