Capgo Release Management

Ship, promote, roll back, and clean up Capgo OTA bundles from the CLI.

Facts below were checked against @capgo/cli 8.77 (October 2026). Every command accepts -a, --apikey. The appId can be omitted inside a Capacitor project.

When to Use

TRIGGER when:

• The user uploads, lists, deletes, or cleans up bundles, or asks which version a channel serves.
• The user creates or configures channels, promotes staging to production, starts, pauses, or rolls back a progressive rollout, or rolls back a bad release.
• The user asks whether a change is OTA-safe (bundle compatibility, bundle releaseType).
• The user sets up bundle encryption (key create, key save, --key-v2).

Do not use when:

• The work is app-side updater code or config (notifyAppReady, autoUpdate, setChannel). Use capgo-live-updates.
• A native binary is needed. Use capgo-native-builds.
• The user manages organizations, members, 2FA, or API-key policy. Use capgo-organization-management.
• The user wants an end-to-end release pipeline design. Use capgo-release-workflows.

Command Map

All of these are npx @capgo/cli@latest <command>. Commands that do not exist (they come from old docs or other tools): channel create, bundle revert, upload --sign, key verify, and a top-level capgo upload without bundle.

Procedure

1. Inspect first

npx @capgo/cli@latest channel list com.example.app
npx @capgo/cli@latest channel currentBundle production com.example.app --quiet
npx @capgo/cli@latest bundle releaseType com.example.app --channel production

Report the current live version and the OTA/native verdict before you change anything. If the verdict is native, stop and hand off to capgo-native-builds (or the user's native pipeline).

2. Upload

npm run build
npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel staging --comment "$(git rev-parse --short HEAD)"

• The version comes from package.json unless you pass --bundle <semver>. It must be unique, greater than 0.0.0, and never a previously deleted version.
• Use --delta for instant-apply apps. The CLI refuses delta uploads with more than 10,000 files. Use --no-delta in that case.
• Use --fail-on-incompatible in CI. Use --accept-incompatible only when the JS guards missing plugins. These two flags and --ignore-metadata-check cannot be combined.

3. Promote and roll out

• Promote: npx @capgo/cli@latest channel promote staging production com.example.app. It runs the same compatibility checks as channel set --bundle.
• Gradual rollout: upload with --rollout <pct>, then watch the stats before you run --rollout-promote.
• Only change which channel is the default (channel set <ch> --state default, or channel add --default) when the user explicitly wants to move production traffic.

4. Roll back

npx @capgo/cli@latest bundle list com.example.app
npx @capgo/cli@latest channel set production com.example.app --bundle 1.4.2
# or, during a rollout:
npx @capgo/cli@latest channel set production com.example.app --rollout-rollback

Devices pick up the change on their next update check.

5. Encryption (optional, for sensitive apps)

npx @capgo/cli@latest key create        # writes .capgo_key_v2 (private) + .capgo_key_v2.pub, saves the public key to config
npx cap sync                             # the public key must ship in the native app
npx @capgo/cli@latest bundle upload com.example.app --key-v2 ./.capgo_key_v2 --channel production

In CI, keep the private key in the CI secret store, write it to ./.capgo_key_v2 in the job, and pass the same --key-v2 ./.capgo_key_v2. The private key never leaves the runner. Add .capgo_key_v2 to .gitignore and never commit it. A changed key needs a new native build: devices with the old publicKey fail with key_id_mismatch.

Traps

• On a channel that has a rollout configured, a plain bundle upload --channel production sets the rollout target, and stable is unchanged. Replace stable explicitly with channel set --bundle.
• bundle cleanup --ignore-channel also deletes the linked channels. Never add it without asking.
• bundle delete is permanent, and the deleted version cannot be reused. Prefer relinking an older bundle to roll back.
• releaseType only sees native package metadata, not raw ios/ or android/ edits.
• --self-assign on upload changes the channel's settings, not just this bundle.

Verification

1. npx @capgo/cli@latest channel currentBundle production com.example.app --quiet prints the expected version.
2. npx @capgo/cli@latest probe --platform ios (run in the project) reports whether an update would be served.
3. npx @capgo/cli@latest app debug com.example.app shows a test device downloading and setting the bundle.
4. For encrypted uploads, a device on the new native build applies the update with no key_id_mismatch error.

Error Handling

Resources

• Bundle reference: https://capgo.app/docs/cli/reference/bundle/
• Channel reference: https://capgo.app/docs/cli/reference/channel/
• Progressive rollouts: https://capgo.app/docs/live-updates/progressive-rollouts/
• Encryption: https://capgo.app/docs/live-updates/encryption/
• Compatibility: https://capgo.app/docs/live-updates/compatibility/