Workflow per canali Native + OTA

Una configurazione Capgo comune utilizza un dev channel e un produzione channel. La CI carica ogni bundle OTA su dev, poi promuove a production quando sei pronto. I team spesso aggiungono --fail-on-incompatible così la CI non pubblica accidentalmente un live update che richiede nuovi code nativi.

Questa pagina risponde a: cosa fare quando si volontariamente serve un bundle incompatibile con i package nativi attuali del canale?

Se vuoi capire perché Capgo confronta i package nativi, parti da Compatibilità nativa. Per una pipeline CI completa che scelga tra OTA o Capgo Build in automatico, vedi Auto OTA o Native.

Layout dei canali consigliato

Questa guida presuppone che i dev e production canali esistano già. Creali prima, se necessario:

npx @capgo/cli@latest channel add production com.example.app
npx @capgo/cli@latest channel add dev com.example.app

Canale	Chi lo riceve	Upload tipico
dev	Build interne / QA	Ogni push CI di JS (e baseline native intenzionali)
production	Utenti degli Store	Promosso o caricato solo quando pronto per il rilascio

--fail-on-incompatible è un buon default su entrambi i canali per upload OTA quotidiani. Confronta i pacchetti nativi nel bundle che stai caricando con il bundle attualmente attivo su quel canale. Se differiscono, l'upload fallisce e nulla viene rilasciato.

OTA quotidiano (mantieni il flag)

Quando la modifica riguarda solo JavaScript e i pacchetti nativi corrispondono al canale:

npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --fail-on-incompatible \
  --auto-min-update-version

--fail-on-incompatible blocca l'eventuale drift nativo accidentale. --auto-min-update-version è richiesto ad ogni upload una volta che il canale utilizza la metadata strategia (consigliata sotto). Se il canale non è ancora su metadata puoi omettere --auto-min-update-version finché non effettui il passaggio.

Opzionale: gate CI prima dell'upload:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to upload with --fail-on-incompatible
# → native   stop; ship a native binary first (see below)

Bump nativo intenzionale (togli il flag una volta)

Tu non può fare l'upload di un bundle che richiede nuovi code nativi mantenendo --fail-on-incompatible. Quel flag serve proprio a bloccare questo caso. Quando un plugin, la versione di Capacitor, o un'altra dipendenza nativa cambia intenzionalmente:

1. Pubblica il corrispondente binario nativo (App Store / Play Store, o Build Capgo).
2. Carica il bundle JS corrispondente senza --fail-on-incompatible.
3. Preferisci --auto-min-update-version con il canale impostato su metadata strategy, così i dispositivi che usano ancora il vecchio binario non ricevono il nuovo bundle finché non installano la nuova app.
4. Dopo questo upload di baseline, torna --fail-on-incompatible alla normale CI OTA (e mantieni --auto-min-update-version mentre il canale rimane su metadata).

1. Una tantum per canale: abilita il metadata gating

   npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

   Ripeti per dev se anche quel canale riceve baseline native intenzionali. Dopo questo passaggio, ogni upload sul canale deve includere --auto-min-update-version o --min-update-version.

2. Pubblica il binario nativo

   Fai la build e invia l'app iOS/Android che include i nuovi plugin o le modifiche native. Finché gli utenti non installano quel binario, non possono eseguire in sicurezza un bundle che dipende da quei pacchetti nativi.

3. Carica la baseline OTA corrispondente (nessun --fail-on-incompatible)

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --auto-min-update-version

   Questo registra i nuovi pacchetti nativi sul canale. In seguito bundle releaseType / --fail-on-incompatible i controlli usano quella baseline.

4. Riprendi gli upload OTA protetti

   I rilasci JS-only successivi usano di nuovo entrambi i flag:

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --fail-on-incompatible \
     --auto-min-update-version

Tip

Considera l'upload del native-baseline come un job CI dedicato (o un passaggio di release manuale), non come un'eccezione da aggiungere al job OTA predefinito. Il job predefinito deve sempre mantenere --fail-on-incompatible, e su un metadata channel deve anche mantenere --auto-min-update-version.

FAQ

Posso mantenere --fail-on-incompatible e spingere comunque un bundle incompatibile con il Native Build?

No. Se i pacchetti nativi dell'upload differiscono dal bundle live del canale, il flag blocca intenzionalmente il comando. Per un aggiornamento nativo voluto, ometti il flag in quell'upload (e usa --auto-min-update-version quando possibile).

Un upload una tantum senza flag è l'approccio corretto?

Sì. È il modo supportato per aggiornare la baseline nativa del canale dopo aver rilasciato un nuovo binario. Mantieni il flag in tutti gli altri upload OTA per far fallire la CI in caso di drift nativo accidentale.

Devo caricare su dev prima, poi su production?

Sì, se corrisponde al tuo processo. Applica le stesse regole per canale: il controllo di compatibilità avviene rispetto a quanto è attualmente live sul canale di destinazione. Promuovi o carica nuovamente su production solo dopo dev sembra a posto, e usa un upload native-baseline (senza --fail-on-incompatible) su ogni canale in cui vanno registrati i nuovi pacchetti nativi.

Cosa succede se faccio upload del nuovo bundle nativo con il flag ancora attivo?

La CI fallisce e Capgo non distribuisce quell'upload. È il risultato previsto. O il cambiamento è stato accidentale (correggi i pacchetti nativi e riprova come OTA), oppure era intenzionale (usa il percorso nativo qui sopra).

Quale flag va su quale job?

Percorso	Quando	Flag di upload
OTA	Solo JS; i pacchetti nativi devono corrispondere al canale	--fail-on-incompatible + --auto-min-update-version (obbligatorio se il canale è attivo metadata)
Baseline nativa	Nuovo binario nativo + bundle JS corrispondente	No --fail-on-incompatible; mantieni --auto-min-update-version

Correlati

Compatibilità nativa

Come Capgo rileva il drift dei pacchetti nativi e cosa significa l'incompatibilità per i dispositivi.

Auto OTA o Native

Integra bundle releaseType in GitHub Actions o GitLab, così la CI sceglie il percorso corretto.

Targeting delle versioni

Canali, regole semver e la strategia dei metadati per i delivery floor.

CLI: bundle

Riferimento per upload, compatibilità, releaseType e flag correlati.

Continua da Native + OTA Channel Workflow

Se stai usando Workflow Canale Native + OTA per mantenere sicuri i Live Update tra i rilasci nativi, connettilo a Compatibilità nativa per le regole di confronto dei pacchetti, Auto OTA o Native per il branching della CI, Targeting delle versioni per i metadata floors e il riferimento al bundle Capgo CLI per i flag di upload.