🚀[기능개선][CICD] AppStore/PlayStore 배포 지원 대폭 개선 > 심사 자동 제출 + 배포 모드 3단계 통일

[Cassiiopeia]

📝 개요

iOS(App Store) · Android(Play Store) 스토어 배포 CICD를 전면 개선 완료했다. 이 문서는 이 이슈만 보고도 처음 보는 사람이 동일한 배포 파이프라인을 작성·유지보수할 수 있도록 파일별 역할, 의존성, 시크릿, 실제 코드, 동작 흐름, 트러블슈팅을 모두 정리한다.

관련 이슈: #930(Android 거짓 성공 제거), #931(iOS 심사 자동 제출 누락). 상세 구현 보고서는 #931 댓글 참조.

최종 결과: 코드 push 한 번으로 빌드 → 스토어 업로드 → (모드에 따라) 심사 직전 또는 심사 자동 제출까지 자동화. iOS 1.10.104가 실제 App Store 심사 큐(Waiting for Review)에 자동 진입 실측 검증 완료. Android 1.10.101 production "검토 중" 진입 검증 완료.

---

🗂️ 1. 파일 구성과 의존성

1-1. 운영 워크플로우 (실제 배포가 도는 곳)

파일	역할	트리거
.github/workflows/ROMROM-IOS-TESTFLIGHT.yaml	iOS 빌드 → TestFlight → App Store deliver	push: deploy / workflow_run(CHANGELOG) / workflow_dispatch
.github/workflows/ROMROM-ANDROID-PLAYSTORE-CICD.yaml	Android 빌드 → internal → production promote	동일

중요: 두 워크플로우 모두 ref: deploy를 checkout 한다. 즉 deploy 브랜치의 코드/Fastfile로 빌드한다. main에만 머지하면 배포에 반영 안 됨 → main → deploy 머지 필요.

1-2. Fastlane 설정 파일

파일	역할	누가 사용
android/fastlane/Fastfile.playstore	Android lane(deploy_internal, promote_internal_to_production)	Android 워크플로우가 Fastfile로 복사해 사용
(iOS) 인라인 Fastfile	iOS 워크플로우 step 안에서 cat > ios/fastlane/Fastfile 로 동적 생성	iOS 워크플로우 자체

iOS는 별도 Fastfile 파일이 없다. 워크플로우 step "Install Fastlane and create Fastfile"이 heredoc으로 ios/fastlane/Fastfile을 그 자리에서 만든다. iOS deliver 로직을 고치려면 이 워크플로우 YAML 안의 heredoc을 수정해야 한다.

1-3. 마법사(wizard) 템플릿 — 신규 프로젝트 셋업용

파일	역할
.github/util/flutter/testflight-wizard/templates/Fastfile	iOS Fastfile 템플릿 (신규 프로젝트가 ios/fastlane/Fastfile로 받음). 운영 인라인 Fastfile과 동일 로직 유지
.github/util/flutter/testflight-wizard/templates/Gemfile	fastlane ~> 2.228 + multi_json
.github/util/flutter/testflight-wizard/testflight-wizard-setup.sh	위 템플릿들을 프로젝트에 설치 + Xcode Manual Signing 패치
.github/util/flutter/playstore-wizard/playstore-wizard-setup.sh/.ps1	Android 셋업(+multi_json)

유지보수 원칙: 운영 워크플로우(인라인 Fastfile)를 고치면 wizard 템플릿도 같이 고쳐야 둘이 분기되지 않는다.

---

⚙️ 2. 필요한 GitHub Secrets / Variables

2-1. iOS Secrets

Secret	용도
APPLE_CERTIFICATE_BASE64 / APPLE_CERTIFICATE_PASSWORD	Distribution 인증서(.p12)
APPLE_PROVISIONING_PROFILE_BASE64	Provisioning Profile
APP_STORE_CONNECT_API_KEY_BASE64 / APP_STORE_CONNECT_API_KEY_ID / APP_STORE_CONNECT_ISSUER_ID	App Store Connect API Key(.p8) — pilot·deliver 인증
ENV_FILE, SECRETS_XCCONFIG, GOOGLE_SERVICE_INFO_PLIST	앱 환경/Firebase

2-2. Android Secrets

Secret	용도
Release Keystore 관련	AAB 서명
GOOGLE_PLAY_JSON_KEY(서비스 계정)	Play Console API

2-3. Repository Variables (배포 모드 제어)

Variable	기본(폴백)	효과
IOS_DEPLOY_MODE	testflight_only	iOS 평소 자동 배포 모드
ANDROID_DEPLOY_MODE	store_submit	Android 평소 자동 배포 모드

우선순위: workflow_dispatch input > repo variable > 폴백.

---

🎛️ 3. 배포 모드 3단계 (양 플랫폼 공통 개념)

모드	iOS (App Store)	Android (Play Store)	사람 개입
store_only	TestFlight 업로드까지만 (pilot)	internal 트랙 업로드까지만	없음(테스트용)
store_prepare	버전 생성 + 빌드 선택 + What's New 채워 Prepare for Submission	production draft 승급	ASC에서 Add for Review / 콘솔에서 "출시 시작"
store_submit	submit_for_review로 심사 자동 제출	production completed 승급(심사 자동 등록)	없음(완전 자동)

iOS는 testflight_only/appstore_prepare/appstore_submit 네이밍과 store_* 둘 다 인식(Fastfile에서 별칭 처리).

flowchart TD
    A(["코드 push → deploy"]) --> B["Flutter 빌드 + 코드사인 + IPA/AAB"]
    B --> C["스토어 업로드 (pilot / internal)"]
    C --> D{"DEPLOY_MODE?"}
    D -->|store_only| E(["업로드까지만 — 종료"])
    D -->|store_prepare| F["빌드 처리 대기 → deliver/promote(draft)"]
    D -->|store_submit| G["빌드 처리 대기 → deliver/promote(completed)"]
    F --> H(["제출 직전 — 사람이 버튼 클릭"])
    G --> I(["심사 자동 제출 — Waiting for Review"])

Loading

---

🍏 4. iOS deliver 핵심 코드 (인라인 Fastfile)

iOS 워크플로우의 deploy_appstore lane 중 deliver 부분. 6개 옵션이 각각 특정 실패를 막는다 — 하나라도 빠지면 그 단계에서 실패한다.

# 모드 판정 (store_* / appstore_* 별칭 호환)
deploy_mode = (ENV["DEPLOY_MODE"] || "testflight_only").strip
prepare_appstore = ["appstore_prepare","appstore_submit","store_prepare","store_submit"].include?(deploy_mode)
submit_to_appstore = ["appstore_submit","store_submit"].include?(deploy_mode)

# 1) TestFlight 업로드 (항상). ASC 모드면 빌드 처리 완료까지 대기(deliver가 그 빌드를 골라야 하므로)
pilot(
  api_key: api_key,
  app_identifier: app_id,                              # 없으면 비대화형 crash
  ipa: ENV["IPA_PATH"],
  changelog: ENV["RELEASE_NOTES"],
  skip_waiting_for_build_processing: !prepare_appstore # store_only면 대기 안 함
)

if prepare_appstore
  # whatsNew(What's New) 메타를 절대경로로 생성 — ⚠️ 로케일은 'ko'만 유효(ko-KR 무효)
  metadata_path = File.join(ENV["GITHUB_WORKSPACE"], "ios", "fastlane", "metadata")
  FileUtils.mkdir_p(File.join(metadata_path, "ko"))
  File.write(File.join(metadata_path, "ko", "release_notes.txt"), release_notes)
  # 심사 Notes 초기화(이전 거절 소명서 자동승계 방지) — notes.txt만 비움, 연락처·데모는 ASC 기존값 보존
  FileUtils.mkdir_p(File.join(metadata_path, "review_information"))
  File.write(File.join(metadata_path, "review_information", "notes.txt"), "")

  deliver(
    api_key: api_key,
    app_identifier: app_id,                 # [원인1] Bundle ID 미전달 → crash
    app_version: ENV["APP_VERSION"],        # [원인2] editable 버전 자동 생성/선택
    build_number: ENV["BUILD_NUMBER"],      # [원인5] 빌드 명시 선택(skip_metadata:false면 자동선택 누락)
    submit_for_review: submit_to_appstore,  # store_submit이면 심사 제출
    automatic_release: submit_to_appstore,
    force: true,                            # CI 비대화형
    run_precheck_before_submit: false,
    skip_binary_upload: true,               # pilot으로 올린 빌드 사용
    skip_metadata: false,                   # whatsNew/notes 업로드 위해 false
    metadata_path: metadata_path,           # [원인3] 절대경로 (상대경로는 CWD 어긋남)
    skip_screenshots: true
    # app_review_information은 안 넘김 → ASC 기존 연락처·데모계정 보존(개인정보 하드코딩 방지)
  )
end

워크플로우 step이 deliver에 넘기는 ENV (deploy-testflight job):

export APP_IDENTIFIER="com.alom.romrom"
export APP_VERSION="${{ needs.prepare-build.outputs.version }}"
export BUILD_NUMBER="${{ needs.prepare-build.outputs.build_number }}"
export DEPLOY_MODE="${{ env.DEPLOY_MODE }}"
export RELEASE_NOTES="$(cat final_release_notes.txt)"

---

🤖 5. Android promote 핵심 코드 (Fastfile.playstore)

deploy_mode = (ENV["DEPLOY_MODE"] || "store_submit").strip
promote = ["store_prepare","store_submit","appstore_prepare","appstore_submit"].include?(deploy_mode)
submit  = ["store_submit","appstore_submit"].include?(deploy_mode)

# Step1: internal 트랙 업로드 (completed)
upload_to_play_store(package_name: 'com.alom.romrom', track: 'internal',
  aab: ENV["AAB_PATH"], json_key: ENV["GOOGLE_PLAY_JSON_KEY"], release_status: 'completed', ...)

next unless promote   # store_only면 여기서 종료

# Step2: production 승급 — submit이면 completed(심사 자동등록), prepare면 draft
promote_internal_to_production(promote_status: submit ? 'completed' : 'draft')

lane :promote_internal_to_production do |options|
  upload_to_play_store(
    track: 'internal', track_promote_to: 'production',
    track_promote_release_status: options[:promote_status] || 'completed',
    rollout: '1.0',
    changes_not_sent_for_review: false,        # 변경을 심사로 전송
    rescue_changes_not_sent_for_review: false  # [거짓성공 차단] 실패 시 워크플로우 빨간불
  )
end

거짓 성공의 정체: fastlane supply의 rescue_changes_not_sent_for_review 기본값이 true라, Google API가 "changesNotSentForReview를 true로 설정하라" 에러를 내면 fastlane이 자동 rescue해 심사 안 보내고 저장만 한 채 success 반환한다. false로 명시해야 실패가 표면화된다.

---

⚠️ 6. 트러블슈팅 (실제 겪은 6개 원인)

증상(로그)	원인	해결
Could not infer your App's Bundle Identifier	deliver에 app_identifier 없음(비대화형)	app_identifier 명시
Cannot submit for review - could not find an editable version	App Store에 해당 버전 페이지 없음	app_version 명시(자동 생성)
missing required attribute 'whatsNew'	What's New 메타 미반영(경로 어긋남)	metadata_path 절대경로
Unsupported directory name(s) ... ko-KR	fastlane 미지원 로케일 코드	ko만 사용(ko-KR 금지)
1.10.x 버전에 엉뚱한 이전 빌드가 붙음	skip_metadata:false면 deliver가 빌드 자동선택 건너뜀	build_number 명시
Notes에 옛 거절 소명서가 매번 남음	ASC가 이전 버전 Notes 자동 승계	review_information/notes.txt 빈 파일

Apple 빌드 처리(Processing) 병목 — 코드 문제 아님

store_prepare/store_submit은 deliver가 "방금 올린 그 빌드"(같은 버전 정합성)를 골라야 하므로 pilot이 그 빌드의 Processing → Complete를 기다린다. 이 시간은 Apple 서버 사정(보통 5~15분, 때때로 1시간+, 통제 불가). CI가 "TestFlight 배포" step에서 오래 멈춰도 hang이 아니다. 급하면 store_only 사용. 단기간 연속 업로드는 Processing 큐를 밀리게 하므로 자제.

---

✅ 7. 운영 체크리스트

• main 변경 후 deploy 브랜치에 머지해야 배포에 반영됨 (ref: deploy)
• 평소 기본: iOS store_prepare(제출 직전, 안전) / Android store_submit(자동 심사)
• 심사까지 자동 원하면: iOS도 IOS_DEPLOY_MODE=store_submit 또는 dispatch에서 선택
• 인라인 Fastfile(운영) 수정 시 wizard 템플릿도 동기화
• iOS 로케일은 항상 ko(ko-KR 금지), 다른 로케일은 DELIVER_LOCALES ENV로 추가
• 개인정보(연락처·데모계정)는 ASC에서 관리, 코드에 하드코딩 금지

🙋‍♂️ 담당자

• 프론트엔드: @Cassiiopeia

[SeoHyun1024]

Guide by SUH-LAB

브랜치

20260622_#934_AppStore_PlayStore_배포_지원_대폭_개선_심사_자동_제출_배포_모드_3단계_통일

커밋 메시지

AppStore/PlayStore 배포 지원 대폭 개선 > 심사 자동 제출 + 배포 모드 3단계 통일 : feat : {변경 사항에 대한 설명} https://github.com/TEAM-ROMROM/RomRom-FE/issues/934