Générer des builds de release Android sans Android Studio sur Linux, Windows et CI

Android Studio est un excellent IDE, mais il n'est pas indispensable pour produire un build Android prêt pour les stores. Le android/ dossier généré dans un projet Capacitor contient un Gradle wrapper qui permet de compiler et signer depuis n'importe quel terminal. C'est crucial pour les serveurs Linux sans interface graphique, les machines Windows où Studio est lent, et pour la CI.

Ce guide explique comment générer un AAB signé uniquement via la ligne de commande, puis présente la variante cloud avec Build Capgo for teams that do not want keystores on laptops.

Prerequisites

• JDK 21 (java -version affiche 21).
• Ligne de commande Android SDK avec platform-tools, build-tools et la plateforme correspondant à votre version Capacitor (API 36 pour Capacitor 8, API 35 pour Capacitor 7). Le Guide Linux et Guide Windows couvrent l'installation.
• ANDROID_HOME exportée, ou android/local.properties avec sdk.dir=....
• Une application Capacitor avec android/ générée par bunx cap add android.

1) Créer le keystore de signature

keytool fait partie du JDK sur chaque plateforme :

keytool -genkeypair -v \
  -keystore release.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias release

Répondez aux prompts et choisissez un mot de passe pour le store et un pour la clé. Enregistrez le fichier et les deux mots de passe dans votre gestionnaire de mots de passe ou coffre-fort dès maintenant. Ne commitez jamais release.jks.

Activez Play App Signing lors de la création de l'application dans la Play Console. Google conserve alors la clé de signature finale et votre keystore devient une clé d'upload, qui peut être réinitialisée en cas de perte.

2) Configurer la signature dans Gradle

Gardez vos secrets hors de build.gradle. Créez android/keystore.properties (gitignored) :

storeFile=/absolute/path/to/release.jks
storePassword=your-store-password
keyAlias=release
keyPassword=your-key-password

Puis référencez-le dans android/app/build.gradle:

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

android {
    signingConfigs {
        release {
            if (keystorePropertiesFile.exists()) {
                storeFile file(keystoreProperties['storeFile'])
                storePassword keystoreProperties['storePassword']
                keyAlias keystoreProperties['keyAlias']
                keyPassword keystoreProperties['keyPassword']
            }
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
        }
    }
}

Ajouter android/keystore.properties et *.jks à .gitignore.

3) Incrémentez la version

Google Play rejette les uploads avec un versionCode qu'il a déjà vu. Modifiez android/app/build.gradle:

defaultConfig {
    versionCode 12
    versionName "1.4.0"
}

Les équipes dérivent généralement versionCode des numéros de run CI ou du nombre de commits git pour éviter les modifications manuelles.

4) Générez l'AAB depuis le terminal

bun run build
bunx cap sync android
cd android
./gradlew bundleRelease

Sur Windows, utilisez .\gradlew.bat bundleRelease. Le bundle signé est écrit dans android/app/build/outputs/bundle/release/app-release.aab.

Besoin d'un APK pour des installs directes via adb ? ./gradlew assembleRelease produit app-release.apk sous outputs/apk/release/. Installez-l’avec adb install; le guide d'installation adb couvre les cas particuliers.

5) Vérifier la signature

$ANDROID_HOME/build-tools/36.0.0/apksigner verify --print-certs app/build/outputs/apk/release/app-release.apk

Pour un AAB, jarsigner -verify -verbose app-release.aab confirme la signature et l'empreinte du certificat. Comparez le SHA-256 avec celui affiché dans la Play Console sous Intégrité de l'application.

6) Envoyer vers Google Play via la ligne de commande

L'upload manuel via la Play Console fonctionne. Pour l'automatisation, créez un compte de service dans Google Cloud, donnez-lui l'accès dans la Play Console sous Utilisateurs et permissions, et téléchargez sa clé JSON. Ensuite, effectuez l'upload avec l’API Google Play Developer ou un outil comme fastlane supply :

bundle exec fastlane supply --aab android/app/build/outputs/bundle/release/app-release.aab \
  --track internal --json_key play-service-account.json --package_name com.example.app

Le premier upload d'une nouvelle application doit être fait manuellement dans la Play Console ; API n'accepte que les builds d'applications déjà existantes.

7) L'alternative cloud : Capgo Build pour Android

Tout ce qui précède fonctionne, mais cela laisse un keystore sur chaque machine qui effectue le build. Capgo Build conserve le keystore dans un coffre-fort chiffré, effectue le build à partir du projet android/ préparé que vous envoyez, et peut pousser l'AAB vers un canal Play.

Enregistrez les identifiants une seule fois :

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./release.jks \
  --keystore-alias "release" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

Ou laissez bunx @capgo/cli@latest build init --platform android vous guider. Ensuite, chaque release est :

bun run build
bunx cap sync android
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release

Les logs défilent dans le terminal. Ajoutez --output-upload pour obtenir un lien de téléchargement de l'AAB ou de l'APK, et --ai-analytics pour obtenir une explication automatique d'un build échoué. La même commande s'exécute sous Windows, Linux, macOS et en CI. Un exemple GitHub Actions est disponible dans le guide de build Android.

Comme Capgo ne reçoit que le projet natif préparé, vos registres npm privés et vos secrets de build web restent dans votre environnement.

8) Arrêtez de recompiler pour chaque changement web

Un build natif signé est nécessaire pour les mises à jour de plugins, de permissions, d'icônes et de Capacitor. Pour tout le reste, dist/, Capgo Live Updates envoyez le nouveau bundle web directement aux applications installées :

bunx @capgo/cli@latest bundle upload --channel production

Cela élimine la plupart des exécutions Gradle de votre semaine.

Troubleshooting

• SDK location not found: définissez ANDROID_HOME ou créez android/local.properties.
• Keystore was tampered with, or password was incorrect: mot de passe de store incorrect, ou le fichier a été corrompu par une conversion CRLF dans Git. Marquez *.jks comme binaire dans .gitattributes s'il doit être versionné, ce qui ne devrait pas être le cas.
• Unsupported class file major version: the JDK is newer or older than 21.
• Play rejette l'AAB : « signé avec une clé différente »: Play App Signing attend votre clé d'upload. Utilisez le keystore enregistré dans la Play Console ou demandez une réinitialisation de la clé d'upload.
• Le build est lent sur Windows: exclure ~/.gradle et le SDK de Defender, et gardez le projet sur un chemin local court.
• Erreur de mémoire (Out of memory) dans Gradle: ajoutez org.gradle.jvmargs=-Xmx4g à android/gradle.properties.

Résumé

Un Capacitor Android release nécessite un JDK, le SDK et le Gradle wrapper, pas Android Studio. Créez le keystore avec keytool, signez via keystore.properties, compilez avec bundleRelease, et effectuez l'upload avec le Play API. Pour sortir le keystore des ordinateurs portables et utiliser la même commande sur chaque OS, Capgo Build gère la signature et l'upload depuis le projet préparé.