Builds de release de Android sin Android Studio en Linux, Windows y CI

Android Studio es un buen IDE, pero no es necesario para generar un build de Android listo para la tienda. El android/ directorio en un proyecto Capacitor contiene un Gradle wrapper que permite build y firma desde cualquier terminal. Esto es clave para servidores Linux sin interfaz gráfica, máquinas Windows donde Studio es lento y para CI.

Esta guía crea un AAB firmado solo con la línea de comandos, y luego muestra la variante cloud con Build de Capgo para equipos que no quieren tener keystores en sus laptops.

Requisitos

• JDK 21 (java -version imprime 21).
• Línea de comandos de Android SDK con platform-tools, build-tools y la plataforma que coincida con tu versión de Capacitor (API 36 para Capacitor 8, API 35 para Capacitor 7). La Guía de Linux y Guía de Windows cubren la instalación.
• ANDROID_HOME exportado, o android/local.properties con sdk.dir=....
• Una app Capacitor con android/ generado por bunx cap add android.

1) Crea el keystore de firma

keytool es parte del JDK en cada plataforma:

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

Responde a los prompts y elige una contraseña para el store y otra para la key. Guarda el archivo y ambas contraseñas en tu gestor de contraseñas o vault ahora. Nunca hagas commit release.jks.

Activa Play App Signing al crear la app en Play Console. Google guardará la clave de firma final y tu keystore pasará a ser una upload key, que puedes resetear si se pierde.

2) Configura Gradle para la firma

Mantén los secretos fuera de build.gradle. Crea android/keystore.properties (gitignored):

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

Luego referéncialo en 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
        }
    }
}

Añadir android/keystore.properties y *.jks a .gitignore.

3) Incrementa la versión

Google Play rechaza las subidas con un versionCode que ya ha visto antes. Edita android/app/build.gradle:

defaultConfig {
    versionCode 12
    versionName "1.4.0"
}

Los equipos suelen obtener versionCode desde números de CI o desde el conteo de commits de git para evitar ediciones manuales.

4) Genera el AAB desde la terminal

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

En Windows usa .\gradlew.bat bundleRelease. El bundle firmado se guarda en android/app/build/outputs/bundle/release/app-release.aab.

¿Necesitas un APK para instalar directamente con adb? ./gradlew assembleRelease genera app-release.apk en outputs/apk/release/. Instálalo con adb install; la guía de adb install cubre los casos especiales.

5) Verifica la firma

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

Para un AAB, jarsigner -verify -verbose app-release.aab confirma la firma y el fingerprint del certificado. Compara el SHA-256 con el que aparece en Play Console en App integrity.

6) Sube a Google Play desde la terminal

La subida manual vía Play Console funciona. Para automatizar, crea una service account en Google Cloud, dale acceso en Play Console en Users and permissions y descarga su clave JSON. Luego sube con el Google Play Developer API o una herramienta como 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

La primera subida de una app nueva debe hacerse manualmente en Play Console; API solo acepta builds de apps que ya existen.

7) La alternativa en la nube: Capgo Build para Android

Todo lo anterior funciona, pero deja un keystore en cada máquina que hace el build. Capgo Build mantiene el keystore en un vault cifrado, hace el build desde el android/ proyecto que subes y puede enviar el AAB a un track de Play.

Guarda las credenciales una vez:

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

O deja que bunx @capgo/cli@latest build init --platform android te guíe. Entonces, cada release es:

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

Los logs se muestran en la terminal. Añade --output-upload para obtener un link de descarga del AAB o APK, y --ai-analytics para que un build fallido se explique automáticamente. El mismo comando funciona en Windows, Linux, macOS y CI. Un ejemplo de GitHub Actions está en la guía de build de Android.

Como Capgo solo recibe el proyecto nativo preparado, los registros privados de npm y los secretos del build web permanecen en tu entorno.

8) Deja de recompilar por cambios en la web

Se necesita un Native Build firmado para actualizar plugins, permisos, iconos y Capacitor. Para todo lo demás, dist/, Live Updates de Capgo envía el nuevo bundle web directamente a las apps instaladas:

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

That removes most Gradle runs from your week.

Solución de problemas

• SDK location not found: establece ANDROID_HOME o crea android/local.properties.
• Keystore was tampered with, or password was incorrect: contraseña del store incorrecta, o el archivo se corrompió por una conversión CRLF en Git. Marca *.jks como binario en .gitattributes si debe ser versionado, lo cual no debería ocurrir.
• Unsupported class file major version: la versión del JDK no es la 21.
• Play rechaza el AAB: “signed with a different key”: Play App Signing espera tu clave de subida. Usa el keystore registrado en Play Console o solicita un reset de la upload key.
• El build es lento en Windows: excluye ~/.gradle y el SDK de Defender, y mantén el proyecto en una ruta local corta.
• Out of memory en Gradle: añadir org.gradle.jvmargs=-Xmx4g a android/gradle.properties.

Resumen

Un release de Android Capacitor necesita un JDK, el SDK y el Gradle wrapper, no Android Studio. Crea el keystore con keytool, firma mediante keystore.properties, build con bundleRelease, y realiza el upload con el Play API. Si quieres sacar el keystore de los laptops y usar el mismo comando en cualquier OS, Capgo Build se encarga del signing y el upload desde el proyecto preparado.