One time setup checklist

You finished onboarding. Now configure Capgo once. After that, daily work is only upload → test → deploy.

Ship a new store build first

Installing the Capgo plugin in your project is not enough. OTA updates only work on devices running a native app that already includes the plugin.

After you add Capgo and call CapacitorUpdater.notifyAppReady():

1. Run npx cap sync
2. Build a new iOS / Android binary
3. Submit to the App Store, Play Store, TestFlight, or your internal distribution

Users on an older store build without the plugin will never receive live updates. Uploading bundles to Capgo only affects devices on a Capgo-enabled binary.

See also troubleshooting.

Rule: channels are release lanes (development, production), not tickets, features, or developer names.

---

One time setup checklist

1. Create channels: pick the smallest set that fits (see below).

2. Set default upload channel in app settings:

   • Solo app → production
   • Team → development

3. Production channel: public on, device self-set off, block updates under native on, auto-update guard on major.

4. Test channel (development / staging): public off, device self-set on for QA.

5. Upload from CI with --delta (checksum and native dependencies are automatic):

   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

   The --bundle value must be valid semantic versioning. Validate it in the SemVer tester before you upload.

6. Deploy to production only after testing, from the dashboard or CLI.

7. Team & security: invite once, least permissions, 2FA for the org, one API key in CI.

Leave encryption, min_update_version, metadata, and preview off unless you have a clear reason.

---

Pick your size

Simple: 1 app, 1 channel: production

Team: development + production. Upload to dev, deploy to prod.

Native versions: add channels only when needed, e.g. production-9.0 + test-9.0. Keep store users on the main production channel.

Many apps: same simple model per app (usually one production each). Do not create extra channels just because the org is big.

Release train (optional): staging → rc → production. Same template on every app that needs it.

Caution

Do not use channels named after tickets, people, or CI variables like ${inputs_capgo_channel}.

---

Bundle name vs comment

Bundle names are required to follow semantic versioning. Capgo uses semver for compatibility checks, channel auto-update rules, and rollbacks. Validate every name in the SemVer tester before upload.

• Name = semver from CI, e.g. 1.8.0, 1.8.0-beta.1, or 1.8.0-20260629.42
• Comment = free text for humans → commit abc1234 run 28059070270

Use semver pre-release labels (the part after -) when you ship many builds under the same MAJOR.MINOR.PATCH. For example, keep 1.8.0 and add the date or build counter in the pre-release: 1.8.0-20260629.1, 1.8.0-beta.2. Do not invent custom formats like fix-login-bug or 2.5.2026062306. They are not valid semver and uploads will fail or behave unpredictably.

Put release notes in --comment, not in the bundle name.

See also version targeting and bundle versioning.

---

Delta upload

--delta uploads a manifest so devices download only changed files instead of the full bundle every time. Checksum is always computed automatically. You do not pass a checksum flag.

Default: --delta (manifest + zip backup)

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

This is the recommended default for most apps. Capgo stores the manifest and keeps the full zip as a backup. Good when storage cost is not your main concern.

Storage saving: --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

Use --delta-only when you want to reduce Capgo storage. Only the delta/manifest files are stored, not the full zip. Choose this for large apps or high upload volume where storage adds up.

Trade-off: without the zip backup on the server, you rely fully on the manifest path. Skip --delta-only unless you actually need the storage savings.

No extra plugin config is required on the device. The updater reads the manifest and fetches changed files only.

Tip

See Delta updates for troubleshooting and directUpdate behavior.

---

Daily workflow

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

---

Common mistakes

Mistake	Fix
Expecting OTA before a new store release	Rebuild and ship the native app after adding the plugin
Uploading a bundle but not deploying to a channel	Assign the bundle to a channel (e.g. production)
Channel per feature, ticket, or developer	Use permanent release lanes only
Dynamic CI channel names	Fixed names: development, production
Too many channels for a simple app	Start with 1-2 channels
Device self-set on production	Off for production, on for test channels
Skipping --delta	Add --delta to uploads; use --delta-only only when you need to save storage
Non-semver bundle names	Follow semantic versioning and validate in the SemVer tester
Changing versioning scheme over time	Keep semver; use pre-release labels for extra builds (1.8.0-20260629.1)
Metadata / preview enabled without reason	Leave off by default

---

Learn more

Channels Defaults, precedence, and routing.

Delta updates Why and how to use --delta.

CI/CD Automate upload and deploy.

Bundles Checksum, dependencies, and metadata.