Getting Started

Get started with Capgo Cloud Build and create your first iOS or Android native build in minutes.

What You’ll Need

Before you begin, ensure you have:

• A Capacitor app that builds successfully locally
• Node.js 20 or higher installed
• A Capgo account with an active subscription
• Your app already registered in Capgo (run npx @capgo/cli@latest app add if not)
• Build credentials configured (certificates, keystores) - see below

Before Your First Build

⚠️ Setup Credentials First

Required before building: You must configure your build credentials (certificates for iOS, keystores for Android).

Setup Credentials →

Quick Start

1. Setup Build Credentials

   Before you can build, you need to save your credentials locally:

   For iOS:

   npx @capgo/cli build credentials save \
     --platform ios \
     --certificate ./cert.p12 \
     --p12-password "password" \
     --provisioning-profile ./profile.mobileprovision \
     --apple-key ./AuthKey.p8 \
     --apple-key-id "KEY123" \
     --apple-issuer-id "issuer-uuid" \
     --apple-team-id "team-id"

   For Android:

   npx @capgo/cli build credentials save \
     --platform android \
     --keystore ./release.keystore \
     --keystore-alias "my-key" \
     --keystore-key-password "key-pass" \
     --keystore-store-password "store-pass"

   See the full credentials guide for details.

2. Verify Local Build

   First, ensure your app builds locally without errors:

   # Build your web assets
   npm run build
   
   # Sync with Capacitor
   npx cap sync
   
   # Test local build (optional but recommended)
   npx cap open ios    # For iOS
   npx cap open android # For Android

3. Authenticate with Capgo

   Set your Capgo API key (if not already configured):

   npx @capgo/cli@latest login

   Or set the environment variable:

   export CAPGO_TOKEN=your_api_key_here

4. Run Your First Build

   Start with an Android debug build (fastest to test):

   npx @capgo/cli@latest build com.example.app \
     --platform android \
     --build-mode debug

   You’ll see real-time logs as your build progresses:

   ✔ Creating build job...
   ✔ Uploading project (15.2 MB)...
   ✔ Build started
   
   📝 Build logs:
   → Installing dependencies...
   → Running Gradle build...
   → Signing APK...
   ✔ Build succeeded in 3m 42s

5. Check Build Status

   The CLI will automatically poll and display the build status. Once complete, you’ll see:

   • Build time
   • Success/failure status
   • App submitted to App Store/Play Store (if credentials configured)

Understanding the Build Process

When you run the build command, here’s what happens:

flowchart LR
    A[Your Machine] -->|1. Zip Project| B[Local Temp]
    B -->|2. Upload| C[Capgo Cloud]
    C -->|3. Build| D[Build Server]
    D -->|4. Logs Stream| A
    D -->|5. Cleanup| E[Auto Delete]

1. Local Preparation - Your project is zipped (excluding node_modules and dotfiles)
2. Upload - The zip is uploaded to secure cloud storage (Cloudflare R2)
3. Build Execution - Your app builds on dedicated infrastructure
4. Log Streaming - Real-time logs stream to your terminal via Server-Sent Events
5. Automatic Cleanup - Build artifacts are deleted (Android: instant, iOS: 24 hours)

Your First Production Build

Once you’ve verified the process works, create a production build:

Android

npx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release

You’ll need to configure signing credentials first. See Android Build Configuration.

iOS

npx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode release

iOS builds require signing certificates and provisioning profiles. See iOS Build Configuration.

What Gets Built

Capgo Build only uploads the minimum files needed to compile your native app. Your full source code never leaves your machine.

What Gets Uploaded

Included	Description
ios/ or android/	The native platform folder you’re building
package.json, package-lock.json	Dependency manifest
capacitor.config.*	Capacitor configuration
resources/	App icons, splash screens
Native plugin code	Only the ios/ or android/ subfolder of each Capacitor plugin

What’s NOT Uploaded

Excluded	Why
node_modules/ (most of it)	Only native plugin code is included, not JS dependencies
src/	Your web source code stays local
dist/, www/, build/ (root level)	Already synced into the native folder via cap sync
.git/	Version control history
.gradle/, .idea/, .swiftpm/	Build caches and IDE settings
.env, secrets	Never uploaded

Note

Your built web assets (JS, CSS, HTML) are uploaded - but as part of the native folder. When you run npx cap sync, your web build is copied into ios/App/App/public/ or android/app/src/main/assets/public/. That’s why running cap sync before building is required.

Your Responsibilities

Before running npx @capgo/cli build:

1. Build your web assets - Run npm run build (or your framework’s build command)
2. Sync to native - Run npx cap sync to copy web assets into the native project
3. Commit dependencies - Ensure all native plugins are in package.json

What Capgo Build Handles

• Native iOS compilation (Xcode, Fastlane)
• Native Android compilation (Gradle)
• Code signing with your credentials
• App store submission (if configured)

Build Time & Costs

Build time is measured from start to completion:

• Android: Typically 3-5 minutes (1× billing multiplier)
• iOS: Typically 5-10 minutes (2× billing multiplier due to Mac hardware costs)

You only pay for actual build time used. No hidden fees.

Common Use Cases

CI/CD Integration

Add to your GitHub Actions workflow:

- name: Build native app
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
  run: |
    npm run build
    npx cap sync
    npx @capgo/cli@latest build ${{ secrets.APP_ID }} \
      --platform both \
      --build-mode release

Local Development

Test builds locally before committing:

# Quick debug build for testing
npm run build && npx cap sync
npx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode debug

Multi-Platform Builds

Build for both platforms by running two commands:

# iOS build
npx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode release

# Android build
npx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release

In CI/CD, you can run these in parallel jobs for faster builds.

Next Steps

Now that you’ve created your first build:

• Configure iOS builds - Set up certificates and profiles
• Configure Android builds - Set up keystores and Play Store
• Troubleshooting - Common issues and solutions
• CLI Reference - Complete command documentation

Need Help?

• Check the troubleshooting guide
• Join our Discord community
• Email support at support@capgo.app