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 bunx @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:

   bunx @capgo/cli@latest 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:

   bunx @capgo/cli@latest 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
   bun run build
   
   # Sync with Capacitor
   bunx cap sync
   
   # Test local build (optional but recommended)
   bunx cap open ios    # For iOS
   bunx cap open android # For Android

3. Authenticate with Capgo

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

   bunx @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):

   bunx @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[Mac Mini Silicon M4 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)

Build Infrastructure

Build execution runs on dedicated Mac Mini Silicon M4 machines:

• 10-core M4 CPU (4 performance cores, 6 efficiency cores)
• 10-core GPU
• 16-core Neural Engine
• 16GB of RAM
• macOS Tahoe 26.2

The build image supports Xcode 26.2, Android Studio 2025, and .NET 9/.NET 10 SDK workloads for native build pipelines.

Your First Production Build

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

Android

bunx @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

bunx @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 bunx 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 bunx @capgo/cli@latest build:

1. Build your web assets - Run bun run build (or your framework’s build command)
2. Sync to native - Run bunx 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
• iOS: Typically 5-10 minutes
• Infrastructure: Mac Mini Silicon M4 machines running macOS Tahoe 26.2

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

Common Use Cases

CI/CD Integration

Trigger Capgo Build automatically from your GitHub Actions workflow — on push, on tag, or with a manual button click. See the dedicated GitHub Actions guide for complete workflow examples covering manual triggers, tag-based releases, and continuous debug builds.

Local Development

Test builds locally before committing:

# Quick debug build for testing
bun run build && bunx cap sync
bunx @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
bunx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode release

# Android build
bunx @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