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 magazzino — senza che nessun membro dello staff abbia bisogno di un Mac, Xcode o Android Studio installati.

Cosa Otterrai

Lanci senza Intervento

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

Setup Locale Non Richiesto

I contribuenti su Windows o Linux possono attivare le compilazioni iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che gira intorno ai 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 impostare 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 passo dopo passo del mago
Una costruzione locale riuscita (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — il 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 più alti.
Esporta le tue credenziali in un .env file

Eseguire il gestore delle credenziali interattivo:
Fenestra del terminale
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Nella TUI, seleziona Esporta in .env. Il CLI scrive .env.capgo.<appId> nel tuo directory corrente con modalità 0600 (solo leggibile dal proprietario) — ad esempio, .env.capgo.com.example.app. Quando sia iOS che Android sono configurati, le segrete di entrambe le piattaforme finiscono nel medesimo file sotto # === IOS === Ecco # === ANDROID === Sezione intestazione. I nomi delle variabili di ambiente per iOS e Android sono disgiunti, quindi combinare i due è 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 i segreti di 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 in cima al file. Ri-esporta con --platform If hai bisogno di preservare valori per piattaforma.
Invia il .env file a GitHub Secrets dell'azione

La gh secret set -f comando legge un file dotenv e crea un segreto repository per KEY=value riga:
Fenestra del terminale
```
gh secret set -f .env.capgo.com.example.app
```
Ecco fatto — ogni segreto che il tuo workflow ha bisogno è ora in GitHub. Verifica con gh secret list.
Non commettere il file .env
Contiene materiale di firma in testo piano. Una volta che l'avrai inviato a 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.
Crea il file di workflow

Aggiungi .github/workflows/capgo-build.yml al tuo repository. Scegli uno dei tre modelli di trigger sotto a seconda di come vuoi 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 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 fanno già 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 il 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 Actions tabella 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 com.example.app con il tuo ID dell'app. Una volta commesso, vai a Azioni → Capgo Costruzione (Manuale) → Esegui workflow per attivarlo.

2. Rilascio su Tag

Costruisce e distribuisce entrambe le piattaforme in parallelo ogni volta che puoi spingere un tag di versione come 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. Impostazione fail-fast: false significa un build iOS fallito non cancellerà il build Android in corso (e viceversa) — utile quando una piattaforma ha un problema di firma temporaneo.

3. Costruisci in modalità debug su push a Main

Cattura le regressioni di build nativo in anticipo producendo un build Android in modalità debug con ogni push a main. Economico da eseguire, feedback veloce, 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 documentali. --no-playstore-upload salta l'invio su Play Store (non PLAY_CONFIG_JSON necessario), e --output-upload produce un URL di download per il file 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 alla App Store). Combina entrambi con --output-upload per ottenere un URL di download temporaneo per il binario.

Sottoponi la versione di rilascio per la revisione

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

Android utilizza il tuo PLAY_CONFIG_JSON account di servizio e sottopone la versione di rilascio di Google Play al posto di lasciarla inattiva. Aggiungi --store-release-name, --store-release-notes, e opzionali --store-release-notes-locale entri quando desideri che la versione di rilascio di Play porti lo stesso tag e le note di rilascio localizzate come CI:

- 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 \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${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 distribuzione --ios-testflight-groups è facoltativo per la distribuzione beta esterna e non è richiesto per la revisione di 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

Leggi l'URL di output della build e il QR code

Passa --output-record <path> per persistere l'URL e il QR code dell'artifact della build sul disco quando la build ha successo, quindi leggilo nuovamente nelle fasi successive con build last-outputNessuna 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 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 strada del PNG in modo che possa caricarlo come allegato PR.
--qr stampa il QR ASCII reso - lascialo dentro un recinto Markdown code sulla commento PR per la scannabilità inline.

Saltare il numero di build

Di default ogni rilascio di build 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 degne di essere cache 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') }}

Risolvere problemi

Sintomo	Causa probabile
`CAPGO_TOKEN is not set`	Il segreto non è stato 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 contro un repository diverso. Verifica con `gh secret list`
`cap sync` fallisce in CI ma funziona localmente	Un plugin nativo non è in `package.json`, o hai dimenticato `bun install` prima `cap sync`
Il build ha successo ma non compare alcuna app in App Store Connect	ID del team sbagliato, o il record dell'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`	The mappa di provisioning punta a un diverso ID bundle rispetto a quello con cui Xcode firma. Riavvia `build init` per aggiornare il profilo, quindi ri-esporta con `build credentials manage`
Il cambiamento delle credenziali locali ma il CI continua a fallire	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	Il manager avverte e chiede conferma per le chiavi di configurazione condivise tra piattaforme. Si conferma per sovrascrivere, o si ri-esporta per piattaforma con `--platform ios` / `--platform android`
`build last-output` Stampa un URL vuoto	La costruzione non è riuscita `--output-upload`o ha fallito prima di produrre un artefatto. `outputUrl` sarà `null` nel registro. Sviluppa su `[ -n "$URL" ]` prima di utilizzarlo
`build last-output` errori con `Unsupported record schemaVersion`	Il runner è su una versione più vecchia di CLI rispetto a quella che ha scritto il record. Assicurati che sia produttore e lettore siano fissati alla stessa versione esplicita (ad esempio `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`, che galleggia e può spostarsi tra i lavori

Per fallimenti di costruzione specifici della piattaforma, vedi 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 sui certificati, sui profili e sulla sottoscrizione all'App Store.

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

Opzioni di configurazione Tutti i flag e le variabili di ambiente CLI per una fine-tuning delle tue costruzioni.