capgo-release-management · diff
git:20260318.5bd0bc2 to git:20261011.86834d4
109 added, 26 removed. Audit A to A.
---
name: capgo-release-management
- description: Guides the agent through Capgo OTA release workflows including bundle uploads, compatibility checks, channels, cleanup, and encryption key setup. Use when managing Capgo bundle and channel operations. Do not use for native build requests or organization administration.
+ description: Runs Capgo OTA release operations with the CLI, including `bundle upload` (channels, delta, rollout, encryption, version bumps), `bundle compatibility` and `releaseType` checks, `channel add/set/promote/currentBundle/delete`, progressive rollouts and rollback, `bundle cleanup`, preview QR codes, and `key create/save` encryption setup. Use when the user ships, promotes, rolls back, or cleans up Capgo bundles, or hits upload errors such as "Version X already exists", "Bundle NOT compatible with <channel> channel", or "Cannot upload the same bundle content". Do not use for updater plugin wiring in app code (capgo-live-updates), native binaries (capgo-native-builds), or org/member administration (capgo-organization-management).
---
# Capgo Release Management
- Use this skill for Capgo OTA bundle, channel, and encryption-key workflows.
+ Ship, promote, roll back, and clean up Capgo OTA bundles from the CLI.
- ## When to Use This Skill
+ 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.
- - User wants to upload or manage a Capgo bundle
- - User needs channel targeting or compatibility checks
- - User wants bundle encryption or cleanup
+ ## When to Use
- ## Procedures
+ TRIGGER when:
- ### Step 1: Choose the Release Operation
+ - 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`).
- Use the matching command group:
+ Do not use when:
- - bundle upload/list/delete/cleanup
- - bundle compatibility/releaseType/zip/encrypt/decrypt
- - channel add/list/delete/set/currentBundle
- - key save/create/delete_old
+ - 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`.
- ### Step 2: Upload or Inspect Bundles
+ ## Command Map
- Prefer the current Capgo CLI:
+ | 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
+
```bash
- npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production
+ 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
```
- Use compatibility checks before channel changes when the user is unsure whether a bundle is safe for rollout.
+ 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).
- ### Step 3: Manage Channels
+ ### 2. Upload
- Use channel operations to set defaults, target specific bundles, and control rollout scope.
+ ```bash
+ npm run build
+ npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel staging --comment "$(git rev-parse --short HEAD)"
+ ```
- Only change the default channel when the user explicitly intends to move production traffic.
+ - 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.
- ### Step 4: Set Up Encryption
+ ### 3. Promote and roll out
- Use `key create` or `key save` before encrypted bundle uploads.
+ - 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.
- Keep private keys out of version control.
+ ### 4. Roll back
+ ```bash
+ 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)
+
+ ```bash
+ 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, 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
- - For upload failures, verify bundle version uniqueness and channel selection before retrying.
- - For compatibility failures, inspect package metadata and native version constraints before forcing a rollout.
- - For encrypted upload issues, verify the public key and session key flow before rotating keys.
+ | 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
+
+ - 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/