Build Debug APK qua GitHub Actions (app Expo/RN)

1. ⚠️ BẮT BUỘC: debug APK phải nhúng JS bundle (nếu không app chết "Unable to load script")

assembleDebug

localhost:8081

Unable to load script ... Make sure you're running Metro

react {}

android/app/build.gradle

expo-apk-standalone

ReactExtension.kt

• RN ≤ 0.7x:

  bundleInDebug = true

• RN 0.76+ / Expo SDK 5x:

  debuggableVariants = []

  (bundleInDebug đã bị xóa)

cd <project>            # vd: apps/mobile
npx expo prebuild --platform android --no-install
# PHẢI thấy debuggableVariants = [] (hoặc bundleInDebug = true theo RN version):
grep -n -A4 "react {" android/app/build.gradle
# PHẢI thấy applicationId + app_name đúng:
grep -n "applicationId" android/app/build.gradle
grep -n "app_name" android/app/src/main/res/values/strings.xml

1b. ⚠️ BẮT BUỘC: inject env CÔNG KHAI (

EXPO_PUBLIC_*

) vào workflow — thiếu env = APK build OK nhưng app lỗi runtime trên máy thật

https://placeholder.supabase.co

process.env.EXPO_PUBLIC_*

.env

Nguyên nhân gốc

• EXPO_PUBLIC_*

  được inline vào JS bundle lúc build — không có env trong CI = rỗng → rơi vào fallback (placeholder/rỗng) mà không báo lỗi build.
• APK build thành công + mở được ≠ backend hoạt động. Lỗi chỉ lộ khi cài máy thật và thao tác (signup/login/fetch).

Cách fix (áp dụng chung mọi project Expo có backend)

env:

env:
  EXPO_PUBLIC_SUPABASE_URL: ${{ secrets.EXPO_PUBLIC_SUPABASE_URL || 'https://<project-ref>.supabase.co' }}
  EXPO_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.EXPO_PUBLIC_SUPABASE_ANON_KEY || 'eyJ...' }}
  # ... mọi EXPO_PUBLIC_* khác (AdMob unit IDs, API public, v.v.)

• EXPO_PUBLIC_*

  là public-by-design: chúng nằm trong APK, ai giải nén cũng đọc được — KHÔNG phải secret thật, đặt giá trị fallback trực tiếp là OK. Lớp bảo vệ thật là RLS/server-side, không phải giấu key.

• secrets.X || 'fallback'

  cho phép user override sau bằng repo secret nếu cần đổi môi trường, không cần sửa workflow.
• TUYỆT ĐỐI không inject secret thật (service role key, token, DB password) vào env build — chúng sẽ nằm trong APK bị giải nén được.

Verify trước khi push (thêm vào checklist mục 2a)

# Workflow có đủ EXPO_PUBLIC_* cho app không?
grep -n "EXPO_PUBLIC_" .github/workflows/<build>.yml
# Mọi biến app đọc đều có trong workflow env (không chỗ nào rơi vào placeholder)

Chẩn đoán nhanh khi app cài máy thật mà backend fail (không cần đọc code)

# APK có chứa placeholder/URL sai không?
strings app-debug.apk | grep -iE "placeholder|localhost|http://" | head
# Đối chiếu với URL backend thật của project

2. Quy trình (khi user muốn build APK test)

a. Đảm bảo code sạch lỗi trước khi push (theo AGENTS.md)

cd <project>
npx tsc --noEmit           # typecheck
npm run lint               # lint
npx jest                   # test
npx expo export --platform android 2>&1 | tail -2   # bundle check

b. Commit + push lên branch build

cd <project-root>
git add -A
git commit -m "message"
git push origin <branch>   # workflow trigger tự động

c. Theo dõi workflow (không cần đợi build xong nếu user không yêu cầu)

curl -s -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/<owner>/<repo>/actions/runs?per_page=3"

d. Tải APK về khi build xong

# Lấy artifact download URL:
curl -s -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/<owner>/<repo>/actions/artifacts" | python3 -m json.tool
# Download + giải nén:
curl -sL -H "Authorization: Bearer $GH_TOKEN" -o apk.zip "<archive_download_url>"
unzip -o -q apk.zip && ls -lh *.apk

<tên-artifact>

app-debug.apk

3. Chi tiết workflow (debug APK, no keystore) — áp dụng chung

• Build:

  ./gradlew assembleDebug

  (không cần keystore riêng — debug keystore mặc định của Gradle) — kèm bundle JS qua config plugin (mục 1)
• Upload:

  android/app/build/outputs/apk/debug/app-debug.apk

• Bước chuẩn: checkout → Node (LTS) → JDK 17 → Android SDK (accept licenses) →

  npm ci

  →

  expo prebuild --platform android --clean --no-install

  (CI=1) →

  gradlew assembleDebug

  → upload
• BẮT BUỘC có

  env:

  với đủ

  EXPO_PUBLIC_*

  mà app đọc (mục 1b) — không inject thì app mở được nhưng signup/login/fetch đều fail (placeholder)
• KHÔNG dùng: EAS token, keystore production, signing release
• Native config chỉ lộ lỗi khi build thật: nếu build fail, đọc log step "Build debug APK" — các lỗi thường gặp: pin transitive dependency theo Kotlin metadata (xem skill

  gh-actions-expo-apk-build

  ), property

  react {}

  sai theo RN version (mục 1).

Tại sao build APK mới tìm chính xác lỗi

• npx expo export

  chỉ bundle JS — không bắt lỗi native (AdMob, WebView, Gradle, manifest).
• Debug APK cài lên máy thật mới lộ: lỗi native module, manifest, ads hiển thị, navigation bar che UI.
• Luôn khuyên user: "build APK rồi cài lên máy để test lỗi thật" khi nghi ngờ lỗi native/runtime.

Đổi sang Release APK (khi cần)

assembleDebug

assembleRelease

apk/release/app-release.apk

gh-actions-expo-apk-build