capgo-native-builds

Capgo Native Builds

Build signed iOS and Android binaries on Capgo Cloud Build and deliver them to the stores or to a temporary download link.

Facts below were checked against @capgo/cli 8.77 and https://capgo.app/docs/builder/ (October 2026). The CLI describes native cloud builds as "limited beta".

When to Use

TRIGGER when:

• The user asks for a Capgo Cloud Build, a native build in the cloud, a signed IPA/APK/AAB, a TestFlight, App Store, or Play upload through Capgo, or a temporary build download link or QR code.
• The user runs or asks about build init, build request, build prescan, build needed, build last-output, build sync-ios-version, or any build credentials ... subcommand.
• A Capgo build fails on signing, provisioning, keystore, prescan, or store upload.

Do not use when:

• Only JavaScript/web assets change. That is an OTA release: use capgo-release-management, or capgo-live-updates for plugin wiring.
• The user builds locally in Xcode or Gradle, or on their own CI runners without Capgo Build. Use capacitor-ci-cd.
• The user needs store listing, metadata, or review prep. Use capacitor-app-store and capacitor-apple-review-preflight.
• The user is upgrading Capacitor itself. Use capacitor-app-upgrades.

Reference Index

Only load a reference when its topic is in play.

File	Load when
references/request-options.md	Building the exact build request flags: store submission, tracks, release notes, versioning, cache, Xcode version, prescan flags
references/credentials-and-ci.md	Saving, updating, exporting, or migrating credentials, and pushing them into CI secrets

Secrets and Confirmation

• Never ask the user to paste a Capgo API key, signing password, .p8 key, keystore, or service-account JSON into the chat. Ask them to run npx @capgo/cli@latest login themselves (it opens the browser or asks for the key in a masked prompt), or to set CAPGO_TOKEN in their shell or CI secret store.
• Do not put secrets in command arguments: they end up in shell history and process lists. Use environment variables, the saved login, or the CLI's interactive prompts.
• If a secret appears in the conversation anyway, do not repeat it, do not write it to a file, and tell the user to revoke it and create a new one.
• npx @capgo/cli@latest downloads and runs the newest CLI from npm. Run it only inside the user's project and with their go-ahead. In CI, pin an exact version.
• Ask before any command that changes remote state: uploading a bundle, changing or promoting a channel, deleting apps, bundles, channels, or keys, requesting a build that uploads to a store, and exporting or deleting credentials. Say what will change and for which app and channel.

Operating Rules

• Use npx @capgo/cli@latest in user-facing commands.
• API keys, P12 passwords, keystore passwords, .p8 keys, and Play service-account JSON are secrets. Use placeholders in examples. Never ask for them in the chat and never echo them back. If one is pasted into the chat, tell the user to revoke it and create a new one.
• Credentials are stored locally (~/.capgo-credentials/credentials.json, or .capgo-credentials.json with --local). They are uploaded only for the build job, and the temporary server copies are deleted when the build finishes. Never commit either file.
• Confirm these before requesting: platform, app ID, project path, flavor or scheme, and destination (store upload, download link, or both).

Auth and API-key precedence

The CLI resolves the key in this order:

1. -a, --apikey <key> on the command
2. The CAPGO_TOKEN environment variable
3. ~/.capgo, the global key saved by npx @capgo/cli@latest login
4. ./.capgo, the project key saved by login --local

Trap: a global key wins over a project-local key. If a repository must use a different org's key, set CAPGO_TOKEN. Make sure .capgo is git-ignored.

Procedure

1. Inspect

• ls ios android and confirm the target native folder exists and npx cap sync <platform> has run.
• Read capacitor.config.* for appId. It must match the iOS bundle ID and Android applicationId (prescan check shared/bundle-id-consistency).
• iOS: check the Xcode scheme and target names (default App) and any extensions that need their own provisioning profiles.
• Android: check android/app/build.gradle for productFlavors. If there is more than one flavor, --android-flavor is required.
• Check that the app exists: npx @capgo/cli@latest app list. Add it with npx @capgo/cli@latest app add com.example.app.

2. Decide whether a native build is needed at all

npx @capgo/cli@latest build needed com.example.app --channel production
# prints "yes" and exits 1 -> native build required
# prints "no" and exits 0 -> ship OTA instead
# exits 2 -> the command itself failed

It compares native package metadata only. Raw edits under ios/ or android/ still need a native build.

3. Set up credentials

First build, interactive (preferred):

npx @capgo/cli@latest build init        # alias: build onboarding

• iOS: verifies or creates the App Store Connect API key, then creates or reuses the certificate, bundle ID, and App Store provisioning profiles. It saves everything locally and can fire the first build. Progress persists under ~/.capgo-credentials/onboarding/, so the user can resume.
• Android: sets up the keystore. Google OAuth then provisions a GCP service account and sends the Play Console invite.
• macOS helper for the .p8 key: npx @capgo/cli@latest build credentials apple-key --appId com.example.app.

When the user already has signing files, use build credentials save instead. See references/credentials-and-ci.md.

4. Pre-flight

npx @capgo/cli@latest build prescan com.example.app --platform ios

Prescan runs automatically inside build request. Run it alone to fix problems before you upload anything. If one finding is intentional, skip only that check: --prescan-skip <check-id>. Avoid --no-prescan.

5. Request the build

# App Store / TestFlight (default ios distribution app_store)
npx @capgo/cli@latest build request com.example.app --platform ios --path .

# Android to Play internal track (default track internal, status draft)
npx @capgo/cli@latest build request com.example.app --platform android --path .

# Artifact only, no store upload
npx @capgo/cli@latest build request com.example.app --platform ios --ios-distribution ad_hoc --output-upload --output-retention 2d
npx @capgo/cli@latest build request com.example.app --platform android --no-playstore-upload --output-upload

The --output-retention range is 1h to 7d. The default TTL saved in credentials is 1h.

Traps

• Xcode / Capacitor 9: the Capgo Build docs list macOS Tahoe 26.2 with Xcode 26.2. You can pin with --xcode-version <major[.minor]> (or CAPGO_IOS_XCODE_VERSION). Capacitor 9 needs Xcode 27+. Capgo's docs and CLI 8.77 do not confirm an Xcode 27 builder. Before promising a Capacitor 9 iOS cloud build, check with --xcode-version 27 or current docs.
• --no-playstore-upload requires --output-upload. Otherwise the build has no destination.
• Ad hoc iOS skips the store. Use it with --output-upload when the App Store record does not exist yet.
• --submit-to-store-review changes the Android defaults to the production track with status completed. Confirm with the user before you add it.
• Build numbers auto-increment by default. If the project owns build numbers, add --skip-build-number-bump. Marketing versions can also auto-bump (--skip-marketing-version-bump turns this off).
• Build timeout defaults to 15 minutes. Raise it with npx @capgo/cli@latest app set com.example.app --build-timeout-minutes 60 (range 5 to 360).
• server.url left in capacitor.config (live reload) fails prescan ios/capacitor-server-url-shipped for store builds. Remove it rather than skipping the check.

Verification

1. npx @capgo/cli@latest build credentials list --appId com.example.app shows masked credentials for the target platform.
2. npx @capgo/cli@latest build prescan com.example.app --platform <p> --fail-on-warnings exits 0.
3. build request ends with a success status. With --output-upload it prints a download link and QR code. With --output-record /tmp/build.json, check npx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl.
4. Store path: the build appears in TestFlight or the Play Console track you chose.
5. Install the artifact on a device and check the version and build number.

Error Handling

String / symptom	Fix
No Capgo API key found. Run ... first, then retry this command.	The user runs npx @capgo/cli@latest login, or sets CAPGO_TOKEN
Insufficient permissions for <key> / prescan shared/apikey-permission	The key's role cannot request native builds for this app or org. Use a key with build rights
Missing required argument: --platform <ios|android>	Add --platform ios or --platform android
❌ No credentials found for this app and platform	Run build init or build credentials save --appId <id> --platform <p> .... Check --local versus the global store
Legacy provisioning profile format detected. Run: npx @capgo/cli build credentials migrate --platform ios	Run npx @capgo/cli@latest build credentials migrate --platform ios
Missing argument, you need to provide a appId, or be in a capacitor project	Pass the app ID positionally or run from the app root
output-retention must be a number with optional unit: s, m, h, d	Use 1h, 6h, 2d, and so on (max 7d)
Prescan ios/cert-profile-pairing / ios/profile-type-vs-mode	The profile does not embed the certificate or does not match app_store/ad_hoc. Regenerate it with build credentials ios-provisioning
Prescan ios/targets-covered	An extension has no profile. Add --ios-provisioning-profile <bundleId>=<path>
Android "Key alias not found" / wrong password	Check the alias and passwords. If they differ, pass both --keystore-key-password and --keystore-store-password
Multiple flavors error	Add --android-flavor <flavor>
Need diagnosis	Re-run with --verbose. --ai-analytics sends the failure logs to Capgo AI. --send-logs-to-support sends them to support

More fixes: https://capgo.app/docs/builder/troubleshooting/

Supporting Docs

• Build reference: https://capgo.app/docs/cli/reference/build/
• Getting started: https://capgo.app/docs/builder/getting-started/
• iOS: https://capgo.app/docs/builder/ios/ · Android: https://capgo.app/docs/builder/android/
• Credentials: https://capgo.app/docs/builder/credentials/ · Prescan: https://capgo.app/docs/builder/prescan/
• OTA vs native in CI: https://capgo.app/docs/builder/ci-ota-or-native/