simple-notes-sync/GITHUB_ACTIONS_SETUP.md

GitHub Actions Setup Guide

This guide explains how to set up the GitHub Actions workflow for automated APK builds with proper signing.

Overview

The workflow in .github/workflows/build-production-apk.yml automatically:

• Builds signed APKs on every push to main
• Generates version numbers using YYYY.MM.DD + build number
• Creates 3 APK variants (universal, arm64-v8a, armeabi-v7a)
• Creates GitHub releases with all APKs attached

Prerequisites

• GitHub CLI (gh) installed
• Java 17+ installed (for keytool)
• Git repository initialized with GitHub remote

Step 1: Generate Signing Keystore

⚠️ IMPORTANT: Store the keystore securely! Without it, you cannot publish updates to your app.

# Navigate to project root
cd /path/to/simple-notes-sync

# Generate keystore (replace values as needed)
keytool -genkey -v \
  -keystore android/app/simple-notes-release.jks \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000 \
  -alias simple-notes

# You will be prompted for:
# - Keystore password (remember this!)
# - Key password (remember this!)
# - Your name, organization, etc.

Store these securely:

• Keystore password
• Key password
• Alias: simple-notes
• Keystore file: android/app/simple-notes-release.jks

⚠️ BACKUP: Make a backup of the keystore file in a secure location (NOT in the repository).

Step 2: Base64 Encode Keystore

# Create base64 encoded version
base64 android/app/simple-notes-release.jks > simple-notes-release.jks.b64

# Or on macOS:
base64 -i android/app/simple-notes-release.jks -o simple-notes-release.jks.b64

Step 3: Set GitHub Secrets

Using GitHub CLI (recommended):

# Set KEYSTORE_BASE64 secret
gh secret set KEYSTORE_BASE64 < simple-notes-release.jks.b64

# Set KEYSTORE_PASSWORD (will prompt for input)
gh secret set KEYSTORE_PASSWORD

# Set KEY_PASSWORD (will prompt for input)
gh secret set KEY_PASSWORD

# Set KEY_ALIAS (value: simple-notes)
printf "simple-notes" | gh secret set KEY_ALIAS

Or manually via GitHub web interface:

1. Go to repository Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Add these secrets:
   • KEYSTORE_BASE64: Paste content of simple-notes-release.jks.b64
   • KEYSTORE_PASSWORD: Your keystore password
   • KEY_PASSWORD: Your key password
   • KEY_ALIAS: simple-notes

Step 4: Verify Setup

# Check secrets are set
gh secret list

# Expected output:
# KEYSTORE_BASE64  Updated YYYY-MM-DD
# KEYSTORE_PASSWORD  Updated YYYY-MM-DD
# KEY_PASSWORD  Updated YYYY-MM-DD
# KEY_ALIAS  Updated YYYY-MM-DD

Step 5: Cleanup

# Remove sensitive files (they're in .gitignore, but double-check)
rm simple-notes-release.jks.b64
rm -f android/key.properties  # Generated by workflow

# Verify keystore is NOT tracked by git
git status | grep -i jks
# Should return nothing

Step 6: Trigger First Build

# Commit and push to main
git add .
git commit -m "🚀 feat: Add GitHub Actions deployment workflow"
git push origin main

# Or manually trigger workflow
gh workflow run build-production-apk.yml

Verification

1. Go to GitHub repository → Actions tab
2. Check workflow run status
3. Once complete, go to Releases tab
4. Verify release was created with 3 APK variants
5. Download and test one of the APKs

Troubleshooting

Build fails with "Keystore not found"

• Check KEYSTORE_BASE64 secret is set correctly
• Verify base64 encoding was done without line breaks

Build fails with "Incorrect password"

• Verify KEYSTORE_PASSWORD and KEY_PASSWORD are correct
• Re-set secrets if needed

APK files not found

• Check build logs for errors in assembleRelease step
• Verify APK output paths match workflow expectations

Updates don't work

• Ensure you're using the same keystore for all builds
• Verify applicationId in build.gradle.kts matches

Security Notes

• ✅ Keystore is base64-encoded in GitHub secrets (secure)
• ✅ Passwords are stored in GitHub secrets (encrypted)
• ✅ key.properties and .jks files are in .gitignore
• ⚠️ Never commit keystore files to repository
• ⚠️ Keep backup of keystore in secure location
• ⚠️ Don't share keystore passwords

Versioning

Versions follow this pattern:

• Version Name: YYYY.MM.DD (e.g., 2025.01.15)
• Version Code: GitHub run number (e.g., 42)
• Release Tag: vYYYY.MM.DD-prod.BUILD (e.g., v2025.01.15-prod.42)

This ensures:

• Semantic versioning based on release date
• Incremental version codes for Play Store compatibility
• Clear distinction between builds

APK Variants

The workflow generates 3 APK variants:

1. Universal APK (~5 MB)

   • Works on all devices
   • Larger file size
   • Recommended for most users

2. arm64-v8a APK (~3 MB)

   • For modern devices (2018+)
   • Smaller, faster
   • 64-bit ARM processors

3. armeabi-v7a APK (~3 MB)

   • For older devices
   • 32-bit ARM processors

Users can choose based on their device - Obtanium auto-updates work with all variants.