GitHub Azioni

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

Automatizza le tue costruzioni 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 del team abbia bisogno di un Mac, Xcode o Android Studio installati.

Cosa Otterrai

Lanci 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

I contribuenti su Windows o Linux possono attivare le costruzioni iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che gira intorno ai laptop.

Segreti Scoperti

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

Costruzioni in Parallelo

Costruisci iOS e Android nello stesso momento con un lavoro di matrice. Un rilascio tipico si conclude in meno di 10 minuti.

Requisiti

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 è)
Le credenziali di build configurate localmente con bunx @capgo/cli@latest build init — vedi Gestione delle Credenziali per la guida passo passo del wizard
Una build locale riuscita (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug — CI non è il posto per debuggare il tuo primo build
Il GitHub CLI (gh) installato e autenticato (gh auth login)

Configurazione

Il Capgo CLI può esportare le tue credenziali locali come file pronto all'uso, .env file. Combinato con gh secret set -fQuesto riduce l'intera configurazione CI/CD a tre comandi — nessuna codifica base64 manuale, nessun ingranaggio JSON, nessun copia-incolla-segreti-segreti-segreti.

Aggiungi la tua Capgo API chiave come segreto del repository

La chiave API non fa parte del magazzino di credenziali per-app, quindi aggiungila una volta manualmente:
Fermata del terminale
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Genera la chiave nel Capgo dashboard con carica permessi o superiori.
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
```
Nel TUI, seleziona Esporta in .env. Il CLI scrive .env.capgo.<appId> nella tua directory corrente con modalità 0600 (solo leggibile dal proprietario) — ad esempio, .env.capgo.com.example.appQuando sia iOS che Android sono configurati, i segreti di entrambe le piattaforme finiscono nel medesimo file sotto # === IOS === e # === ANDROID === intestazioni dei sottosezioni. I nomi delle variabili di ambiente iOS e Android sono disgiunti, quindi combinare i due è conflitto-free.

Passa --platform ios (o --platform android) per limitare il gestore a una sola piattaforma. L'esportazione produce poi un file per piattaforma come .env.capgo.com.example.app.iosUtile quando i segreti di iOS e Android vivono in repository o ambienti diversi.

Un pugno di impostazioni di configurazione (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) possono essere memorizzate indipendentemente per ogni piattaforma e possono essere diventate diverse. Se il gestore trova delle differenze, stampa le chiavi in conflitto, chiede 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.
Inserisci il .env file in GitHub segreti di Actions

Il gh secret set -f comando legge un file dotenv e crea un segreto repository per linea: KEY=value Finestra del terminale
Copia nel portapenne
```
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.
Contiene materiale di firma in chiaro. Una volta che l'avrai spinto su __CAPGO_KEEP_0__:
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Copia nel portapenne
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Finestra del terminale
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 nei tuoi segreti

Per riferimento, gh secret set -f creerà questi segreti del repository (il tuo file YAML di workflow li riferisce esattamente 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`
(aggiunti manualmente)	`CAPGO_TOKEN`

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

Esempi di workflow

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 Pulsante "Azioni" in GitHub con un menu a discesa di 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 With il tuo ID dell'app. Una volta commesso, vai a azioni → Capgo Costruisci (Manuale) → Esegui workflow per attivarlo.

2. Rilascio su Tag

Il build e la distribuzione di entrambe le piattaforme vengono eseguiti in parallelo ogni volta che si invia un tag di versione come v1.4.0. Questo è 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 runner separati. Impostare fail-fast: false significa che un build iOS fallito non annullerà il build Android in corso (e viceversa) — utile quando una piattaforma ha un problema di firma temporaneo.

3. Costruisci in debug su push a Main

Cattura le regressioni di costruzione nativa in anticipo producendo un costrutto Android in debug su ogni push a mainCosto basso, 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

assicura che il flusso di lavoro non venga eseguito su modifiche solo documentali. paths salta la sottoscrizione alla Play Store (non necessaria), e --no-playstore-upload produce un URL di download per l'APK risultante in modo che tu possa installarlo su un dispositivo di test. PLAY_CONFIG_JSON Modelli Comuni --output-upload Sottosezione intitolata “Modelli Comuni”

Salta sottoscrizione alla Play Store / Carica su TestFlight

Per le build di test, salta la sottoscrizione alla store: Android utilizza

(che non invia mai alla App Store). Combina entrambi con --no-playstore-uploadCommon Patterns --ios-distribution ad_hoc Skip Play Store / TestFlight upload --output-upload per ottenere un URL di download temporaneo per il binario.

Leggi l'URL di output di costruzione e il QR code

Passa --output-record <path> per persistere l'URL dell'artefatto di costruzione e il QR code sul disco quando la costruzione ha successo, quindi leggilo nuovamente nelle fasi successive con build last-outputNessuna raccolta di log, nessun 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 leggilo nuovamente:

--field outputUrl stampa solo l'URL di download (terminato con nuovo riga; sicuro per URL=$(...)).
--field qrCodePngPath stampa il percorso del file PNG in modo che tu possa caricarlo come allegato PR.
--qr stampa il codice ASCII QR — lascialo all'interno di un recinto Markdown code nella commento della PR per la scannabilità 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 le dipendenze

bun install è già abbastanza veloce che una cache dei dipendenze JS è raramente redditizia, 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`	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 è presente `package.json`, o hai dimenticato `bun install` prima `cap sync`
La costruzione ha avuto successo, ma non compare l'applicazione in App Store Connect	L'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`
La costruzione si blocca dopo 'Caricamento del progetto'	Il file di archiviazione 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 sta firmando. Riavvia `build init` per aggiornare il profilo, quindi esporta nuovamente con `build credentials manage`
Il credenziale sono state cambiate localmente ma il CI continua a fallire	Dimentica 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	Il manager avverte e chiede conferma per le chiavi di configurazione condivise tra piattaforme. Si può confermare per sovrascrivere, o esportare nuovamente per piattaforma con `--platform ios` / `--platform android`
`build last-output` stampa un URL vuoto	La costruzione non è riuscita `--output-upload`, oppure è fallita prima di produrre un artefatto. `outputUrl` sarà `null` nel registro. Sulla branca di `[ -n "$URL" ]` prima di utilizzarlo
`build last-output` errori con `Unsupported record schemaVersion`	Lo esecutore si trova su una versione più vecchia di CLI rispetto a quella che ha scritto il registro. Assicurarsi che sia fissata la stessa versione esplicita (ad esempio `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`, che fluttua e può spostarsi tra i job

Per le fallite di costruzione specifiche 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.

Costruzione iOS Guida più approfondita sui certificati, sui profili e sulla sottoscrizione all'App Store.

Costruzione Android Configurazione del keystore, servizi di Play Store e gestione dei flavor.

Opzioni di configurazione Tutti i flag e le variabili di ambiente CLI per una fine-tuning dei costruttori.