capgo-live-updates

Capgo Live Updates

Wire @capgo/capacitor-updater into a Capacitor app, ship the first bundle, and keep rollback safe.

Facts below were checked against @capgo/capacitor-updater 8.52 and @capgo/cli 8.77 (October 2026).

When to Use

TRIGGER when:

• The user wants OTA / live updates, hotfixes without store review, or "Capgo" in a Capacitor app.
• The updater plugin needs installing, upgrading, or configuring in capacitor.config.*.
• The user asks about notifyAppReady, autoUpdate modes, directUpdate, autoSplashscreen, setChannel, getLatest, download, next, set, or reset.
• Updates upload fine but devices never get them, roll back, or loop.

Do not use when:

• The work is only CLI bundle, channel, rollout, or encryption-key commands. Use capgo-release-management.
• The user needs a signed IPA/APK/AAB from Capgo Cloud. Use capgo-native-builds.
• The user is moving from Capawesome Cloud (capawesome-live-update-migration) or Ionic Appflow (ionic-appflow-migration).
• The user wants the whole release pipeline (OTA, native builds, and store publishing). Use capgo-release-workflows.
• The request is about general CLI routing or MCP setup. Use capgo-cli-usage.

Reference Index

Only load a reference when its topic is in play.

File	Load when
references/configuration.md	Editing plugins.CapacitorUpdater in capacitor.config.*, choosing autoUpdate modes, self-hosted URLs
references/js-api.md	Writing manual update flows, listeners, channel switching, or rollback code
references/channels-and-rollouts.md	Channels, device self-assignment, progressive rollouts, version targeting
references/ci-cd.md	Uploading from GitHub Actions, GitLab CI, or another CI
references/troubleshooting.md	A device does not update, rolls back, or the backend returns an error code

Version Rule (read first)

The updater major version follows the Capacitor major version.

Capacitor	Install
8.x	npm install @capgo/capacitor-updater@latest (8.x line)
7.x	npm install @capgo/capacitor-updater@lts-v7
6.x	npm install @capgo/capacitor-updater@lts-v6
5.x	npm install @capgo/capacitor-updater@lts-v5
4.x	npm install @capgo/capacitor-updater@lts-v4

Capacitor 9 trap: Capacitor 9 is still prerelease (@capacitor/core@next). As of October 2026 there is no updater line for Capacitor 9. The 8.x line declares peerDependencies: @capacitor/core ^8.0.0. The @capgo/[email protected] on npm is an old Capacitor 5 release from 2023 and is marked deprecated, so never install it for Capacitor 9. Before you advise on a Capacitor 9 project, check the current tags with npm view @capgo/capacitor-updater dist-tags. If no Capacitor 9 line is listed, tell the user that.

Secrets and Confirmation

• Never ask the user to paste a Capgo API key, signing password, .p8 key, keystore, or service-account JSON into the chat. Ask them to run npx @capgo/cli@latest login themselves (it opens the browser or asks for the key in a masked prompt), or to set CAPGO_TOKEN in their shell or CI secret store.
• Do not put secrets in command arguments: they end up in shell history and process lists. Use environment variables, the saved login, or the CLI's interactive prompts.
• If a secret appears in the conversation anyway, do not repeat it, do not write it to a file, and tell the user to revoke it and create a new one.
• npx @capgo/cli@latest downloads and runs the newest CLI from npm. Run it only inside the user's project and with their go-ahead. In CI, pin an exact version.
• Ask before any command that changes remote state: uploading a bundle, changing or promoting a channel, deleting apps, bundles, channels, or keys, requesting a build that uploads to a store, and exporting or deleting credentials. Say what will change and for which app and channel.

Procedure

1. Inspect before editing

• Read package.json to get the @capacitor/core major and any existing @capgo/capacitor-updater.
• Read capacitor.config.ts|json to get appId, webDir, and any existing plugins.CapacitorUpdater.
• Find the app entry point (main.ts, main.tsx, App.vue setup, app.component.ts, and so on). That is where notifyAppReady() goes.
• Check for another OTA SDK. If one is present, stop and switch to the matching migration skill.

2. Connect the project (preferred path)

The guided onboarding registers the app, installs the plugin, patches the entry point, builds, uploads, and verifies on a device:

npx @capgo/cli@latest init

Ask the user to run it in their terminal: it signs in through the browser (or uses the key saved by login), asks for the app ID, and uploads a first bundle, so get their go-ahead first. Do not ask for the API key in the chat. In monorepos, add --package-json, --main-file, and --capacitor-config.

3. Manual install (when not using init)

npm install @capgo/capacitor-updater@latest   # pick the tag from the Version Rule table
npx cap sync
npx @capgo/cli@latest app add com.example.app

Minimum config (autoUpdate defaults to true, which equals "atBackground"):

plugins: {
  CapacitorUpdater: {
    autoUpdate: true,
  },
},

4. Call notifyAppReady() immediately

import { CapacitorUpdater } from '@capgo/capacitor-updater';

CapacitorUpdater.notifyAppReady();

• Call it at the very top of the entry file, before any network call or async init. If it is not called within appReadyTimeout (default 10000 ms), the bundle is marked failed and the previous one is restored.
• Crashes or API errors after this call do not trigger a rollback.
• bundle upload checks for this call and fails with notifyAppReady() is missing in the build folder (...). Fix the source. Only use --ignore-notify-app-ready / --no-code-check when the user accepts the rollback risk.

5. Ship a bundle

npm run build
npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production

For instant-apply modes ("atInstall", "onLaunch", "always"), upload with --delta and set autoSplashscreen: true with @capacitor/splash-screen launchAutoHide: false. See references/configuration.md.

6. Decide OTA vs native before each release

OTA can only change web assets. A new or upgraded native plugin, a Capacitor bump, or an edit under ios/, android/, or native config needs a store build. Check with:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production   # prints OTA or native

releaseType compares native package metadata only. It cannot see raw edits under ios/ or android/.

Traps

• Store compliance: OTA may change only interpreted web code and assets, and must not change the app's primary purpose. This comes from the interpreted-code clause in Apple's Developer Program License Agreement, App Review Guideline 2.5.2, and Google Play's Device and Network Abuse policy. Never use OTA to ship features that need review, and do not force an update to block app usage.
• Privacy manifest: iOS needs NSPrivacyAccessedAPICategoryUserDefaults with reason CA92.1 in PrivacyInfo.xcprivacy.
• Config key is publicKey, not privateKey. The private key (.capgo_key_v2) stays with the uploader and must never be in the app or the repo.
• resetWhenUpdate (default true) clears downloaded bundles when a new native build is installed. If you disable it, a store build older than the OTA bundle can break things.
• Testing on a dev build: a channel blocks dev, emulator, or prod devices by flag (disable_dev_build, disable_emulator, ...). Check the channel options before you assume the plugin is broken.
• Live reload (Ionic/Quasar): the updater does not serve live-reload URLs. Turn live reload off when testing updates.
• set() destroys the JS context. No code after it runs. Prefer next() to apply on the next background.
• Encryption is not secrecy: an unencrypted bundle is a public web asset. Encryption protects storage and delivery, but the public key ships in the app. See capgo-release-management for key create / key save.

Verification

1. npx @capgo/cli@latest doctor shows the installed updater version and flags anything outdated.
2. grep -rn "notifyAppReady" src/ finds exactly one early call in the entry point.
3. npx cap sync succeeds, then build and install the native app once on a real device.
4. Upload a visibly changed bundle. Run npx @capgo/cli@latest app debug com.example.app while you background and reopen the app. The log should show the check, the download, and set.
5. npx @capgo/cli@latest probe --platform ios (or android) reports whether the backend would deliver an update to this config and explains why not.

Error Handling

Symptom / string	Fix
notifyAppReady() is missing in the build folder	Add the call to the entry point, rebuild, then upload again
index.html is missing in the root folder of <dir>	--path points at the wrong folder. Use the built webDir
no_new_version_available	Normal: the device is already current
disable_auto_update_to_major / _minor / _patch	Channel strategy blocks the jump. Align CapacitorUpdater.version or change --disable-auto-update
cannot_update_via_private_channel	Enable self-assign on the channel (channel set <ch> --self-assign)
on_premise_app (HTTP 429)	The appId is not in Capgo, the app is flagged on-prem, or the plan is cancelled
Update downloads then reverts on next launch	notifyAppReady() ran too late or not at all, or the bundle throws before it runs

The full code list is in references/troubleshooting.md.

Resources

• Getting started: https://capgo.app/docs/getting-started/add-an-app/
• Plugin settings: https://capgo.app/docs/plugins/updater/settings/
• Plugin API: https://capgo.app/docs/plugins/updater/api/
• Update behavior: https://capgo.app/docs/live-updates/update-behavior/
• Common problems: https://capgo.app/docs/plugins/updater/commonproblems/