❗[버그][CICD][Android] CI Android APK 빌드 시 release 서명 설정 누락으로 빌드 실패

[Cassiiopeia]

🗒️ 설명

• main 브랜치에서 CI(PROJECT-Flutter-CI) 실행 시 Android APK 빌드가 실패함
• iOS 빌드는 --no-codesign 옵션으로 정상 성공
• Android는 flutter build apk --release 실행 시 release 서명용 keystore 파일이 CI 환경에 없어서 packageRelease 태스크에서 실패

🔄 재현 방법

1. main 브랜치에 PR 머지 또는 push
2. PROJECT-Flutter-CI 워크플로우 자동 실행
3. Android 빌드 job에서 flutter build apk --release 단계 실행
4. SigningConfig "release" is missing required property "storeFile" 에러로 빌드 실패

📸 참고 자료

• GitHub Actions Run: https://github.com/MapSee-Lab/MapSy-FE/actions/runs/22294402400/job/64488018374
• 에러 로그:

FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':app:packageRelease'.
> A failure occurred while executing com.android.build.gradle.tasks.PackageAndroidArtifact$IncrementalSplitterRunnable
   > SigningConfig "release" is missing required property "storeFile".

✅ 예상 동작

• CI에서 Android APK release 빌드가 정상적으로 성공해야 함
• Play Store CICD 워크플로우처럼 keystore secrets를 사용하여 release 서명 적용
• secrets가 없는 환경에서도 debug 서명으로 fallback하여 빌드 실패 방지

⚙️ 환경 정보

• CI Runner: ubuntu-latest (GitHub Actions)
• Flutter: 3.35.5
• Java: 17
• 워크플로우: PROJECT-FLUTTER-CI.yaml

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: @Cassiiopeia
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260223_#43_CI_Android_APK_빌드_시_release_서명_설정_누락으로_빌드_실패

커밋 메시지

CI Android APK 빌드 시 release 서명 설정 누락으로 빌드 실패 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-FE/issues/43

[Cassiiopeia]

📌 작업 개요

CI(PROJECT-Flutter-CI) 워크플로우에서 Android APK release 빌드 시 keystore 서명 설정 누락으로 빌드 실패하는 문제 수정. CI workflow에 release keystore 설정 단계를 추가하고, build.gradle.kts에 debug 서명 fallback 로직을 적용하여 이중 안전장치 구현.

• 이슈: #43
• 관련 Actions Run: #22294402400

---

🔍 문제 분석

에러 현상

Execution failed for task ':app:packageRelease'.
> SigningConfig "release" is missing required property "storeFile".

근본 원인

• android/app/build.gradle.kts에서 key.properties 파일을 읽어 release 서명 설정을 구성
• CI 환경에는 key.properties 파일이 존재하지 않아 storeFile이 null로 설정됨
• release 빌드 타입이 무조건 release signingConfig을 참조하여 null storeFile로 패키징 시도 → 실패

iOS는 성공한 이유

• iOS 빌드는 flutter build ios --release --no-codesign 으로 서명 없이 빌드
• Android에는 이에 대응하는 서명 스킵 옵션이 없음

Play Store CICD는 성공하는 이유

• PROJECT-FLUTTER-ANDROID-PLAYSTORE-CICD.yaml에서는 GitHub Secrets(RELEASE_KEYSTORE_BASE64 등)를 사용하여 keystore 파일과 key.properties를 CI 환경에 동적 생성
• CI workflow(PROJECT-FLUTTER-CI.yaml)에는 이 설정이 누락되어 있었음

---

✅ 구현 내용

1. CI workflow에 release keystore 설정 추가

• 파일: .github/workflows/PROJECT-FLUTTER-CI.yaml
• 변경 내용: Android 빌드 job에 keystore 파일 생성 및 key.properties 생성 단계 2개 추가
• 이유: Play Store CICD 워크플로우와 동일하게 GitHub Secrets를 사용하여 release 서명 적용

2. build.gradle.kts에 debug 서명 fallback 추가

• 파일: android/app/build.gradle.kts
• 변경 내용: release 빌드 타입의 signingConfig을 key.properties 존재 여부에 따라 분기 처리
• 이유: Secrets가 없는 환경(로컬 개발 등)에서도 빌드 실패 없이 debug 서명으로 빌드 가능하도록 안전장치 추가

---

🔧 주요 변경사항 상세

.github/workflows/PROJECT-FLUTTER-CI.yaml

Android 빌드 job의 Gradle 셋업 단계 직전에 2개 step 추가:

Step 1 - Setup Release Keystore

• RELEASE_KEYSTORE_BASE64 Secret이 존재하는 경우에만 실행 (if 조건)
• base64 디코딩하여 android/app/keystore/key.jks 파일 생성

Step 2 - Create key.properties

• RELEASE_KEYSTORE_BASE64 Secret이 존재하는 경우에만 실행
• android/key.properties 파일에 keystore 경로 및 서명 정보 작성
• 사용하는 Secrets: RELEASE_KEYSTORE_PASSWORD, RELEASE_KEY_ALIAS, RELEASE_KEY_PASSWORD

동작 흐름:

Secrets 있음 → keystore 생성 → key.properties 생성 → release 서명 빌드
Secrets 없음 → 두 step 모두 스킵 → key.properties 없음 → debug fallback 빌드

android/app/build.gradle.kts

release buildType의 signingConfig 설정을 조건부로 변경:

변경 전:

signingConfig = signingConfigs.getByName("release")

변경 후:

signingConfig = if (keystorePropertiesFile.exists()) {
    signingConfigs.getByName("release")
} else {
    signingConfigs.getByName("debug")
}

keystorePropertiesFile은 파일 상단(15번째 줄)에서 이미 rootProject.file("key.properties")로 선언되어 있으므로 별도 수정 없이 해당 변수를 재활용.

---

🧪 테스트 및 검증

• CI에서 Android APK 빌드가 정상 성공하는지 확인 (main 브랜치 push 후)
• GitHub Secrets에 RELEASE_KEYSTORE_BASE64, RELEASE_KEYSTORE_PASSWORD, RELEASE_KEY_ALIAS, RELEASE_KEY_PASSWORD가 이미 설정되어 있는지 확인 (Play Store CICD에서 사용 중이므로 이미 존재할 것으로 예상)
• iOS 빌드에 영향 없는지 확인
• Play Store CICD 워크플로우에 영향 없는지 확인

---

📌 참고사항

• CI workflow와 Play Store CICD workflow는 동일한 GitHub Secrets를 공유하므로 별도의 Secrets 추가 설정은 불필요
• build.gradle.kts의 debug fallback은 로컬 개발 환경에서도 유용. keystore 설정 없이 flutter build apk --release 실행 가능
• 기존 Play Store CICD 워크플로우(PROJECT-FLUTTER-ANDROID-PLAYSTORE-CICD.yaml)는 자체적으로 keystore를 설정하므로 이번 변경에 영향받지 않음