capgo-release-management

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

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

• 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

Devices pick up the change on their next update check.

5. Encryption (optional, for sensitive apps)

In CI, pass --key-data-v2 "$CAPGO_PRIVATE_KEY". 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/