Trasforma ogni pull request in una preview installabile

Ogni team di sviluppo mobile ha provato lo stesso dolore: una feature è pronta per la review, ma per farla arrivare agli stakeholder bisogna affrontare il labirinto delle review beta di TestFlight o Google Play. Quello che dovrebbe richiedere minuti si trasforma in ore di attesa, installazione e gestione di build beta.

E se la tua app in produzione potesse fare il pull delle ultime modifiche da qualsiasi pull request direttamente sul dispositivo, senza reinstallazioni o ritardi degli app store?

È questo che PR preview rendono possibile. Quando uno sviluppatore apre una pull request, un'Action di GitHub crea un canale di aggiornamento dedicato e pubblica le modifiche. Chiunque abbia l'app installata può passare a quel canale, testare la funzionalità e tornare indietro, il tutto senza uscire dall'app che ha già.

Il problema di TestFlight

Il workflow tradizionale per testare funzionalità mobile è più o meno questo:

1. Lo sviluppatore apre la PR - Code è pronto per la revisione
2. In attesa di TestFlight - 15-30 minuti di elaborazione
3. Trova e installa - I tester cercano la build giusta
4. Testa e ripeti - Ogni modifica comporta un'altra attesa

Questo crea un collo di bottiglia. QA resta bloccato in attesa delle build. I product manager non possono verificare le funzionalità rapidamente. Gli sviluppatori perdono il contesto mentre aspettano il feedback. Si stima che questo costi circa 340 $ per PR in termini di produttività persa.

Come funzionano le PR Preview

Le PR preview utilizzano il sistema di canali di Capgo per creare stream di update dedicati a ogni PR. Ecco il flusso:

1. PR aperta o aggiornata - L'Action GitHub si attiva
2. Bundle caricato - Le modifiche JS/CSS vanno in un canale specifico per la PR
3. Commento pubblicato - I tester ricevono le istruzioni nella PR
4. Testing istantaneo - Cambia canale, testa, torna al precedente

Nessuna nuova installazione. Niente ritardi con TestFlight. La stessa app di produzione può ricevere update da canali diversi.

Configurare le PR Preview

Prima di poter implementare le anteprime PR, il tuo progetto deve essere configurato con Capgo Live Updates. Segui la quickstart guide di Capgo se non l'hai già fatto.

Workflow di GitHub Actions

Crea .github/workflows/pr-preview.yml:

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install Dependencies
        run: bun install

      - name: Build
        run: bun run build

      # Create a channel named after your PR (may already exist on synchronize)
      - name: Create PR Channel
        id: create_channel
        continue-on-error: true
        run: bunx @capgo/cli@latest channel add pr-${{ github.event.pull_request.number }} --self-assign
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

      # Upload the build to that channel
      - name: Upload to Capgo
        run: bunx @capgo/cli@latest bundle upload --channel pr-${{ github.event.pull_request.number }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

      # Post a comment with testing instructions (only on PR open)
      - name: Comment on PR
        if: github.event.action == 'opened'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: ${{ github.event.pull_request.number }},
              body: '📱 **Test this PR on device:**\n\nOpen your app and switch to channel: `pr-${{ github.event.pull_request.number }}`\n\nUse the shake menu or call `setChannel()` from your app.'
            })

La chiave è il --self-assign flag durante la creazione del canale. Questo consente ai tester di passare al canale dall'interno dell'app utilizzando il setChannel() API.

Configurazione del token Capgo

1. Vai alla tua dashboard di Capgo
2. Vai a Impostazioni > Chiavi API
3. Genera una nuova chiave con all permessi
4. Aggiungila come CAPGO_TOKEN nei segreti del tuo repository GitHub

Come i tester cambiano canale

I tester possono passare a un canale PR in due modi:

Opzione 1: Shake Menu (la più semplice)

Abilita il menu shake con selettore di canale nella configurazione Capacitor:

// capacitor.config.ts
const config: CapacitorConfig = {
  // ... your other config
  plugins: {
    CapacitorUpdater: {
      shakeMenu: true,
      allowShakeChannelSelector: true
    }
  }
};

I tester scuotono il dispositivo per aprire il menu di debug, che mostra un elenco dei canali disponibili con una barra di ricerca. Trovano il canale della loro PR (ad es., pr-123), toccano per selezionarlo e l'app scarica e applica automaticamente l'aggiornamento. Una volta terminato il test, scuotono di nuovo e tornano alla produzione.

Il menu shake gestisce l'intero flusso automaticamente:

1. Recupera tutti i canali auto-assegnabili tramite listChannels()
2. Mostra i canali con ricerca per trovare PR specifiche
3. Scarica l'aggiornamento dopo la selezione
4. Richiede il reload con le opzioni “Ricarica ora” / “Più tardi”

Opzione 2: UI del selettore di canali personalizzato

Crea un selettore di canali nell'app che elenchi i canali PR disponibili e consenta ai tester di sceglierne uno. Questo utilizza due API chiave:

• listChannels() - Recupera tutti i canali con auto-assegnazione abilitata
• setChannel() - Passa il dispositivo al canale selezionato

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Get all available channels (including PR channels)
async function getAvailableChannels() {
  const { channels } = await CapacitorUpdater.listChannels();

  // Filter to show only PR channels
  const prChannels = channels.filter(c => c.name.startsWith('pr-'));

  return prChannels;
}

// Switch to a specific PR channel
async function switchToChannel(channelName: string) {
  await CapacitorUpdater.setChannel({
    channel: channelName,
    triggerAutoUpdate: true  // Immediately check for updates
  });
}

// Return to production
async function switchBackToProduction() {
  await CapacitorUpdater.unsetChannel({});
}

// Get current channel
async function getCurrentChannel() {
  const { channel } = await CapacitorUpdater.getChannel();
  return channel;
}

Con questi elementi puoi creare una semplice UI:

// Example: List PR channels and let user select
const channels = await getAvailableChannels();
const current = await getCurrentChannel();

// Display channels in your UI
channels.forEach(channel => {
  console.log(`${channel.name} ${channel.name === current ? '(current)' : ''}`);
});

// When user selects a channel
await switchToChannel('pr-123');

Per un esempio completo di componente React, consulta il nostro articolo sul channel surfing.

Pulizia dei canali PR

Quando una PR viene mergiata o chiusa, dovrai pulire il channel. Aggiungi un altro workflow:

name: Cleanup PR Preview
on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Delete PR Channel
        run: bunx @capgo/cli@latest channel delete pr-${{ github.event.pull_request.number }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Questo rimuove il canale quando la PR viene chiusa, mantenendo pulita la lista dei canali.

Compatibilità versioni

Le anteprime PR funzionano solo se il bundle JavaScript è compatibile con la versione nativa installata. Se la PR include modifiche native a code (nuovi plugin Capacitor, modifiche iOS/Android), i tester avranno bisogno di un nuovo Native Build.

Capgo controlla automaticamente la compatibilità delle versioni. Se il bundle di una PR punta a una versione nativa diversa da quella installata, l'aggiornamento non verrà applicato. Questo evita crash dovuti a code incompatibili.

Per le PR che richiedono modifiche native, dovrai distribuire una nuova build su TestFlight/Play Store. Le anteprime PR sono ideali per modifiche a JavaScript, CSS e asset che non toccano code.

Chi trae vantaggio dalle anteprime PR

QA Engineer

• Testa le feature subito dopo l'apertura delle PR
• Passa tra diverse PR senza reinstallare
• Verifica fix e regressioni su dispositivi reali
• Niente più attese per l'elaborazione di TestFlight

Product manager

• Recensisci le feature prima del merge
• Dai feedback direttamente sulla PR
• Verifica che l'implementazione rispetti i requisiti
• Riduci i tempi di review

Developer

• Ricevi feedback più rapidi sulle modifiche
• Fai demo istantanee agli stakeholder
• Debugga i problemi con utenti specifici
• Meno tempo per gestire build beta

Confronto: Tradizionale vs PR Previews

Best practice

1. Nomina i canali in modo chiaro: Usa pr-{number} convenzione per identificarli facilmente
2. Pulizia automatica: Elimina sempre i canali quando chiudi le PR
3. Limita l'accesso: Abilita lo shake menu solo nelle build debug/staging
4. Documenta il processo: Aggiungi istruzioni di test al template della PR
5. Gestisci gli errori con eleganza: Verifica che la creazione del channel sia riuscita prima di postare commenti

Quando non usare le PR preview

Le PR preview servono per modifiche JS/CSS. Se la tua PR include:

• Nuovi plugin Capacitor
• Modifiche native iOS di code
• Modifiche native Android di code
• Aggiornamenti delle dipendenze che impattano le build native

Per queste modifiche servirà la distribuzione tradizionale tramite TestFlight/Play Store.

Combinazione con Channel Surfing

Le anteprime PR funzionano al meglio se combinate con il channel surfing. La tua app può avere:

• production - Release stabili per tutti gli utenti
• beta - Accesso anticipato per gli utenti opt-in
• pr-123 - Anteprime di funzionalità per PR specifiche

I tester con build di produzione possono passare a qualsiasi canale PR, testare la funzionalità e poi tornare indietro, tutto con la stessa app installata.

Risorse

• Documentazione Capgo Live Updates
• Documentazione sui canali
• Guida alla gestione dei canali
• Riferimento comandi CLI
• Pagina soluzioni PR Preview

Conclusione

Le PR preview cambiano il modo in cui il tuo team rivede e testa le funzionalità mobile. Invece di aspettare l'elaborazione di TestFlight e gestire più build beta, i tester possono passare a qualsiasi canale PR in pochi secondi usando l'app che hanno già installata.

Il setup è minimo — basta un solo file di workflow GitHub Actions — e i vantaggi si sommano in tutto il team. Il QA non resta bloccato, i product manager fanno review più velocemente e i developer ricevono feedback più rapidi.

Inizia aggiungendo il workflow a un repository e scopri come cambia il tuo processo di revisione.

Continua da Trasforma ogni pull request in una preview installabile

Se stai usando Trasforma ogni pull request in una preview installabile per pianificare il routing dei canali e il rollout graduale, connettilo a Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Soluzione Beta Testing per il workflow di prodotto nella Soluzione Beta Testing, e Soluzione Version Targeting per il workflow di prodotto nella Soluzione Version Targeting.