From 0e897b75a8e1aa489f77985e65c9a18f52ef4163 Mon Sep 17 00:00:00 2001 From: Martin Donadieu Date: Fri, 7 Aug 2026 18:13:58 +0300 Subject: [PATCH] docs(cli): document bundle upload --auto-bump Document the new CLI flag for CI-friendly semver bumps from channel or latest remote versions. Co-authored-by: Cursor --- apps/docs/src/content/docs/docs/cli/commands.mdx | 1 + .../src/content/docs/docs/cli/reference/bundle.mdx | 11 +++++++++++ .../docs/docs/getting-started/cicd-integration.mdx | 14 ++++++++++++++ .../content/docs/docs/live-updates/channels.mdx | 2 ++ 4 files changed, 28 insertions(+) diff --git a/apps/docs/src/content/docs/docs/cli/commands.mdx b/apps/docs/src/content/docs/docs/cli/commands.mdx index 78061cb38..f0304d386 100644 --- a/apps/docs/src/content/docs/docs/cli/commands.mdx +++ b/apps/docs/src/content/docs/docs/cli/commands.mdx @@ -173,6 +173,7 @@ Optionally, you can give: * `--no-code-check` Ignore checking if notifyAppReady() is called in source code and index present in root folder. * `--display-iv-session` Show in the console the IV and session key used to encrypt the update. * `--bundle ` Bundle version number of the bundle to upload. +* `--auto-bump [level]` Auto-increment from the channel's linked bundle, else the latest remote app version. Level: `major`, `minor` (default), `patch` (alias `fix`), or `metadata`. Bumps until a free name is found (deleted names stay occupied). Cannot be combined with `--bundle`. * `--min-update-version ` Minimal version required to update to this version. Used only if the disable auto update is set to metadata in channel. * `--auto-min-update-version` Set the min update version based on native packages. * `--ignore-metadata-check` Ignores the metadata (node_modules) check when uploading. diff --git a/apps/docs/src/content/docs/docs/cli/reference/bundle.mdx b/apps/docs/src/content/docs/docs/cli/reference/bundle.mdx index 764112433..bb6309e90 100644 --- a/apps/docs/src/content/docs/docs/cli/reference/bundle.mdx +++ b/apps/docs/src/content/docs/docs/cli/reference/bundle.mdx @@ -28,6 +28,16 @@ Capgo never inspects external content. Add encryption for trustless security. npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production,beta ``` +Auto-bump the next free semver from the channel (or latest remote app version) when you do not pass `--bundle`. Useful in CI when `package.json` already matches a version Capgo has: + +```bash +npx @capgo/cli@latest bundle upload --channel=production --auto-bump +npx @capgo/cli@latest bundle upload --auto-bump major +npx @capgo/cli@latest bundle upload --auto-bump minor # default when the flag has no value +npx @capgo/cli@latest bundle upload --auto-bump patch # alias: fix +npx @capgo/cli@latest bundle upload --auto-bump metadata +``` + **Options:** | Param | Type | Description | @@ -54,6 +64,7 @@ npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel prod | **--no-code-check** | boolean | Ignore checking if notifyAppReady() is called in source code and index present in root folder | | **--display-iv-session** | boolean | Show in the console the IV and session key used to encrypt the update | | **-b** | string | Bundle version number of the bundle to upload | +| **--auto-bump** | string | Auto-increment from the channel's linked bundle, else the latest remote app version. Level: major, minor (default), patch (alias fix), or metadata. Bumps until a free name is found (deleted names stay occupied). Cannot be combined with --bundle (-b) | | **--link** | string | Link to external resource (e.g. GitHub release) | | **--comment** | string | Comment about this version, could be a release note, a commit hash, a commit message, etc. | | **--min-update-version** | string | Minimal version required to update to this version. Used only if the disable auto update is set to metadata in channel | diff --git a/apps/docs/src/content/docs/docs/getting-started/cicd-integration.mdx b/apps/docs/src/content/docs/docs/getting-started/cicd-integration.mdx index fda6c281d..1b869e599 100644 --- a/apps/docs/src/content/docs/docs/getting-started/cicd-integration.mdx +++ b/apps/docs/src/content/docs/docs/getting-started/cicd-integration.mdx @@ -148,6 +148,20 @@ This configuration does the following: Make sure to run semantic-release before building your app so that the updated version from `package.json` is included in your build through the capacitor.config. +### Auto-bump when the local version is already on Capgo + +Bundle names must be unique (deleted versions still occupy their name). If CI keeps uploading the same `package.json` version, the upload fails. Prefer bumping `package.json` (for example with semantic-release). When that is not practical, let the CLI pick the next free semver from the channel's linked bundle, or else the latest remote app version: + +```bash +npx @capgo/cli@latest bundle upload --channel=production --auto-bump +npx @capgo/cli@latest bundle upload --auto-bump major +npx @capgo/cli@latest bundle upload --auto-bump minor # default when the flag has no value +npx @capgo/cli@latest bundle upload --auto-bump patch # alias: fix +npx @capgo/cli@latest bundle upload --auto-bump metadata +``` + +Do not combine `--auto-bump` with `--bundle` / `-b`. See the [`bundle upload` reference](/docs/cli/reference/bundle/#bundle-upload) for the full option list. + ## Troubleshooting If you encounter issues with your Capgo CI/CD integration, here are a few things to check: diff --git a/apps/docs/src/content/docs/docs/live-updates/channels.mdx b/apps/docs/src/content/docs/docs/live-updates/channels.mdx index 4f11dfb0f..fe650ea67 100644 --- a/apps/docs/src/content/docs/docs/live-updates/channels.mdx +++ b/apps/docs/src/content/docs/docs/live-updates/channels.mdx @@ -209,6 +209,8 @@ It's important to note that bundles in Capgo are global to your app, not specifi When versioning your bundles, we recommend using [semantic versioning with Capgo's Semver Tester](/semver_tester/) and pre-release identifiers for channel-specific builds. For example, a beta release might be versioned as `1.2.3-beta.1`. +In CI, if the local version was already uploaded, use `npx @capgo/cli@latest bundle upload --auto-bump` (optionally `major`, `minor`, `patch`/`fix`, or `metadata`) so the CLI bumps from the channel's linked bundle until a free name is found. You cannot combine it with `--bundle`. See [CI/CD Integration](/docs/getting-started/cicd-integration/#auto-bump-when-the-local-version-is-already-on-capgo) and the [CLI reference](/docs/cli/reference/bundle/#bundle-upload). + This approach has several benefits: - It clearly communicates the relationship between builds. `1.2.3-beta.1` is obviously a pre-release of `1.2.3`.