Android Builds

Build and submit Android apps to the Google Play Store using Capgo’s secure cloud infrastructure.

Before You Build

⚠️ Setup Android Credentials First

Required: You must save your Android credentials before building release apps.

Setup Android Credentials →

How Android Builds Work

Android builds run in secure Cloudflare sandboxes:

• Infrastructure: Cloudflare Workers with containerized Android SDK
• Build Tool: Gradle with Android build tools
• Execution: Isolated sandbox environment per build
• Cleanup: Instant deletion after build completion
• Security: No persistent storage, complete isolation between builds

Prerequisites

Before building for Android, you need:

1. Development Environment (Local Testing)

• Android Studio installed locally (for initial keystore setup)
• Your app building successfully with npx cap open android
• Java JDK 17 or higher

2. Signing Keystore

For release builds, you need a signing keystore:

Build Type	Keystore Required	Purpose
Debug	No	Testing only, auto-generated
Release	Yes	Play Store submission

Creating a Keystore

If you don’t have a keystore yet, create one:

keytool -genkey -v \
  -keystore my-release-key.keystore \
  -alias my-key-alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

Answer the prompts:

• Password: Choose a strong password (save it securely!)
• Name: Your name or company name
• Organization: Your company name
• Location: Your city, state, country

Attenzione

Important: Keep your keystore file and passwords secure! If you lose them, you cannot update your app on the Play Store.

Build Configuration

Required Environment Variables

For release builds, set these credentials:

# Android Signing (Required for release)
ANDROID_KEYSTORE_FILE="<base64-encoded-keystore>"
KEYSTORE_KEY_ALIAS="my-key-alias"
KEYSTORE_KEY_PASSWORD="<key-password>"
KEYSTORE_STORE_PASSWORD="<store-password>"

# Play Store Publishing (Optional, for auto-submission)
PLAY_CONFIG_JSON="<base64-encoded-service-account-json>"

Generating Base64 Credentials

Keystore File:

base64 -i my-release-key.keystore | pbcopy

Play Store Service Account JSON:

base64 -i play-store-service-account.json | pbcopy

The base64 string is now in your clipboard.

Play Store Service Account Setup

To enable automatic Play Store uploads:

1. Go to Google Play Console → Setup → API Access
2. Click “Create new service account”
3. Follow the link to Google Cloud Console
4. Create a service account with “Service Account User” role
5. Create a JSON key for the service account
6. Download the JSON file
7. Go back to Play Console and grant access to the service account
8. Give it “Release to production, exclude devices, and use Play App Signing” permissions

Building for Android

Debug Build

Perfect for testing without signing:

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

This creates a debug APK that can be installed on any device for testing.

Release Build

For Play Store submission:

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

Requires signing credentials to be configured as environment variables.

CI/CD Integration

GitHub Actions Example

name: Build Android App

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build web assets
        run: npm run build

      - name: Sync Capacitor
        run: npx cap sync android

      - name: Build Android app
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_STORE_CONFIG }}
        run: |
          npx @capgo/cli@latest build ${{ secrets.APP_ID }} \
            --platform android \
            --build-mode release

Build Process Details

What Happens During an Android Build

1. Sandbox Initialization (~5 seconds)

   • Secure container spun up
   • Android SDK and Gradle loaded
   • Isolated file system created

2. Project Setup (~20 seconds)

   • Project zip downloaded from R2
   • Extracted to build directory
   • Signing credentials injected

3. Gradle Build (2-4 minutes)

   • Dependencies downloaded
   • APK/AAB compilation
   • ProGuard/R8 optimization (release mode)
   • Code signing applied

4. Play Store Upload (30 seconds, if configured)

   • AAB uploaded to Play Console
   • Release track configured
   • Submission initiated

5. Cleanup (immediate)

   • All files deleted
   • Container destroyed
   • No artifacts retained

Build Stack

Our Android build environment includes:

• Java: OpenJDK 17
• Android SDK: Latest stable
• Gradle: 8.x
• Build Tools: 34.x
• Node.js: 18.x (LTS)
• NPM: Latest stable

Build Output

APK vs AAB

• APK (Android Package): Installable file for direct installation
• AAB (Android App Bundle): Google Play’s recommended format (smaller downloads for users)

By default, Capgo builds create:

• Debug mode: APK
• Release mode: AAB (optimized for Play Store)

Build Times

Typical Android build times:

Build Type	Average Time
Debug	2-3 minutes
Release (no ProGuard)	3-4 minutes
Release (with ProGuard)	4-6 minutes

Nota

Android builds cost 1× the base rate (half the cost of iOS builds).

Build Variants

Custom Build Variants

If your app has custom build variants (e.g., staging, production), use build-config:

npx @capgo/cli@latest build com.example.app \
  --platform android \
  --build-mode release \
  --build-config '{"variant":"staging"}'

This will build the stagingRelease variant.

Flavor Dimensions

For apps with flavor dimensions:

--build-config '{"flavor":"premium","variant":"production"}'

This builds the premiumProductionRelease variant.

Troubleshooting

Common Issues

“Keystore password incorrect”

• Verify KEYSTORE_STORE_PASSWORD matches your keystore
• Ensure KEYSTORE_KEY_PASSWORD matches your key alias password
• Check for extra spaces or special characters

“Key alias not found”

• Verify KEYSTORE_KEY_ALIAS matches exactly (case-sensitive)
• List aliases: keytool -list -keystore my-release-key.keystore

“Gradle build failed”

• Check build logs for the specific error
• Ensure your app builds locally with ./gradlew assembleRelease
• Verify all native dependencies are in build.gradle

“Play Store upload failed”

• Verify service account JSON is valid
• Ensure service account has correct permissions in Play Console
• Check that app is properly set up in Play Console

“Build timeout”

• Large apps may need optimization
• Check if unnecessary dependencies can be removed
• Contact support if builds consistently timeout

Debug Logs

Watch for these key phases in the build logs:

→ Downloading dependencies...
→ Running Gradle assembleRelease...
→ Signing APK/AAB...
→ Uploading to Play Store...
✔ Build succeeded

If a build fails, the specific Gradle error will be shown in the logs.

Best Practices

1. Test Locally First

Always ensure your Android build works locally:

cd android
./gradlew assembleRelease
# or
./gradlew bundleRelease

2. Secure Your Keystore

• Never commit keystores to version control
• Store in secure secrets management (1Password, AWS Secrets Manager, etc.)
• Keep backup copies in multiple secure locations
• Document passwords in a secure password manager

3. Version Management

Capgo reads version from your capacitor.config.json:

{
  "appId": "com.example.app",
  "appName": "My App",
  "version": "1.0.0",
  "build": "1"
}

Increment the build number for each release.

4. ProGuard Configuration

For release builds, ensure ProGuard rules are properly configured:

android/app/proguard-rules.pro

-keep class com.getcapacitor.** { *; }
-keep @com.getcapacitor.annotation.CapacitorPlugin public class * {
  @com.getcapacitor.annotation.PluginMethod public <methods>;
}

5. Monitor Build Size

Keep an eye on APK/AAB size to ensure it’s optimized:

The CLI shows final size:
→ APK size: 12.4 MB

If your app is large (>50 MB), consider:

• Enabling ProGuard/R8
• Using AAB format (dynamic delivery)
• Optimizing images and assets

Play Store Submission

Automatic Submission

With PLAY_CONFIG_JSON configured, builds are automatically uploaded to Play Console’s internal testing track.

Manual Submission

If you prefer manual submission:

1. Run the build without PLAY_CONFIG_JSON
2. Download the AAB from build artifacts (if configured)
3. Upload manually to Play Console

Next Steps

• iOS Builds - Configure iOS builds
• Troubleshooting - Common build issues
• CLI Reference - Full command documentation

Need Help?

• Troubleshooting Guide
• Discord Community
• Email: support@capgo.app