GitHub Azioni

Copia la guida di installazione con i passaggi e la guida Markdown completa per questo plugin.

Automatizza i tuoi build iOS e Android direttamente dal tuo repository GitHub. Con un file di workflow e un pugno di segreti del repository, ogni push, tag o trigger manuale può produrre app firmate e pronte per il magazzino — senza che nessun membro dello staff abbia bisogno di un Mac, Xcode o Android Studio installati.

Cosa Otterrai

Rilasci senza Intervento

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

Setup Locale Non Richiesto

Contributori su Windows o Linux possono attivare le compilazioni per iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che galleggia sui portatili.

Segreti a livello di ambito

Credenziali sono memorizzate nei segreti del repository GitHub, associati al tuo repository e visibili solo al runner del workflow. Facile da rotare, facile da verificare.

Costruzioni parallele

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

Prerequisites

Prima di configurare il workflow, assicurati di avere:

Un Capgo account con una sottoscrizione attiva e un Capgo API chiave
La tua app registrata in Capgo (bunx @capgo/cli@latest app add se non)
Costruisce credenziali configurate localmente con bunx @capgo/cli@latest build init — vedi Gestione delle credenziali per la guida del mago
Un costrutto locale riuscito (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debugnon è il posto giusto per debuggare il tuo primo costrutto
Il GitHub CLI (gh) installato e autenticato (gh auth login)

Setup

Il tuo Capgo CLI può esportare le tue credenziali locali come file pronto all'uso .env file. Combinato con gh secret set -f, questo trasforma l'intera configurazione CI/CD in tre comandi — nessuna codifica base64 manuale, nessuna gestione JSON, nessuna copia-incolla-segreti-segreti.

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:
Fenestra del terminale
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Genera la chiave nel Pannello di controllo Capgo con Carica o un livello di autorizzazione superiore.
Esporta le tue credenziali in un .env file

Esegui il gestore delle credenziali interattivo:
Fermata dei comandi
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Nella finestra TUI, seleziona Esporta in .env. Il CLI scrive .env.capgo.<appId> nel tuo directory corrente con permessi 0600 (solo lettura del proprietario) — ad esempio, .env.capgo.com.example.app. Quando sia configurati iOS e Android, i segreti di entrambe le piattaforme finiscono nello stesso file sotto # === IOS === e # === ANDROID === section headers. iOS and Android env-var names are disjoint, so combining them is conflict-free.

Passa --platform ios (o --platform androidper limitare il manager a una piattaforma. L'esportazione produce quindi un file per piattaforma come .env.capgo.com.example.app.ios. Utile quando i segreti di iOS e Android vivono in repository o ambienti diversi.

Un pugno di interruttori di configurazione (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) può essere archiviato separatamente per ogni piattaforma e potrebbe essere diventato diverso. 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 in cima al file. Ri-esporta con --platform Se hai bisogno di preservare i valori per piattaforma.
Spingi il .env file su GitHub Segreti Actions

La gh secret set -f comando legge un file dotenv e crea un segreto di repository per KEY=value riga:
Finestra del terminale
```
gh secret set -f .env.capgo.com.example.app
```
È tutto — ogni segreto che il tuo workflow necessita è ora in GitHub. Verifica con gh secret list.
Non commettere il file .env
Contiene materiale di firma in testo normale. Una volta che l'avete spedito su GitHub:
Finestra del terminale
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Rieporta ogni volta che è necessario rotare le credenziali — il file non è un artefatto a lunga durata.
Creare il file di workflow

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

Cosa finisce nelle tue segrete

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

Piattaforma	Esegui 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 sotto riportati già fanno riferimento a tutti di loro.

Esempi di workflow

I tre esempi sotto riportati coprono i modelli più comuni. Tutti utilizzano la stessa forma: controlla il repository, installa le dipendenze, costruisci gli asset web, sincronizza con nativo, poi chiama Capgo Costruisci con credenziali passate come variabili di ambiente.

1. Trigger manuale

Lascia chiunque abbia accesso di scrittura lanciare un build dal Azioni tab in GitHub con un menu a discesa per piattaforma. Utile per costruire build ad-hoc o per avviare una rilascio 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 com.example.app con il tuo ID dell'app. Una volta commesso, vai a Azioni → Capgo Costruisci (Manuale) → Esegui workflow per attivarlo.

2. Rilascio su Tag

Builds and ships both platforms in parallel whenever you push a version tag like v1.4.0Questo è il setup di produzione più comune — git tag v1.4.0 && git push --tags diventa il tuo comando di rilascio.

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. Impostare 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.

Sezione intitolata "3. Esegui build su push a Main"

Cattura le regressioni di costruzione nativa in anticipo producendo un build Android debug su ogni push a mainEconomico da eseguire, feedback veloci, e puoi saltare l'upload su 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 filter ensures the workflow doesn’t run on doc-only changes. --no-playstore-upload salta l'invio su Play Store (nessuna PLAY_CONFIG_JSON necessità), e --output-upload genera un URL di download per l'APK risultante in modo che possa installarlo su un dispositivo di test.

Patterni Comuni

Salta l'upload su Play Store / TestFlight

For test builds, skip store submission: Android uses --no-playstore-upload; per iOS, costruisci in modalità ad-hoc con --ios-distribution ad_hoc (che non invia mai alla App Store). Combina entrambi con --output-upload ottenere un URL di download temporaneo per il file binario.

Invia la versione di store per la revisione

Di default, le rilascie del store caricano l'artifact firmato e lasciano l'azione finale del store sotto il tuo controllo. Per le rilascie CI che dovrebbero muoversi direttamente nella flussi di revisione del store, aggiungi --submit-to-store-review.

Android utilizza il tuo PLAY_CONFIG_JSON account di servizio. Senza un tracciato esplicito, --submit-to-store-review si default al tracciato di produzione con release_status: completed. Prefer specificare il tracciato in sito di chiamata con --android-track (o PLAY_STORE_TRACK, e sovrascrivere lo stato quando necessario: --android-release-status / PLAY_STORE_RELEASE_STATUS Copia nel portapenne

- name: Submit Android release for review
  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 }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track production \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

Per un rilascio interno completato invece che di produzione:

- name: Submit Android internal release
  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 }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track internal \
      --store-release-name "${GITHUB_REF_NAME}"

iOS utilizza la chiave di percorso App Store Connect API e invia la build elaborata di TestFlight alla revisione di App Store. Richiede app_store distribution; --ios-testflight-groups è facoltativo per la distribuzione beta esterna e non è richiesto per la revisione dell'App Store:

- name: Submit iOS build to App Store review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
    CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
    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 }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform ios \
      --build-mode release \
      --ios-distribution app_store \
      --submit-to-store-review \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}" \
      --no-ios-automatic-release

Read the build output URL and QR code

Passa --output-record <path> to persist the build artifact URL and QR code to disk when the build succeeds, then read it back in subsequent steps with build last-outputSenza scrittura di log, senza 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, finishedAte un codice QR code in PNG accanto a /tmp/build.json.qr.png. build last-output leggilo nuovamente:

--field outputUrl stampa solo l'URL di download (a capo; sicuro per URL=$(...)).
--field qrCodePngPath prints the PNG path so you can upload it as a PR attachment.
--qr stampa il codice ASCII QR — inseriscilo dentro un recinto di Markdown code nella commento di PR per la lettura inline.

Saltare l'incremento 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

Cache dipendenze

bun install è già abbastanza veloce che un cache JS-dipendenze raramente si ripaga, ma Capacitor's dipendenze native (CocoaPods, Gradle) sono utili per caching per 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') }}

Troubleshooting

Symptom	Causa probabile
`CAPGO_TOKEN is not set`	Segreto non aggiunto, o il lavoro non ha accesso ad esso (controlla le protezioni dell'ambiente/ramo)
Errore 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` non funziona nei CI ma funziona localmente	A plugin nativo non è presente `package.json`o hai dimenticato `bun install` prima `cap sync`
Creare un problema e discutere prima di lavorare su una nuova funzione	Errore nell'ID della squadra o il record dell'app non esiste ancora in App Store Connect. Verifica localmente con `bunx @capgo/cli@latest build credentials manage`
Il progetto si blocca durante l'upload	La costruzione si blocca dopo 'Caricamento del progetto' `node_modules` non viene caricato (non dovrebbe essere caricato di default)
`Provisioning profile doesn't match bundle ID`	La mappa di provisioning punta a un ID bundle diverso da quello con cui Xcode sta firmando. Esegui nuovamente `build init` per rifare il profilo, esporta nuovamente con `build credentials manage`
per aggiornare il profilo, quindi esporta nuovamente con	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, oppure ri-esportare per piattaforma. `--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`	The runner is on an older CLI than the one that wrote the record. Pin both producer and reader to the same explicit version (e.g. `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`, che fluttua e può allontanarsi tra le esecuzioni

For platform-specific build failures, see the Guida di risoluzione dei problemi.

Next Steps

Auto OTA o Nativo CI tra l'upload di live update e il Capgo Build.

Attiva da CI UI Esegui Capgo Build dalla scheda Azioni su richiesta.

Costruisci Webhook Avvia lo stesso workflow da un dashboard HTTP di amministrazione.

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

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