GitHub Azioni

Copia un prompt di configurazione con le istruzioni 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 unico e un piccolo numero di segreti del repository, ogni push, tag o trigger manuale può produrre app firmate e pronte per il store — senza che nessun membro dello staff abbia bisogno di un Mac, Xcode o Android Studio installati.

Cosa ottieni

Rilasci senza intervento manuale

Etichetta un rilascio in Git e le tue app iOS e Android firmate vengono inviate automaticamente a TestFlight e Play Store.

Nessuna configurazione locale

Contribuenti su Windows o Linux possono attivare le build per iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che gira intorno ai portatili.

Segreti a livello di ambito

I segreti vivono nei segreti del repository GitHub, a livello di ambito 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 release si conclude in meno di 10 minuti.

Requisiti preliminari

Prima di configurare il workflow, assicurati di avere:

Un account Capgo con una sottoscrizione attiva e una Capgo API chiave
La tua app registrata in Capgo (bunx @capgo/cli@latest app add se non lo è)
Configura le credenziali di build locali con bunx @capgo/cli@latest build init vedi Gestione delle credenziali per la guida passo passo del wizard
Un build locale riuscito (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — il CI non è il posto giusto per debuggare il tuo primo build
Il GitHub CLI (gh) installato e autenticato (gh auth login)

Configurazione

The Capgo CLI can export your local credentials as a ready-to-use .env . Il __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ può esportare le tue credenziali locali come un file pronto all'uso gh secret set -f. Combinato con

Add your Capgo API key as a repository secret

Aggiungi la tua API __CAPGO_KEEP_1__ chiave come un segreto del repository
. La __CAPGO_KEEP_0__ chiave non fa parte del magazzino di credenziali per app, quindi aggiungila una volta manualmente:
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Copia nel portapenne Genera la chiave nel Capgo dashboard con carica o con 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 .env. Il CLI scrive .env.capgo.<appId> con modalità 0600 (disponibile solo per il proprietario) — ad esempio, .env.capgo.com.example.app. Quando sono configurati sia iOS che Android, le chiavi segrete di entrambe le piattaforme vengono salvate nello stesso file sotto # === IOS === e # === ANDROID === sezione dei titoli. I nomi delle variabili di ambiente per iOS e Android sono disgiunti, quindi combinare le due è conflitto-free.

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

A pochi toggle di configurazione (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) possono essere memorizzati sotto ogni piattaforma in modo autonomo e possono essere diventati diversi. Se il gestore 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 a GitHub segreti Actions

La gh secret set -f comanda legge un file dotenv e crea un segreto di repository per KEY=value linea:
Finestra del terminale
```
gh secret set -f .env.capgo.com.example.app
```
È tutto — ogni segreto che il tuo workflow ha bisogno è ora in GitHub. Verifica con gh secret list.
Don't commit il file .env
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Finestra del terminale
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Re-export anytime you need to rotate credentials — the file isn’t a long-lived artifact.
Creare il file di workflow

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

Cosa finisce nella sezione dei segreti

Per riferimento, gh secret set -f creerà questi segreti del repository (il tuo file YAML di workflow li cita 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 sotto riportati già fanno riferimento a tutti di loro.

Esempi di Flusso di Lavoro

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 che chiunque abbia accesso di scrittura possa avviare una costruzione dal azioni tabella in GitHub con un menu a discesa per piattaforma. Utile per costruire versioni 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

Il 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 uno dei due piattaforme ha un problema di firma temporaneo.

3. Debug Build su Push a Main

Cattura le regressioni di costruzione nativa in anticipo producendo un costrutto Android in modalità debug su ogni invio a main. Economico da eseguire, feedback veloci e puoi saltare l'upload su Play Store per mantenerlo puramente come 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

La paths il filtro assicura che il flusso di lavoro non venga eseguito su modifiche esclusivamente documentali. --no-playstore-upload salta la sottoscrizione a Play Store (nessuna PLAY_CONFIG_JSON è necessaria), e --output-upload produce un URL di download per il file APK risultante in modo che tu possa installarlo su un dispositivo di test.

Pattimenti Comuni

Saltare l'upload di Play Store / TestFlight

Per le versioni di test, saltare la sottoscrizione al negozio: Android utilizza --no-playstore-upload; per iOS, costruire in modalità ad-hoc con --ios-distribution ad_hoc (che non invia mai alla App Store). Combina entrambi con --output-upload per ottenere una URL di download a tempo limitato per il file binario.

Sottoporre la versione di rilascio al controllo del negozio

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

Android utilizza il tuo PLAY_CONFIG_JSON servizio di account. Senza un tracciato esplicito, --submit-to-store-review si applica al percorso di produzione con release_status: completed. Preferire indicare il percorso all'istante della chiamata con --android-track (o PLAY_STORE_TRACK), e sovrascrivere lo stato con --android-release-status / PLAY_STORE_RELEASE_STATUS quando necessario:

- 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 al posto 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 il build elaborato di TestFlight alla revisione di App Store. Richiede app_store la 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 di costruzione e il QR code

Passa --output-record <path> per persistere l'URL di artefatto di costruzione e il QR code sul disco quando la costruzione ha successo, poi leggilo nuovamente nelle fasi successive con 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 QR code in PNG accanto a /tmp/build.json.qr.png. build last-output leggilo nuovamente:

--field outputUrl stampa solo l'URL di download (terminato da nuovo riga; sicuro per URL=$(...)).
--field qrCodePngPath stampa il percorso del file PNG in modo che possa essere caricato come allegato di PR.
--qr stampa il codice ASCII QR — inseriscilo dentro un recinto di Markdown code nella commento di PR per la lettura 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

Cache dipendenze

bun install è già abbastanza veloce che un cache delle dipendenze JS è raramente redditizio, ma le dipendenze native di Capacitor (CocoaPods, Gradle) sono comunque da 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 i problemi

Sintomo	Causa probabile
`CAPGO_TOKEN is not set`	La chiave segreta non è stata aggiunta, o il job non ha accesso ad essa (verifica le protezioni dell'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	A plugin nativo non è presente `package.json`o hai dimenticato `bun install` prima `cap sync`
Costruisci con successo ma non appare alcuna app in App Store Connect	L'ID del team è sbagliato o l'app non esiste ancora in App Store Connect. Verifica localmente con `bunx @capgo/cli@latest build credentials manage`
La costruzione si blocca dopo 'Caricamento del progetto'	La cartella del progetto è insolitamente grande — controlla che `node_modules` non stia caricando (non dovrebbe farlo di default)
`Provisioning profile doesn't match bundle ID`	Il mapping di provisioning punta a un ID bundle diverso da quello con cui Xcode firma. Esegui di nuovo `build init` per aggiornare il profilo, quindi esporta nuovamente con `build credentials manage`
Il cambio delle credenziali locali non ha ancora avuto effetto sul CI	Dimenticati di esportare nuovamente e di 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 conferma per sovrascrivere, o si esporta nuovamente 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. Sulla branca di `[ -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. Si fissi entrambe la versione produttrice e quella del lettore alla stessa versione esplicita (ad esempio `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`, che fluttua e può deviare tra i job

For le fallimenti di costruzione specifici della piattaforma, vedi il Guida di risoluzione dei problemi.

Passaggi successivi

Auto OTA o Nativo CI di ramo tra l'upload di aggiornamento in tempo reale e Capgo Build.

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

Build Webhooks Inizia lo stesso workflow da una chiamata HTTP del pannello di controllo amministrativo.

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 la fine-tunizzazione delle tue build.