SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscapgo-release-management

capgo-release-management

Deployment & operations

View repository

Updated 10-14 09:12

About this skill

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

Goal Command
Upload and link bundle upload [appId] --path ./dist --channel production (comma-separate several channels)
Is it OTA-safe? bundle releaseType [appId] --channel production prints OTA or native
Detailed native diff bundle compatibility [appId] --channel production [--text]
What is live channel currentBundle production [appId] --quiet
Promote channel promote staging production [appId]
Roll back channel set production [appId] --bundle <previous-version>
Rollout bundle upload ... --rollout 10, then channel set ... --rollout-percentage 50 / --rollout-promote / --rollout-rollback
Create channel channel add beta [appId] [--default] [--self-assign]
Channel policy channel set <ch> --disable-auto-update major|minor|patch|metadata|none plus --ios/--android/--dev/--prod/--emulator/--device toggles
List bundle list [appId], channel list [appId]
Clean up bundle cleanup [appId] --bundle 1.0 --keep 3
Delete bundle delete <version> [appId], channel delete <ch> [appId]
Preview QR app set [appId] --preview once, then get-qr [appId] --channel beta or bundle upload ... --qr-preview
Encryption keys key create, key save --key ./.capgo_key_v2.pub, key delete_old
Custom zip / external bundle zip [appId] --json, bundle encrypt <zip> <checksum>, bundle upload --external <url>

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

String Fix
❌ Version X already exists Bump --bundle, use --auto-bump patch, or pass --version-exists-ok in CI re-runs
Cannot upload the same bundle content The checksum is already on that channel. Rebuild with changes, or pass --ignore-checksum-check
Bundle NOT compatible with <channel> channel Native packages differ. Do a native build first, or use --accept-incompatible if the code guards it
notifyAppReady() is missing in the build folder (...) Fix the app entry point (see capgo-live-updates)
index.html is missing in the root folder of <dir> Wrong --path
Cannot find channel <name> Check channel list. Names are case sensitive
Channel strategy <x> is not known Use major, minor, patch, metadata, or none
No Capgo API key found. Run ... first, then retry this command. npx @capgo/cli@latest login, set CAPGO_TOKEN, or pass -a
Insufficient permissions for <key> The API key role is too low for this app. Ask an admin for an upload-capable key
Cannot upload bundle ( try again with --tus option) Retry with --tus, and raise --timeout for large bundles

Resources