Android APK: Resolve Debug vs Release Build Configuration and Keystore Authentication

[stphung]

Problem Statement

The Android build pipeline currently defaults to debug builds only due to keystore authentication failures when attempting release builds. While debug builds work perfectly (27.1 MB APK), we need to resolve the release build configuration for production-ready APKs.

Current Status Analysis

✅ Working: Debug Builds

• Build Time: ~1m41s consistently successful
• APK Size: 27.1 MB ARM64 APK
• Signing: Auto-generated debug keystore
• Quality: Fully functional for development and testing

❌ Failing: Release Builds

• Error: "Release Username and/or Password is invalid for the given Release Keystore"
• Status: Commented out in CI/CD pipeline (lines 256-259 in .github/workflows/ci-cd.yml)
• Fallback: Automatically reverts to debug build when keystore unavailable

Technical Investigation

Commented Out Variables in GitHub Actions

# Lines 256-259 in .github/workflows/ci-cd.yml
# env:
#   KEYSTORE_BASE64: ${{ secrets.SECRET_RELEASE_KEYSTORE_BASE64 }}
#   KEYSTORE_USER: ${{ secrets.SECRET_RELEASE_KEYSTORE_USER }}
#   KEYSTORE_PASSWORD: ${{ secrets.SECRET_RELEASE_KEYSTORE_PASSWORD }}

Recent Commit Analysis

• 6129bd4: Re-enable Android release build with keystore signing - Initial attempt
• ee6232e: Revert to debug Android build due to keystore authentication failure - Rollback due to failure
• 18c8520: Document comprehensive CI/CD implementation achievements - Current documented state

Current CI Logic (Lines 264-280)

if [ -n "$KEYSTORE_BASE64" ]; then
  # Release build path
  EXPORT_TYPE="release"
  EXPORT_PRESET="Android"
  OUTPUT_FILE="build/android/$EXPORT_NAME.apk"
else
  # Debug build fallback (currently active)
  EXPORT_TYPE="debug"
  EXPORT_PRESET="Android Debug"
  OUTPUT_FILE="build/android/$EXPORT_NAME-debug.apk"
fi

Root Cause Analysis

Potential Issues with Keystore Authentication

1. GitHub Secrets Configuration

   • SECRET_RELEASE_KEYSTORE_BASE64: Base64 encoded keystore file
   • SECRET_RELEASE_KEYSTORE_USER: Keystore alias (should be "stphung")
   • SECRET_RELEASE_KEYSTORE_PASSWORD: Keystore password

2. Keystore Alias Mismatch

   • Error suggests username/alias issue
   • Current expectation: alias should be "stphung"
   • Need to verify actual keystore alias

3. Password Authentication

   • Keystore password may not match secret
   • Key password vs store password distinction

4. Keystore File Integrity

   • Base64 encoding/decoding issues
   • Keystore file corruption during secret storage

Investigation Tasks

Phase 1: Keystore Verification (HIGH PRIORITY)

• Verify existing keystore file

  • Check keystore alias using keytool -list -keystore release.keystore
  • Confirm actual alias name (may not be "stphung")
  • Verify keystore integrity and password

• Audit GitHub Repository Secrets

  • Verify SECRET_RELEASE_KEYSTORE_BASE64 is properly set
  • Confirm SECRET_RELEASE_KEYSTORE_USER matches actual keystore alias
  • Validate SECRET_RELEASE_KEYSTORE_PASSWORD is correct

• Test Local Release Build

  • Build release APK locally to isolate CI/CD vs keystore issues
  • Verify export preset configuration matches keystore requirements

Phase 2: Configuration Resolution (MEDIUM PRIORITY)

• Update GitHub Secrets

  • Regenerate keystore if necessary with known credentials
  • Update repository secrets with verified values
  • Test secret retrieval in CI environment

• Export Preset Alignment

  • Review export_presets.cfg Android release configuration
  • Ensure keystore paths and credentials match CI expectations
  • Verify signing settings alignment

Phase 3: Enhanced Build Pipeline (LOW PRIORITY)

• Dual APK Output

  • Provide both debug and release APKs in builds
  • Allow debug builds for development, release for production
  • Clear naming convention: continuum-debug.apk vs continuum-release.apk

• Keystore Management Improvement

  • Documentation for keystore regeneration process
  • Backup strategy for release keystore
  • Rotation plan for production keys

Proposed Solutions

Immediate Fix (Next 1-2 Days)

1. Generate Fresh Release Keystore

   keytool -genkey -v -keystore release.keystore \
     -alias stphung -keyalg RSA -keysize 2048 -validity 25000 \
     -dname "CN=Continuum Game,OU=Game Development,O=stphung,L=City,ST=State,C=US"

2. Update GitHub Secrets

   • Encode keystore: base64 -i release.keystore | pbcopy
   • Set secrets with known password and alias
   • Re-enable commented environment variables

3. Test Release Build

   • Uncomment lines 256-259 in GitHub Actions
   • Trigger build and verify release APK generation

Long-term Strategy (Next 1-2 Weeks)

1. Hybrid Build Approach

   • Maintain debug builds for CI testing
   • Enable release builds for tagged versions only
   • Clear documentation for when each type is used

2. Production Keystore Management

   • Secure keystore backup strategy
   • Documented credential rotation process
   • Separation of debug vs production signing

Success Criteria

Phase 1 Success

• Release builds complete without authentication errors
• Signed release APK generated (should be similar size to debug: ~27MB)
• GitHub Secrets properly configured and accessible in CI

Phase 2 Success

• Both debug and release builds available as CI artifacts
• Clear naming convention for different APK types
• Documentation for keystore management and troubleshooting

Phase 3 Success

• Production-ready release process with proper signing
• Backup and rotation strategy for release keystore
• Comprehensive testing of signed APKs on Android devices

Risk Assessment

Low Risk

• Debug builds continue working: Current functionality unaffected
• Fallback mechanism: CI automatically uses debug if release fails

Medium Risk

• Keystore regeneration: May require updating other development environments
• Google Play Store: Future store uploads require consistent release signing

Mitigation Strategies

• Keep debug builds as reliable fallback
• Document all keystore changes thoroughly
• Test release APKs on multiple Android devices before production use

---

Priority: High (blocks production-ready Android releases)
Complexity: Medium (keystore management + CI/CD configuration)
Impact: Enables professional Android app distribution

Next Steps: Start with Phase 1 keystore verification and GitHub Secrets audit.