Checkliste für die Ersteinrichtung

Fertiggestellt Onboarding. Konfiguriere jetzt Capgo einmal. Danach besteht der tägliche Workflow nur aus upload → testen → deployen.

Erstelle zuerst einen neuen Store-Build

Das Installieren des Capgo Plugins in deinem Projekt reicht nicht aus. OTA-Updates funktionieren nur auf Geräten mit einer nativen App, die das Plugin bereits enthält.

Nachdem du Capgo hinzugefügt und CapacitorUpdater.notifyAppReady():

1. Ausführen npx cap sync
2. Erstelle eine neue iOS / Android Binary
3. Einreichung bei App Store, Play Store, TestFlight oder internem Vertrieb

Nutzer einer älteren Store-Build-Version ohne das Plugin erhält niemals Live Updates. Das Hochladen von Bundles zu Capgo betrifft nur Geräte mit einer Capgo-aktivierten Binary.

Siehe auch Fehlerbehebung.

Regel: Channels sind Release-Lanes (development, production), keine Tickets, Features oder Entwicklernamen.

---

Checkliste für die Ersteinrichtung

1. Channels erstellen: Wähle das kleinste passende Set (siehe unten).

2. Standard-Upload-Channel festlegen in App-Einstellungen:

   • Solo-App → production
   • Team → development

3. Production-Channel: öffentlich an, Gerät selbst auf aus, Updates bei Native Build blockieren, Auto-Update-Schutz an major.

4. Test-Channel (development / staging): public off, device self-set on für QA.

5. Upload aus der CI mit --delta (Checksummen und Native Build-Abhängigkeiten erfolgen automatisch):

   npx @capgo/cli@latest bundle upload \
     --channel development \
     --bundle "1.8.0-${BUILD_NUMBER}" \
     --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
     --delta

   Der --bundle Wert musst muss gültig sein Semantic Versioning. Validierung im SemVer-Tester vor dem Upload.

6. In Produktion deployen erst nach dem Testen, über das Dashboard oder CLI.

7. Team & Sicherheit: einmal einladen, minimale Rechte, 2FA für die Org, ein API Key in der CI.

Verschlüsselung, min_update_versionMetadaten und Preview off außer es gibt einen triftigen Grund.

---

Wähle deine Größe

Einfach: 1 App, 1 Channel: production

Team: development + production. Upload auf dev, Deploy auf prod.

Native Versionen: Channels nur bei Bedarf hinzufügen, z. B. production-9.0 + test-9.0. Store-User auf dem Haupt-Production-Channel halten.

Viele Apps: gleiches einfaches Modell pro App (meistens ein production pro App). Erstelle keine extra Channels, nur weil die Orga groß ist.

Release Train (optional): staging → rc → production. Dasselbe Template für jede App, die es benötigt.

Achtung

Verwende keine Channels, die nach Tickets, Personen oder CI-Variablen benannt sind, wie zum Beispiel ${inputs_capgo_channel}.

---

Bundle-Name vs. Kommentar

Bundle-Namen sind erforderlich zu befolgen Semantic VersioningCapgo nutzt SemVer für Kompatibilitätsprüfungen, Channel-Auto-Update-Regeln und Rollbacks. Validieren Sie jeden Namen in der SemVer-Tester vor dem Upload.

• Name = SemVer aus der CI, z. B. 1.8.0, 1.8.0-beta.1, oder 1.8.0-20260629.42
• Kommentar = Freitext für Menschen → commit abc1234 run 28059070270

Nutze SemVer Pre-release- Labels (der Teil nach -) wenn du viele Builds unter derselben MAJOR.MINOR.PATCH. Zum Beispiel: Behalte 1.8.0 und füge das Datum oder den Build-Counter im Pre-Release hinzu: 1.8.0-20260629.1, 1.8.0-beta.2. Erfinde keine eigenen Formate wie fix-login-bug oder 2.5.2026062306. Diese sind kein gültiges Semver, was zu Fehlern beim Upload oder unvorhersehbarem Verhalten führt.

Schreibe Release Notes in --comment, nicht in den Bundle-Namen.

Siehe auch Version Targeting und Bundle Versioning.

---

Delta Upload

--delta Uploads Delta-Dateien damit Geräte statt des gesamten Bundles jedes Mal nur geänderte Dateien downloaden. Der Checksum wird immer automatisch berechnet. Du musst kein Checksum-Flag übergeben.

Standard: --delta (Delta-Dateien + ZIP-Backup)

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --delta

Dies ist die empfohlene Standardeinstellung für die meisten Apps. Capgo speichert die Delta-Dateien und behält das vollständige ZIP als Backup. Geräte mit einer alten Plugin-Version ohne Delta-Support nutzen das ZIP. Gut geeignet, wenn Speicherkosten keine Priorität haben.

Speicherplatzersparnis: --delta-only

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
  --delta-only

Nutzt --delta-only wenn du möchtest, zu Capgo Speicherplatz reduzierenmöchtest. Es werden nur die Delta-Dateien gespeichert, nicht das komplette ZIP. Ideal für große Apps oder hohes Upload-Aufkommen, um Speicherplatz zu sparen.

Trade-off: Ohne das ZIP-Backup auf dem Server bist du rein auf Delta-Dateien angewiesen. Geräte mit alten Plugin-Versionen ohne Delta-Support können nicht updaten. Überspringen, --delta-only außer du benötigst die Speicherplatzersparnis wirklich.

Keine zusätzliche Plugin-Konfiguration auf dem Gerät nötig. Der Updater liest die Liste der Delta-Dateien und lädt nur die geänderten Dateien herunter.

Tipp

Siehe Delta-Updates zur Fehlersuche und directUpdate Verhalten.

---

Täglicher Workflow

Upload to development (--delta)
  → test
  → deploy to production
  → don't touch channel settings again

---

Häufige Fehler

Fehler	Lösung
OTA vor einem neuen Store-Release erwarten	Native App nach Plugin-Installation neu bauen und deployen
Bundle hochladen, aber nicht auf einen Channel deployen	Bundle einem Channel zuweisen (z. B. production)
Pro Feature, Ticket oder Developer ein eigener Channel	Nur permanente Release-Lanes nutzen
Dynamische CI-Channelnamen	Feste Namen: development, production
Zu viele Channels für eine einfache App	Mit 1–2 Channels starten
Geräte-Einstellung in der Production	In Production aus, in Test-Channels an
Überspringen --delta	Füge --delta für Uploads; nutze --delta-only nur, wenn du Speicherplatz sparen willst
Non-SemVer Bundle-Namen	Folgen Semantic Versioning und validiere im SemVer-Tester
Änderung des Versionierungsschemas im Zeitverlauf	SemVer beibehalten; Pre-release-Labels für Extra-Builds nutzen (1.8.0-20260629.1)
Metadata / Preview ohne Grund aktiviert	Standardmäßig deaktiviert

---

Mehr erfahren

Channels Defaults, Priorisierung und Routing.

Delta-Updates Warum und wie man --delta nutzt.

CI/CD Upload und Deployment automatisieren.

Bundles Checksum, Dependencies und Metadaten.