GitHub Actions: Build Expo Android APK/AAB

When to use (vs EAS)

IN_QUEUE

production

android-release-signing

Decision order

1. APK (test) → workflow below, no secrets needed (debug keystore) or with keystore secrets for a release-signed APK.
2. AAB (store) → sign with the project release keystore inside the workflow (decode keystore secret →

   expo prebuild

   with signing plugin →

   ./gradlew bundleRelease

   ). This works without EAS; see

   references/aab-play-store-signing.md

   and the

   android-release-signing

   skill. (EAS Build is an alternative if you prefer EAS-managed signing.)
3. Build failing with a Kotlin/version error → read

   references/troubleshooting.md

   FIRST. These are the 5-fix failure modes that cost hours.

Procedure (APK, test build)

1. Preconditions

• Repo is pushed to GitHub (workflow only runs there).

• google-services.json

  (if the app uses Firebase/AdMob) is committed.

• android/

  is NOT committed (gitignored) — CI regenerates it via

  expo prebuild

  .
• Default branch is

  main

  (rename

  master

  first:

  git branch -M main

  ) or adjust the trigger.

2. Create the workflow

references/workflow-template.md

.github/workflows/build-apk.yml

npm ci

expo prebuild --clean --no-install

CI: 1

./gradlew assembleRelease

upload-artifact

• JDK 17 for Expo SDK 52+ / RN 0.7x+ (21 is not required).
• Always

  --clean

  on prebuild so

  android/

  matches

  app.json

  (plugins, google-services, proguard).
• Validate the YAML before pushing (see below).
• Set

  if-no-files-found: error

  on the upload step.

3. Push and monitor

git add -A && git commit -m 'ci: add APK build workflow' && git push origin main
gh run list --repo <owner>/<repo> --limit 3
gh run watch <run-id> --repo <owner>/<repo>      # or poll via gh run view --json status,conclusion
gh run view <run-id> --repo <owner>/<repo> --log-failed   # when it fails — read THIS, not the full log

--log-failed

--log | grep <keyword>

4. Download the artifact

gh run download <run-id> --repo <owner>/<repo> --dir apk --pattern '*.zip'
# or, faster for large artifacts:
gh api repos/<owner>/<repo>/actions/artifacts --jq '.artifacts[] | select(.workflow_run.id==<run-id>) | {name, id, size_in_bytes, archive_download_url}'
curl -sL -H "Authorization: Bearer $GH_TOKEN" -o apk/artifact.zip '<archive_download_url>'
unzip -o -q apk/artifact.zip -d apk && ls -lh apk/*.apk

GH_TOKEN

5. If the build fails with a compile error

references/troubleshooting.md

6. AAB / Play Store release

references/aab-play-store-signing.md

ANDROID_KEYSTORE_BASE64/PASSWORD/ALIAS/KEY_PASSWORD

expo prebuild

bundleRelease

android-release-signing

npx eas-cli build --platform android --profile production

EXPO_TOKEN

1. Ensure

   eas.json

   has a

   production

   profile with

   buildType: "app-bundle"

   and

   autoIncrement: true

   .

2. npx eas-cli build --platform android --profile production

   .
3. Back up the keystore:

   npx eas-cli credentials --platform android

   → download

   credentials.json

   (gitignore it).
4. Upload a Play service-account JSON to EAS credentials, then

   npx eas-cli submit --platform android

   .
5. Never commit keystores.

Reference routing

references/workflow-template.md

eas submit

references/aab-play-store-signing.md

compileReleaseKotlin

references/troubleshooting.md

scripts/pin-gradle-dependency.js

plugins/

app.json

SPEC.md

Security notes

• Never commit keystores or secrets. Debug keystore builds need no secrets.
• If a token (EXPO_TOKEN, GH_TOKEN/ghp_*) was ever pasted into a chat, tell the user to revoke it after the build finishes.
• Token in push URL leaks via

  git remote -v

  : push with

  git -c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64)" push origin main

  instead.

AAB signing essentials

• Upload key vs App Signing key: your keystore (project-managed in the workflow, or EAS-managed) signs the AAB; Google's Play App Signing key re-signs user APKs. They must differ, and losing your upload key is recoverable (Google Play Support reset, with a 72-hour validity window) because Google holds the final key.
• Back up the keystore immediately after the first production build (

  eas credentials

  → download

  credentials.json

  ); never commit it.

• eas submit

  needs a Google Play service-account JSON (Release Manager permission) uploaded to EAS credentials.

Golden rules (learned the hard way)

• Don't bump Kotlin to read newer metadata. Raising

  kotlinVersion

  can break other libs (e.g. react-native-safe-area-context crashes on Kotlin 2.3) and still not fix the module. Pin the offending native dependency DOWN instead.

• expo-build-properties

  kotlinVersion

  only writes gradle.properties — it does NOT override the RN version catalog, so it often has zero effect. Verify in

  android/gradle/libs.versions.toml

  after prebuild.
• Verify the real cause before patching. Resolve what version Gradle actually picked and inspect the module's Gradle file / AAR metadata; guessing causes repeated failed runs.
• Config-plugin pins are the durable fix (prebuild regenerates

  android/

  each run); hand-editing

  android/build.gradle

  is wiped on the next prebuild.
• When a pinned version lacks APIs the module calls, the compiler error names the exact symbol — patch only those call sites via patch-package, with a safe fallback, and verify the patch applies on a pristine copy.