GitHub Azioni

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Automatizza le tue compilazioni iOS e Android direttamente dal tuo repository GitHub. Con un file di workflow e un piccolo numero di segreti del repository, ogni push, tag o trigger manuale può produrre app firmate e pronte per il deposito — senza che nessun membro della squadra abbia bisogno di un Mac, Xcode o Android Studio installati.

Cosa Otterrai

Rilasci senza Intervento

Etichetta un rilascio in Git e i tuoi binari iOS e Android firmati vengono inviati automaticamente a TestFlight e Play Store.

Nessuna Configurazione Locale

I contributor su Windows o Linux possono attivare le compilazioni iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che gira tra i laptop.

Segreti Scoperti

I credenziali vivono nel repository GitHub segreti, scritti per il tuo repo e visibili solo al runner del workflow. Facile da rotare, facile da auditare.

Costruzioni parallele

Costruisci iOS e Android allo stesso tempo con un lavoro di matrice. Una tipica rilascio finisce in meno di 10 minuti.

Requisiti preliminari

Prima di configurare il workflow, assicurati di avere:

Un account Capgo con un abbonamento attivo e un Capgo API chiave
Il tuo app registrato in Capgo (bunx @capgo/cli@latest app add se non)
Le credenziali di costruzione configurate localmente con bunx @capgo/cli@latest build init — vedere Gestione delle credenziali per la guida di walkthrough del mago
Una costruzione locale riuscita (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — l'analisi CI non è il posto per debuggare la tua prima costruzione
Il GitHub CLI (gh) installato e autenticato (gh auth login)

Configurazione

Il Capgo CLI può esportare le tue credenziali locali come un file pronto all'uso. Combinato con .env , questo trasforma l'intero setup CI/CD in tre comandi — nessuna codifica base64 manuale, nessuna gestione JSON, nessuna copia-incolla-segreti-segreti. gh secret set -fInserisci la tua __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ chiave come un segreto del repository

Add your Capgo API key as a repository secret

The API key isn’t part of the per-app credential store, so add it once manually:
Copia nel portapenne
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
__CAPGO_KEEP_0__ dashboard Capgo dashboard l'upload Setup o permessi superiori.
Esporta le tue credenziali in un .env file

Esegui il gestore delle credenziali interattivo:
Finestra del terminale
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Nella TUI, seleziona Esporta in .envIl CLI scrive .env.capgo.<appId> nella tua directory corrente con modalità 0600 (lettura esclusiva del proprietario) — ad esempio, .env.capgo.com.example.appQuando entrambe iOS e Android sono configurate, le segrete di entrambe le piattaforme finiscono nel medesimo file sotto # === IOS === e # === ANDROID === I intestazioni di sezione. I nomi delle variabili di ambiente per iOS e Android sono disgiunti, quindi combinare loro è conflitto-free.

Passa --platform ios (o --platform android) per limitare il manager a una piattaforma. L'esportazione produce poi un file per piattaforma come .env.capgo.com.example.app.iosUtile quando le chiavi segrete per iOS e Android sono presenti in repository o ambienti diversi.

Un piccolo numero di chiavi di configurazione (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) possono essere memorizzate per ogni piattaforma in modo autonomo e possono essere diverse. Se il manager trova una divergenza, stampa le chiavi in conflitto, chiede una conferma esplicita prima di scrivere e inserisce la lista dei conflitti come commento all'inizio del file. Ri-esporta con --platform If hai bisogno di preservare valori per piattaforma.
Invia il file a __CAPGO_KEEP_0__ Secrets azioni .env file to GitHub Actions secrets

comando legge un file dotenv e crea un segreto repository per riga: gh secret set -f Fenestra del terminale KEY=value Copia nel portapenne
Ecco fatto — ogni segreto del tuo workflow è ora in __CAPGO_KEEP_0__. Verifica con
```
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.
Push the file to __CAPGO_KEEP_0__ Actions secrets
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Finestra del terminale
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Rieporta in qualsiasi momento hai bisogno di ruotare le credenziali — il file non è un artefatto a lunga durata.
Creare il file di workflow

Aggiungi .github/workflows/capgo-build.yml a tuo repository. Scegli uno dei tre modelli di attivazione di build sotto, a seconda di come desideri far partire i build.

Cosa finisce nelle tue segrete

Per riferimento, gh secret set -f creerà questi segreti del repository (il tuo file YAML di workflow li fa riferimento con questi nomi esatti):

Piattaforma	Segreti creati
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`
(aggiunto manualmente)	`CAPGO_TOKEN`

Non è necessario memorizzare questi — gli esempi di workflow riportati di seguito già fanno riferimento a tutti di loro.

Esempi di Flusso di Lavoro

Gli esempi riportati di seguito coprono i modelli più comuni. Tutti utilizzano la stessa forma: consultare il repository, installare le dipendenze, creare gli asset web, sincronizzare con nativo, quindi chiamare Capgo Costruisci con le credenziali passate come variabili di ambiente.

1. Trigger Manuale

Consente a chiunque abbia accesso di scrittura di avviare un build dal Azioni tab in GitHub con un menu a discesa per la piattaforma. Utile per test di ad-hoc o per avviare una release su richiesta.

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

Sostituisci con l'ID del tuo app. Una volta commesso, vai a com.example.app Azioni → __CAPGO_KEEP_0__ Costruisci (Manuale) → Esegui workflow Actions → Capgo Build (Manual) → Run workflow 2. Rilascio su Tag

Sezione intitolata “2. Rilascio su Tag”

Questo è il setup di produzione più comune — v1.4.0diventa il tuo comando di rilascio. git tag v1.4.0 && git push --tags /__CAPGO_KEEP_0__/workflow/__CAPGO_KEEP_1__-costruzione-rilascio.yml

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 esegue iOS e Android in parallelo su esecutori separati. Impostazione fail-fast: false significa che un build iOS fallito non cancellerà il build Android in corso (e viceversa) — utile quando una piattaforma ha un problema di firma temporaneo.

3. Esegui il build di debug all'invio su Main

Cattura le regressioni di build nativo in anticipo producendo un build di debug Android con ogni invio su main. È economico da eseguire, con feedback veloci e puoi saltare l'upload di Play Store per mantenerlo puramente un test di fumo.

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

Il paths il filtro assicura che il workflow non venga eseguito su modifiche esclusivamente di documentazione. --no-playstore-upload salta l'upload di Play Store (non PLAY_CONFIG_JSON necessario), e --output-upload produce un URL di download per l'APK risultante in modo che tu possa installarlo su un dispositivo di test.

Modelli comuni

Salta l'upload di Play Store / TestFlight

For le costruzioni di test, saltare la sottoscrizione del negozio: Android utilizza --no-playstore-upload; per iOS, costruisci in modalità ad-hoc con --ios-distribution ad_hoc (che non invia mai al negozio dell'App Store). Combina entrambi con --output-upload per ottenere un URL di download a tempo limitato per il binario.

Leggi l'URL di output di costruzione e QR code

Passa --output-record <path> per persistere l'URL dell'artefatto di costruzione e QR code sul disco quando la costruzione ha successo, quindi leggilo nuovamente nelle fasi successive con build last-output. Nessuna scrittura di log, nessuna 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 scrive un record JSON (con jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) e un QR code in formato PNG accanto a /tmp/build.json.qr.png. build last-output legge di nuovo:

--field outputUrl stampa solo l'URL di download (terminato da nuovo riga; sicuro per URL=$(...)).
--field qrCodePngPath stampa la cartella PNG in modo che possa caricarla come allegato PR.
--qr stampa il codice QR ASCII elaborato — inseriscilo dentro un recinto Markdown code nella commento PR per la scansione inline.

Saltare l'aumento del numero di build

Di default ogni build di rilascio incrementa il numero di build. Per fissarlo a un valore che controlli (ad esempio, il tag Git), passa --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

Dipendenze in cache

bun install è già abbastanza veloce che una cache delle dipendenze JS raramente si ripaga, ma le dipendenze native di Capacitor (CocoaPods, Gradle) sono comunque utili da cache per i progetti più grandi:

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

Risoluzione dei problemi

Sintomo	Causa probabile
`CAPGO_TOKEN is not set`	Segreto non aggiunto, o il lavoro non ha accesso a esso (controlla le protezioni ambiente/branch)
Errori di credenziali iOS / Android mancanti	`gh secret set -f` non è stato eseguito, o è stato eseguito su un repository diverso. Verifica con `gh secret list`
`cap sync` fallisce in CI ma funziona localmente	Un plugin nativo non è presente `package.json`, o hai dimenticato `bun install` prima `cap sync`
Il build ha successo ma non compare l'app in App Store Connect	ID del team sbagliato, o l'app non esiste ancora in App Store Connect. Verifica localmente con `bunx @capgo/cli@latest build credentials manage`
Il build si blocca dopo 'Caricamento del progetto'	L'archivio del progetto è insolitamente grande — controlla che `node_modules` non stia venendo caricato (non dovrebbe farlo di default)
`Provisioning profile doesn't match bundle ID`	La mappa di provisioning punta a un ID bundle diverso da quello con cui Xcode firma. Riavvia `build init` per aggiornare il profilo, poi rieporta con `build credentials manage`
Le credenziali sono state cambiate localmente ma CI fallisce ancora	Non dimenticare di ri-esportare e ri-pubblicare: `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
Il manager rifiuta di scrivere il file combinato	Le chiavi di configurazione condivise differiscono tra piattaforme — il manager avverte e chiede conferma. Si può confermare per sovrascrivere, o ri-esportare per piattaforma con `--platform ios` / `--platform android`
`build last-output` stampa un URL vuoto	La costruzione non è riuscita `--output-upload`o è fallita prima di produrre un artefatto. `outputUrl` sarà `null` nel registro. Ramo su `[ -n "$URL" ]` prima di utilizzarlo
`build last-output` con errori con `Unsupported record schemaVersion`	Il runner è su una versione più vecchia di CLI rispetto a quella che ha scritto il registro. Assicurati di fissare sia il produttore che il lettore alla stessa versione esplicita (ad esempio `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`Le quali galleggiano e possono spostarsi tra i lavori

Per fallimenti di costruzione specifici della piattaforma, vedere il Guida di risoluzione dei problemi.

Passaggi successivi

Configurazione delle credenziali Riferimento completo per la preparazione delle credenziali iOS e Android come segreti base64.

Costruzioni iOS Guida più approfondita per i certificati, i profili e la sottoscrizione all'App Store.

Costruzioni Android Configurazione del keystore, account di servizio Play Store e gestione dei flavor.

Opzioni di configurazione Tutti i CLI flag e variabili di ambiente per l'ottimizzazione delle tue build.