Android CI/CD

<!-- source: davila7/claude-code-templates cli-tool/components/skills/development/android-cicd/SKILL.md (MIT) adapted wave-r r2 -->

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:

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:

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:

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:

---

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: [email protected]
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

---

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