Mach aus jedem Pull Request eine installierbare Preview

Jedes Mobile-Dev-Team kennt den Schmerz: Eine Funktion ist bereit für die Review, aber um sie Stakeholdern zugänglich zu machen, muss man sich durch den Labyrinth der TestFlight- oder Google-Play-Beta-Reviews kämpfen. Was Minuten dauern sollte, wird zu Stunden des Wartens, Installierens und Verwaltens von Beta-Builds.

Was wäre, wenn deine Produktions-App die neuesten Änderungen aus jedem Pull Request direkt auf das Gerät ziehen könnte – ohne Neuinstallationen oder App-Store-Verzögerungen?

Genau das ist PR-Previews aktivieren. Wenn ein Entwickler einen Pull Request öffnet, erstellt eine GitHub Action einen eigenen Update-Channel und veröffentlicht die Änderungen. Alle, die die App installiert haben, können zu diesem Channel wechseln, das Feature testen und wieder zurückwechseln – ohne die App zu verlassen, die sie bereits haben.

Das TestFlight-Problem

Der klassische Workflow zum Testen von Mobile-Features sieht meistens so aus:

1. Entwickler öffnet PR - Code ist bereit fürs Review
2. Auf TestFlight warten - 15-30 Minuten Verarbeitungszeit
3. Suchen und installieren - Tester suchen nach dem richtigen Build
4. Testen und wiederholen - Jede Änderung bedeutet erneut Warten

Das schafft einen Engpass. QA wird durch das Warten auf Builds blockiert. Product Manager können Features nicht schnell verifizieren. Entwickler verlieren den Kontext, während sie auf Feedback warten. Branchenschätzungen zufolge kostet das etwa 340 $ pro PR an verlorener Produktivität.

So funktionieren PR-Previews

PR-Previews nutzen das Channel-System von Capgo, um Update-Streams pro PR zu erstellen. So läuft der Ablauf ab:

1. PR geöffnet oder aktualisiert - GitHub Action wird ausgelöst
2. Bundle hochgeladen - Deine JS/CSS-Änderungen gehen in einen PR-spezifischen Channel
3. Kommentar gepostet - Tester erhalten Anweisungen im PR
4. Sofortiges Testen - Kanäle wechseln, testen, zurückwechseln

Keine neuen App-Installationen. Keine TestFlight-Verzögerungen. Dieselbe Produktions-App kann aus verschiedenen Update-Kanälen laden.

PR-Previews einrichten

Bevor du PR-Previews implementieren kannst, muss dein Projekt mit Capgo Live Updates konfiguriert sein. Folge dem Capgo Quickstart-Guide , falls du es noch nicht getan hast.

GitHub Actions-Workflow

Erstellen .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.'
            })

Der Schlüssel ist das --self-assign -Flag bei der Erstellung des Kanals. Damit können Tester in der App auf den Kanal wechseln, indem sie das setChannel() API.

Einrichten des Capgo-Tokens

1. Gehe zu deinem Capgo Dashboard
2. Gehe zu Einstellungen > API-Keys
3. Erstelle einen neuen Key mit all Berechtigungen
4. Füge ihn als CAPGO_TOKEN in den Secrets deines GitHub-Repositoriums hinzu

So wechseln Tester zwischen Channels

Tester können auf zwei Arten in einen PR-Channel wechseln:

Option 1: Shake-Menü (am einfachsten)

Aktiviere das Shake-Menü mit Channel-Auswahl in deiner Capacitor-Konfiguration:

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

Tester schütteln ihr Gerät, um das Debug-Menü zu öffnen, das eine Liste der verfügbaren Channels mit Suchleiste anzeigt. Sie finden ihren PR-Channel (z. B. pr-123), tippen zur Auswahl und die App lädt das Update automatisch herunter und wendet es an. Nach dem Testen schütteln sie erneut und wechseln zurück zu Production.

Das Shake-Menü übernimmt den gesamten Ablauf automatisch:

1. Ruft alle selbst zuweisbaren Channels ab über listChannels()
2. Zeigt Channels mit Suche an, um bestimmte PRs zu finden
3. Lädt das Update nach der Auswahl herunter
4. Fordert zum Neuladen mit den Optionen „Jetzt neu laden“ / „Später“ auf

Option 2: Eigene Channel-Auswahl-UI

Integriere einen Channel-Switcher in deine App, der verfügbare PR-Channels auflistet und Testern die Auswahl ermöglicht. Dies nutzt zwei zentrale APIs:

• listChannels() - Ruft alle Channels mit aktivierter Selbstzuweisung ab
• setChannel() - Wechselt das Gerät zum ausgewählten Channel

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;
}

Mit diesen Bausteinen kannst du eine einfache UI erstellen:

// 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');

Ein vollständiges Beispiel für ein React-Component findest du in unserem Artikel zu Channel Surfing.

PR-Channels aufräumen

Wenn ein PR gemerged oder geschlossen wird, solltest du den Channel aufräumen. Füge einen weiteren Workflow hinzu:

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 }}

Dadurch wird der Channel entfernt, sobald der PR geschlossen wird, damit deine Channel-Liste sauber bleibt.

Versionskompatibilität

PR-Previews funktionieren nur, wenn das JavaScript-Bundle mit der installierten nativen Version kompatibel ist. Wenn dein PR native code Änderungen enthält (neue Capacitor Plugins, iOS/Android-Modifikationen), brauchen Tester einen neuen Native Build.

Capgo prüft die Versionskompatibilität automatisch. Wenn das Bundle eines PRs auf eine andere native Version abzielt als die installierte, wird das Update nicht angewendet. Das verhindert Abstürze durch inkompatible code.

Für PRs, die native Änderungen erfordern, musst du einen neuen TestFlight/Play Store Build ausliefern. PR-Previews eignen sich am besten für JavaScript-, CSS- und Asset-Änderungen, die kein natives code betreffen.

Wer profitiert von PR-Previews

QA-Engineers

• Features sofort testen, wenn PRs geöffnet werden
• Zwischen mehreren PRs wechseln, ohne neu zu installieren
• Fixes und Regressionen auf echten Geräten verifizieren
• Kein Warten mehr auf die TestFlight-Verarbeitung

Product Manager

• Funktionen vor dem Merge prüfen
• Feedback direkt im PR geben
• Prüfen, ob die Implementierung den Anforderungen entspricht
• Review-Zyklen verkürzen

Entwickler

• Schnelleres Feedback zu Änderungen erhalten
• Funktionen sofort Stakeholdern demonstrieren
• Probleme mit bestimmten Nutzern debuggen
• Weniger Zeit für das Management von Beta-Builds

Vergleich: klassisch vs. PR Previews

Best Practices

1. Channels klar benennen: Nutze pr-{number} Konvention zur einfachen Identifizierung
2. Auto-Cleanup: Channels immer löschen, wenn PRs geschlossen werden
3. Zugriff einschränken: Shake-Menü nur in Debug/Staging-Builds aktivieren
4. Den Prozess dokumentieren: Testanweisungen zu deinem PR-Template hinzufügen
5. Fehler sauber behandeln: Vor dem Posten von Kommentaren prüfen, ob die Channel-Erstellung erfolgreich war

Wann man PR Previews nicht nutzen sollte

PR-Previews sind für JavaScript/CSS-Änderungen gedacht. Wenn dein PR Folgendes enthält:

• Neue Capacitor-Plugins
• Native iOS-Änderungen für code
• Native Android-Änderungen für code
• Abhängigkeits-Updates, die native Builds betreffen

Für diese Änderungen benötigen Sie die klassische TestFlight-/Play-Store-Verteilung.

Kombination mit Channel Surfing

PR-Previews funktionieren am besten in Kombination mit Channel Surfing. Deine App kann Folgendes bieten:

• production - Stabile Releases für alle Nutzer
• beta - Early Access für Opt-in-Nutzer
• pr-123 - Feature-Previews für spezifische PRs

Tester mit Production-Builds können einfach in jeden PR-Channel wechseln, das Feature testen und dann zurückwechseln – alles mit derselben installierten App.

Ressourcen

• Capgo Live Updates Dokumentation
• Channels Dokumentation
• Channel-Surfing-Guide
• CLI Befehlsreferenz
• PR-Preview-Lösungsseite

Fazit

PR-Previews verändern, wie Ihr Team mobile Features prüft und testet. Statt auf die TestFlight-Verarbeitung zu warten und mehrere Beta-Builds zu verwalten, können Tester in Sekunden auf jeden PR-Channel wechseln – mit der App, die sie bereits installiert haben.

Die Einrichtung ist minimal – eine einzige GitHub Actions-Workflow-Datei – und die Vorteile summieren sich im gesamten Team. QA bleibt blockiert, Produktmanager prüfen schneller und Entwickler erhalten schnelleres Feedback.

Fangen Sie an, indem Sie den Workflow in ein Repository hinzufügen, und sehen Sie, wie sich Ihr Review-Prozess verändert.

Weiterlesen: Jeden Pull Request in eine installierbare Vorschau verwandeln

Wenn du es nutzt Mach aus jedem Pull Request eine installierbare Preview um Channel-Routing und Staged Rollout zu planen, verbinde es mit Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Beta-Testing-Lösung für den Produkt-Workflow in der Beta-Testing-Lösung, und Version-Targeting-Lösung für den Produkt-Workflow in der Version-Targeting-Lösung.