Skip to content
Capgo - Live Updates for Capacitor Apps Capgo

Getting Started

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

What You’ll Need

Section titled “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

Section titled “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

Section titled “Quick Start”

  1. Setup Build Credentials

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

    For iOS:

    Terminal window
    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:

    Terminal window
    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:

    Terminal window
    # 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):

    Terminal window
    npx @capgo/cli@latest login

    Or set the environment variable:

    Terminal window
    export CAPGO_TOKEN=your_api_key_here

  4. Run Your First Build

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

    Terminal window
    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

Section titled “Understanding the Build Process”

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

  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

Section titled “Your First Production Build”

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

Android

Section titled “Android”
Terminal window
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

Section titled “iOS”
Terminal window
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

Section titled “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

Section titled “What Gets Uploaded”
IncludedDescription
ios/ or android/The native platform folder you’re building
package.json, package-lock.jsonDependency manifest
capacitor.config.*Capacitor configuration
resources/App icons, splash screens
Native plugin codeOnly the ios/ or android/ subfolder of each Capacitor plugin

What’s NOT Uploaded

Section titled “What’s NOT Uploaded”
ExcludedWhy
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, secretsNever uploaded

Your Responsibilities

Section titled “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

Section titled “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

Section titled “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

Section titled “Common Use Cases”

CI/CD Integration

Section titled “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

Section titled “Local Development”

Test builds locally before committing:

Terminal window
# 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

Section titled “Multi-Platform Builds”

Build for both platforms by running two commands:

Terminal window
# 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

Section titled “Next Steps”

Now that you’ve created your first build:

Need Help?

Section titled “Need Help?”