Agent Skills: Skill: android-cicd

Skill: android-cicd

Purpose

Set up a complete, multi-stage Android CI/CD pipeline that automatically builds and publishes to Google Play via GitHub Actions. Supports TWA (Trusted Web Activity / Bubblewrap), React Native, Flutter, and native Android (Gradle) projects.

When to Use

• The project has an Android app tracked in a GitHub repository
• No CI/CD pipeline exists yet for the Android build
• Goal: automate publishing to Google Play on every push to main and on version tags
• User wants to avoid manual versionCode bumping

Quick Start

Run the interactive setup wizard from the root of the target project:

npx android-cicd

The wizard handles: framework detection → keystore generation → GitHub Secrets → workflow scaffold.

Prerequisites

Before running the wizard, ensure:

• Node.js ≥ 18
• JDK 17 installed with keytool accessible (JAVA_HOME set, or installed via Eclipse Adoptium / Android Studio)
• gh CLI installed and authenticated (gh auth login)
• App already created in Google Play Console — at least one manual AAB/APK upload done (required before the API can publish)
• App enrolled in Play App Signing (Google manages the signing key; you manage the upload key)
• Google Play Android Developer API enabled in Google Cloud Console
• Service account JSON key downloaded (see Manual Steps below)

Framework Detection

The wizard auto-detects the framework from the project directory structure:

| Condition | Detected framework | |---|---| | pubspec.yaml contains flutter: | flutter | | android/app/build.gradle exists + package.json has react-native dep | react-native | | android-root-app/build.gradle or twa-manifest.json or .bubblewrap/config.json exists | twa | | app/build.gradle exists | native | | android/app/build.gradle exists (fallback) | native |

The user can override the detected framework during the wizard.

Multi-Stage Pipeline

The scaffolded workflow publishes to different tracks based on the git ref:

| Git event | Google Play track | |---|---| | Push to main | internal | | Tag matching v*-alpha (e.g. v1.2-alpha) | alpha | | Tag matching v*-beta (e.g. v1.2-beta) | beta | | Tag matching v* (e.g. v1.2.0) | production | | Manual workflow_dispatch | User-selectable (internal / alpha / beta / production) |

To release to production:

git tag v1.2.0
git push origin v1.2.0

Auto-Bump versionCode

On every push to main, CI automatically:

1. Reads the current versionCode from the version file for the detected framework
2. Increments it by 1
3. Commits the change with [skip ci] (prevents re-triggering the workflow)
4. Pushes the commit back to main

Version file by framework:

| Framework | Version file | Field | |---|---|---| | TWA | android-root-app/build.gradle | versionCode | | React Native | android/app/build.gradle | versionCode | | Flutter | pubspec.yaml | version: x.y.z+N (the +N build number) | | Native | app/build.gradle | versionCode |

For tag-based builds (alpha / beta / production), auto-bump does not run — the tag represents a pinned commit. Increment the version manually before tagging.

Required GitHub Secrets

The wizard sets these automatically via gh secret set:

| Secret | Description | |---|---| | KEYSTORE_FILE | Base64-encoded upload keystore (.jks) | | KEYSTORE_PASSWORD | Keystore password | | KEY_ALIAS | Key alias (e.g. upload) | | KEY_PASSWORD | Key password (usually same as KEYSTORE_PASSWORD) | | GOOGLE_PLAY_SERVICE_ACCOUNT_JSON | Full JSON content of the service account key |

Signing Configuration

TWA / Native Android

Add to your build.gradle (see templates/gradle/signing.gradle):

android {
    signingConfigs {
        release {
            storeFile file("keystore.jks")
            storePassword System.getenv("KEYSTORE_PASSWORD")
            keyAlias System.getenv("KEY_ALIAS")
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            minifyEnabled true
            signingConfig signingConfigs.release
        }
    }
}

Never set org.gradle.java.home in gradle.properties — it breaks Linux CI runners.

Flutter

The CI workflow creates android/key.properties at build time (from secrets) and cleans it up after. Your android/app/build.gradle should read from it:

def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file('key.properties')
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        release {
            keyAlias keystoreProperties['keyAlias']
            keyPassword keystoreProperties['keyPassword']
            storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
            storePassword keystoreProperties['storePassword']
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Manual Steps (Cannot Be Automated)

1. Create the service account

1. Google Cloud Console → your project → IAM & Admin → Service Accounts
2. Create service account → name: github-play-publisher → Done (no roles needed)
3. Click the service account → Keys tab → Add key → Create new key → JSON → download

2. Enable the Play API

Google Cloud Console → APIs & Services → search Google Play Android Developer API → Enable

3. Invite the service account in Play Console

1. Play Console → Users and permissions → Invite new user
2. Email: github-play-publisher@YOUR-PROJECT.iam.gserviceaccount.com
3. Account-level permissions:
   • ✅ Release apps to testing tracks
   • ✅ Manage testing tracks and edit testers
4. Apply

4. First manual upload

Google Play requires at least one manually uploaded AAB before the API can publish. If this is a brand-new app, upload the first build from your local machine before running the CI pipeline.

Troubleshooting

| Error | Cause | Fix | |---|---|---| | Java home supplied is invalid | org.gradle.java.home hardcoded in gradle.properties | Remove that line | | signed with the wrong key | Keystore in secret doesn't match Play's registered upload key | Update KEYSTORE_FILE secret | | The caller does not have permission | Service account missing permissions or API not enabled | Re-check Manual Steps 2 and 3 | | Upload failed — wrong versionCode | versionCode not incremented (tag-based build) | Increment versionCode manually before tagging | | shallow update not allowed | Shallow git checkout when pushing version bump | Workflow uses fetch-depth: 0 — verify the checkout step | | Workflow not triggering on tag | Tag not pushed to remote | Run git push origin TAG_NAME | | gh: command not found | gh CLI not installed | Install from https://cli.github.com | | keytool not found | JDK not installed or not on PATH | Set JAVA_HOME or install JDK 17 |

Recovering a Lost Upload Keystore

If the app uses Play App Signing (recommended):

1. Generate a new keystore: npx android-cicd and choose "I already have a keystore: No"
2. Export the PEM certificate:

   keytool -export -rfc -keystore upload.jks -alias ALIAS -storepass PASSWORD -file cert.pem
   

3. Play Console → app → App integrity → App signing → Request upload key reset
4. Select "I forgot my password" → upload cert.pem
5. Wait 1–2 business days for Google approval
6. Update the KEYSTORE_FILE secret with the new keystore base64

Manually Bumping the Version (Tag Releases)

Before pushing a tag for alpha / beta / production:

TWA / Native / React Native — edit build.gradle:

versionCode 8   // increment
versionName "1.2.0"

Flutter — edit pubspec.yaml:

version: 1.2.0+8

Then tag and push:

git add .
git commit -m "chore: bump version to 1.2.0"
git tag v1.2.0
git push origin main --tags