Skip to content

One time setup checklist

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

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


  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):

    Terminal window
    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.


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.


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 uploads delta files 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 (delta files + zip backup)

Section titled “Default: --delta (delta files + zip backup)”
Terminal window
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 delta files and keeps the full zip as a backup. Devices on an old plugin version without Delta support use the zip. Good when storage cost is not your main concern.

Terminal window
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 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 delta files, and devices on an old plugin version without Delta support cannot update. Skip --delta-only unless you actually need the storage savings.

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


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

MistakeFix
Expecting OTA before a new store releaseRebuild and ship the native app after adding the plugin
Uploading a bundle but not deploying to a channelAssign the bundle to a channel (e.g. production)
Channel per feature, ticket, or developerUse permanent release lanes only
Dynamic CI channel namesFixed names: development, production
Too many channels for a simple appStart with 1-2 channels
Device self-set on productionOff for production, on for test channels
Skipping --deltaAdd --delta to uploads; use --delta-only only when you need to save storage
Non-semver bundle namesFollow semantic versioning and validate in the SemVer tester
Changing versioning scheme over timeKeep semver; use pre-release labels for extra builds (1.8.0-20260629.1)
Metadata / preview enabled without reasonLeave off by default
“New version available” message on a fresh installSkip it when current() returns bundle.id === "builtin" (see below)

App Store review: no update message on a fresh install

Section titled “App Store review: no update message on a fresh install”

Apple accepts apps that use Capgo. Reviewers reject the UI around it: a “new version available” or “updating” message shown at first launch.

This mostly affects self-hosted and manual setups, where your app runs its own version check and shows its own prompt.

The reviewer installs your store binary. It is older than your latest bundle, so the first check finds a bundle right away: your own server call returns it, or the updater finds it and emits updateAvailable. If your app shows a message then, the reviewer sees it.

Right after a fresh install or a native store update, the app runs the shipped bundle and current() returns bundle.id === "builtin". Skip your message in that case:

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

In any visible UI, avoid the words “update”, “live update”, “OTA”, “downloading”, and “installing”. See compliance.