capgo-native-builds

What this skill does

# Capgo Native Builds

Use this skill when the user wants Capgo to build native iOS or Android binaries in the cloud.

## When to Use This Skill

- The user asks for a Capgo Cloud Build, native build, signed IPA/APK/AAB, TestFlight/App Store build, Play Store build, or temporary build download link.
- The user needs Capgo CLI login, build API-key setup, or help choosing between `login`, `CAPGO_TOKEN`, and `-a, --apikey`.
- The user needs iOS build onboarding, Apple signing setup, Android keystore setup, Play service account setup, or credential rotation.
- The user asks about `build init`, `build request`, `build credentials save`, `build credentials update`, `build credentials list`, `build credentials clear`, or `build credentials migrate`.

Do not use this skill for JavaScript-only OTA update uploads, generic CI/CD setup, or local native builds that do not involve Capgo Cloud Build.

## Operating Rules

- Use `npx @capgo/cli@latest` in user-facing commands.
- Treat API keys, P12 passwords, keystore passwords, App Store Connect keys, and Play service account JSON as secrets. Use placeholders in examples and do not echo secret values back to the user.
- Prefer Capgo CLI build flows before inventing custom CI scripts.
- Confirm the platform, app ID, project path, desired output destination, and whether the user wants store upload or a temporary download link.
- Credentials are stored locally by the CLI and are only sent to Capgo for the build job. They are not stored permanently on Capgo servers and are deleted after the build process. See the [Capgo CLI credentials documentation](https://capgo.app/docs/cli/cloud-build/credentials/).

## First Checks

Before requesting a build, verify:

- The project is a Capacitor app and has the native folder for the target platform (`ios/` or `android/`).
- The Capgo app exists. If needed, add it first:

```bash
npx @capgo/cli@latest app add com.example.app
```

- The user has a Capgo API key with permission to trigger native builds for the app.
- Signing credentials exist or the workflow will create/save them before `build request`.
- The output destination is clear:
  - Store upload: provide App Store Connect credentials for iOS or Play config for Android.
  - Download link only: use `--output-upload`, optionally with `--output-retention <duration>`.

## Authentication and Login

Use `login` when the machine should remember the Capgo API key:

```bash
npx @capgo/cli@latest login
npx @capgo/cli@latest login YOUR_API_KEY
npx @capgo/cli@latest login --local YOUR_API_KEY
```

Authentication precedence for build commands:

1. `-a, --apikey <apikey>` on the command.
2. `CAPGO_TOKEN` environment variable.
3. Local key saved by `login --local` in `.capgo`.
4. Global key saved by `login` in `~/.capgo`.

Use `CAPGO_TOKEN` for CI secrets. Use `-a, --apikey` when creating a single copy-pasteable command for onboarding or support. Use `login --local` only when the key should stay scoped to this repository; verify `.capgo` is ignored by git.

## Recommended Build Flows

### iOS Fast Path: `build init`

For a first iOS cloud build, prefer the interactive onboarding command:

```bash
npx @capgo/cli@latest build init
```

If no key is saved, pass one explicitly:

```bash
npx @capgo/cli@latest build init -a YOUR_API_KEY
```

`build init` also has the alias `build onboarding`. It is best when the user wants the CLI to create and save iOS signing material with the fewest manual steps.

What it handles:

- Verifies the App Store Connect API key.
- Creates or reuses Apple signing assets where possible.
- Registers or reuses the bundle ID.
- Creates App Store provisioning profiles.
- Saves build credentials into the same local store used by `build request`.
- Can request the first cloud build at the end.
- Persists onboarding progress under `~/.capgo-credentials/onboarding/` so the user can resume.
- Saves recovery/support material under `~/.capgo-credentials/support/` after unexpected failures.

Use manual credential commands instead when the user already has certificates, profiles, or CI secrets prepared.

### Manual iOS Credential Save

Use this when the user already has Apple signing files:

```bash
npx @capgo/cli@latest build credentials save --appId com.example.app --platform ios \
  --certificate ./cert.p12 --p12-password "P12_PASSWORD" \
  --ios-provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey_KEYID.p8 --apple-key-id "KEY_ID" \
  --apple-issuer-id "ISSUER_UUID" --apple-team-id "TEAM_ID"
```

For apps with extensions or multiple targets, repeat `--ios-provisioning-profile` and map each bundle ID:

```bash
npx @capgo/cli@latest build credentials save --appId com.example.app --platform ios \
  --ios-provisioning-profile com.example.app=./App.mobileprovision \
  --ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision
```

For ad-hoc iOS builds, set the distribution mode and collect the IPA with `--output-upload`:

```bash
npx @capgo/cli@latest build credentials save --appId com.example.app --platform ios \
  --ios-distribution ad_hoc \
  --certificate ./cert.p12 \
  --ios-provisioning-profile ./adhoc.mobileprovision \
  --output-upload
```

### Manual Android Credential Save

Use this when the user already has Android signing files:

```bash
npx @capgo/cli@latest build credentials save --appId com.example.app --platform android \
  --keystore ./release.jks --keystore-alias "release-key" \
  --keystore-key-password "KEY_PASSWORD" \
  --keystore-store-password "STORE_PASSWORD" \
  --play-config ./service-account.json
```

If the user only needs an APK/AAB download link and not Play upload, save `--output-upload` and omit or override Play upload:

```bash
npx @capgo/cli@latest build credentials save --appId com.example.app --platform android \
  --keystore ./release.jks --keystore-alias "release-key" \
  --keystore-key-password "KEY_PASSWORD" \
  --keystore-store-password "STORE_PASSWORD" \
  --output-upload
```

Use `--android-flavor <flavor>` when the Android project has multiple product flavors.

### Request a Build

Use `build request [appId]` after login and credentials are ready:

```bash
npx @capgo/cli@latest build request com.example.app --platform ios --path .
npx @capgo/cli@latest build request com.example.app --platform android --path .
```

Useful request options:

- `--platform ios|android`: required.
- `--path <path>`: project directory, default is the current directory.
- `--build-mode debug|release`: defaults to release.
- `--ios-scheme <scheme>` and `--ios-target <target>` for custom Xcode projects.
- `--ios-distribution app_store|ad_hoc`.
- `--android-flavor <flavor>` for Android product flavors.
- `--output-upload` to create temporary IPA/APK/AAB download links.
- `--output-retention <duration>` from `1h` to `7d`.
- `--no-playstore-upload` to skip Play upload for an Android build. This requires `--output-upload`.
- `--skip-build-number-bump` when the project owns native build numbers itself.
- `--verbose` for support/debugging.

Example: collect an iOS ad-hoc IPA link:

```bash
npx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload \
  --output-retention 2d
```

Example: Android flavor with a download link instead of Play upload:

```bash
npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --android-flavor production \
  --output-upload \
  --no-playstore-upload
```

## Credential Management

Build credentials are stored globally in `~/.capgo-credentials/credentials.json` by default. Add `--local` to use `.capgo-credentials.json` in the project root. Never commit either credentials file.

List masked saved credentials:

```bash
npx @capgo/cli@latest build credentials list
npx @capgo/cli@latest build credentials list --appId com.example.app
npx @capgo/cli@latest build credentials list --local
```

Update only changed fields:

```bash
npx @capgo/cli@latest build credentials update