Zum Inhalt springen

Checkliste für die Ersteinrichtung

Du hast das Onboardingbeendet. Jetzt konfiguriere Capgo einmal. Danach sieht dein Workflow nur noch so aus: upload → testen → deployen.

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


Checkliste für die Ersteinrichtung

Section titled “One time setup checklist”
  1. Channels erstellen: wähle die kleinste passende Menge (siehe unten).

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

    • Solo-App → production
    • Team → development
  3. Production-Channel: public an, device self-set aus, block updates under native an, auto-update guard an major.

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

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

    Terminalfenster
    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 bevor du hochlädst.

  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_version, Metadaten und Preview aus außer du hast einen triftigen Grund.


Einfach: 1 App, 1 Channel: production

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

Native Versionen: füge Channels nur bei Bedarf hinzu, z. B. production-9.0 + test-9.0. Halte Store-User auf dem Haupt-Production-Channel.

Viele Apps: das gleiche einfache Modell pro App (meistens ein production jedem). 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.


Bundle-Namen sind erforderlich zu befolgen Semantic Versioning. Capgo nutzt SemVer für Kompatibilitätsprüfungen, Channel-Auto-Update-Regeln und Rollbacks. Validiere 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. Beispielsweise solltest du 1.8.0 und das Datum oder einen Build-Counter in der Pre-Release-Version hinzufügen: 1.8.0-20260629.1, 1.8.0-beta.2. Erfinde keine eigenen Formate wie fix-login-bug oder 2.5.2026062306. Diese entsprechen nicht dem Semver-Standard; Uploads schlagen fehl oder verhalten sich unvorhersehbar.

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

Siehe auch Version-Targeting und Bundle-Versioning.


--delta Uploads Delta-Dateien Damit laden Geräte nur geänderte Dateien statt jedes Mal das gesamte Bundle herunter. Der Checksum wird immer automatisch berechnet. Du musst kein Checksum-Flag übergeben.

Terminalfenster
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 die vollständige ZIP-Datei als Backup. Geräte mit einer alten Plugin-Version ohne Delta-Support nutzen die ZIP. Gut geeignet, wenn Speicherkosten keine Priorität haben.

Speicherplatz sparen: --delta-only

Abschnitt „Speicherplatz sparen: --delta-only“
Terminalfenster
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 den Speicherplatz von Capgo reduzierenmöchtest. Es werden nur die Delta-Dateien gespeichert, nicht das komplette ZIP. Wähle das für große Apps oder hohes Upload-Volumen, wo sich der Speicherplatz summiert.

Trade-off: Ohne das ZIP-Backup auf dem Server bist du voll auf Delta-Dateien angewiesen, und Geräte mit einer alten Plugin-Version ohne Delta-Support können nicht updaten. Überspringe das, --delta-only es sei denn, du brauchst die Speicherersparnis wirklich.

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


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

FehlerLösung
OTA vor einem neuen Store-Release erwartenNative App nach dem Hinzufügen des Plugins neu bauen und ausliefern
Bundle hochladen, aber nicht auf einen Channel deployenBundle einem Channel zuweisen (z. B. production)
Channel pro Feature, Ticket oder DeveloperNur permanente Release-Lanes nutzen
Dynamische CI-ChannelnamenFeste Namen: development, production
Zu viele Channels für eine einfache AppMit 1–2 Channels starten
Gerät setzt sich in Production selbstIn Produktion aus, für Test-Channels an
Überspringen --deltaFüge --delta für Uploads; nutze --delta-only nur, wenn du Speicherplatz sparen willst
Nicht-SemVer Bundle-NamenFolgen Semantic Versioning und validieren im SemVer Tester
Versioning-Schema über die Zeit ändernSemVer beibehalten; Pre-release-Labels für Extra-Builds nutzen (1.8.0-20260629.1)
Metadaten / Vorschau ohne Grund aktiviertStandardmäßig deaktiviert
„Neue Version verfügbar“-Meldung bei NeuinstallationÜberspringen, wenn current() gibt zurück bundle.id === "builtin" (siehe unten)

App Store Review: Keine Update-Meldung bei Neuinstallation

Abschnitt „App Store Review: Keine Update-Meldung bei einer Neuinstallation“

Apple akzeptiert Apps, die Capgo nutzen. Die Reviewer lehnen jedoch das UI darum ab: eine „Neue Version verfügbar“- oder „Update läuft“-Meldung beim ersten Start.

Dies betrifft meist Self-Hosted- oder manuelle Setups, bei denen deine App einen eigenen Version-Check durchführt und einen eigenen Prompt anzeigt.

Der Reviewer installiert dein Store-Binary. Da es älter als dein letztes Bundle ist, findet der erste Check sofort ein Bundle: Dein eigener Server-Call liefert es zurück, oder der Updater findet es und gibt aus updateAvailable. Wenn deine App dann eine Meldung anzeigt, sieht der Reviewer diese.

Direkt nach einer Neuinstallation oder einem Native Store Update führt die App das bereitgestellte Bundle aus und current() gibt zurück bundle.id === "builtin". Überspringe deine Nachricht in diesem Fall:

import { CapacitorUpdater } from '@capgo/capacitor-updater'
const { bundle } = await CapacitorUpdater.current()
if (bundle.id !== 'builtin') {
showNewVersionMessage()
}

Vermeide in der UI Begriffe wie „Update“, „live update“, „OTA“, „downloading“ oder „installing“. Siehe Compliance.