Android Publishing with Gradle Play Publisher (GPP)

Legacy
This guide predates the Supabase-first architecture and documents the mobile publishing pipeline we used for bundle-ID automation. Keep it only for historical reference.

This document explains how to set up and use the Android publishing automation for React Native apps in this monorepo.

Overview

The Android publishing system uses the Gradle Play Publisher (GPP) plugin to automate the process of building Android App Bundles (AABs) and publishing them to the Google Play Store.

Features

• 🚀 Automated AAB Building: Build release AABs with proper signing
• 📱 Multi-App Support: Handle multiple React Native apps in the monorepo
• 🎯 Track Selection: Publish to different Play Store tracks (internal, alpha, beta, production)
• 🔐 Secure Credentials: Load service account JSON from CI secrets
• 🛠️ Template System: Easy setup for new mobile apps

Quick Start

1. For Existing Apps (Focus AI)

The Focus AI mobile app is already configured. To publish:

# Build AAB only (for testing)
node scripts/publish-android.mjs focus-ai-mobile --build-only

# Publish to internal track
GOOGLE_PLAY_SERVICE_ACCOUNT="$(cat service-account.json)" \
node scripts/publish-android.mjs focus-ai-mobile internal

# Publish to beta track
GOOGLE_PLAY_SERVICE_ACCOUNT="$(cat service-account.json)" \
node scripts/publish-android.mjs focus-ai-mobile beta

2. For New Apps

Use the setup script to configure GPP for a new mobile app:

node scripts/setup-android-gpp.mjs apps/my-new-app "My App Name" com.company.myapp com.company.myapp

Then add the app to the SUPPORTED_APPS configuration in scripts/publish-android.mjs.

Configuration

Environment Variables

Variable	Description	Required
GOOGLE_PLAY_SERVICE_ACCOUNT	Service account JSON content	Yes (for publishing)
ANDROID_APP	App to publish	No (can use CLI arg)
PLAY_TRACK	Play Store track	No (defaults to internal)
MYAPP_UPLOAD_STORE_FILE	Path to upload keystore	Yes (for release builds)
MYAPP_UPLOAD_STORE_PASSWORD	Upload keystore password	Yes (for release builds)
MYAPP_UPLOAD_KEY_ALIAS	Upload key alias	Yes (for release builds)
MYAPP_UPLOAD_KEY_PASSWORD	Upload key password	Yes (for release builds)

Supported Apps

Currently configured apps:

• focus-ai-mobile: AI-powered focus and productivity assistant
• health-tracker-mobile: Health and fitness tracking app
• ai-demo-mobile: AI demonstration app

Supported Tracks

• internal: Internal testing track
• alpha: Alpha testing track
• beta: Beta testing track
• production: Production release track

Scripts

scripts/publish-android.mjs

Main publishing script that handles building and publishing Android apps.

Usage:

node scripts/publish-android.mjs <app> [track] [options]

Options:

• --build-only: Only build AAB, don't publish
• --help: Show help information

Examples:

# Build and publish to internal track
node scripts/publish-android.mjs focus-ai-mobile internal

# Build AAB only
node scripts/publish-android.mjs focus-ai-mobile --build-only

# Using environment variables
ANDROID_APP=focus-ai-mobile PLAY_TRACK=beta node scripts/publish-android.mjs

scripts/setup-android-gpp.mjs

Setup script for configuring GPP on new mobile apps.

Usage:

node scripts/setup-android-gpp.mjs <app-path> <app-name> <namespace> <application-id>

Example:

node scripts/setup-android-gpp.mjs apps/my-mobile-app "My App" com.company.myapp com.company.myapp

Google Play Console Setup

1. Create a Service Account

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the Google Play Android Developer API
4. Create a service account with the following roles:
   • Service Account User
   • Google Play Android Developer API access

2. Generate Service Account Key

1. In the service account, create a new JSON key
2. Download the JSON file
3. Store the JSON content in your CI system as GOOGLE_PLAY_SERVICE_ACCOUNT

3. Grant Play Console Access

1. Go to Google Play Console
2. Go to Setup → API access
3. Link your Google Cloud project
4. Grant access to the service account with these permissions:
   • View app information and download bulk reports
   • Manage store presence
   • Manage app releases

Release Signing

1. Generate Upload Keystore

keytool -genkeypair -v -storetype PKCS12 -keystore upload-keystore.keystore -alias upload -keyalg RSA -keysize 2048 -validity 10000

2. Configure Signing

Set these environment variables in your CI:

MYAPP_UPLOAD_STORE_FILE=path/to/upload-keystore.keystore
MYAPP_UPLOAD_STORE_PASSWORD=your_keystore_password
MYAPP_UPLOAD_KEY_ALIAS=upload
MYAPP_UPLOAD_KEY_PASSWORD=your_key_password

CI/CD Integration

GitHub Actions Example

name: Android Release

on:
  push:
    tags:
      - 'v*'

jobs:
  android-release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Setup Java
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'
          
      - name: Install dependencies
        run: pnpm install
        
      - name: Publish to Play Store
        env:
          GOOGLE_PLAY_SERVICE_ACCOUNT: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT }}
          MYAPP_UPLOAD_STORE_FILE: ${{ secrets.UPLOAD_KEYSTORE_FILE }}
          MYAPP_UPLOAD_STORE_PASSWORD: ${{ secrets.UPLOAD_KEYSTORE_PASSWORD }}
          MYAPP_UPLOAD_KEY_ALIAS: ${{ secrets.UPLOAD_KEY_ALIAS }}
          MYAPP_UPLOAD_KEY_PASSWORD: ${{ secrets.UPLOAD_KEY_PASSWORD }}
        run: |
          node scripts/publish-android.mjs focus-ai-mobile production

Troubleshooting

Common Issues

1. "Service account not found"

   • Verify the service account JSON is valid
   • Check that the service account has proper permissions

2. "Upload keystore not found"

   • Ensure MYAPP_UPLOAD_STORE_FILE points to the correct keystore
   • Verify keystore passwords are correct

3. "Track not found"

   • Make sure the track exists in Google Play Console
   • Internal track is created automatically, others need manual setup

4. "AAB not found"

   • Check that the build completed successfully
   • Verify the artifactDir path in build.gradle

Debug Mode

To debug issues, you can:

1. Use --build-only flag to test building without publishing
2. Check Gradle logs in the app's android directory
3. Verify environment variables are set correctly

File Structure

apps/
├── focus-ai-mobile/
│   └── android/
│       ├── build.gradle              # Root Gradle config
│       ├── settings.gradle           # Project settings
│       ├── gradle.properties         # Gradle properties
│       └── app/
│           ├── build.gradle          # App Gradle config with GPP
│           └── src/main/
│               ├── AndroidManifest.xml
│               └── res/values/strings.xml
scripts/
├── publish-android.mjs               # Main publishing script
└── setup-android-gpp.mjs            # Setup script for new apps

Contributing

When adding new mobile apps:

1. Use scripts/setup-android-gpp.mjs to create the Android structure
2. Add the app to SUPPORTED_APPS in scripts/publish-android.mjs
3. Test with --build-only flag first
4. Update this documentation

Security Notes

• Never commit service account JSON files to the repository
• Use environment variables for all sensitive credentials
• Rotate service account keys regularly
• Use upload keys, not app signing keys in CI