zellyy-finance/docs/ios-signing-setup.md

iOS 코드 서명 설정 가이드

1. Apple Developer 계정 설정

필수 준비사항

• Apple Developer Program 계정 (연간 $99)
• Xcode 15.0 이상
• macOS 빌드 환경

App Store Connect 설정

1. App Store Connect 로그인
2. "My Apps" > "+" > "New App" 클릭
3. 앱 정보 입력:
   • Platform: iOS
   • Name: Zellyy Finance
   • Primary Language: Korean
   • Bundle ID: com.zellyy.finance
   • SKU: zellyy-finance-ios

2. 인증서 및 프로비저닝 프로파일 생성

Developer 계정에서 생성 (수동)

1. Apple Developer Portal 접속
2. Certificates, Identifiers & Profiles 섹션으로 이동

인증서 생성

# 1. CSR(Certificate Signing Request) 생성
# 키체인 접근 > 인증서 지원 > 인증 기관에서 인증서 요청

# 2. Apple Developer Portal에서 인증서 생성
# - iOS Distribution (App Store and Ad Hoc)
# - CSR 파일 업로드
# - 생성된 인증서(.cer) 다운로드 및 키체인에 설치

App ID 생성/확인

- Identifier: com.zellyy.finance
- Description: Zellyy Finance
- Capabilities: 필요한 기능들 활성화 (Push Notifications 등)

프로비저닝 프로파일 생성

- Type: App Store
- App ID: com.zellyy.finance
- Certificate: 위에서 생성한 Distribution 인증서
- Profile Name: Zellyy Finance App Store

API 키를 통한 자동화 (권장)

# App Store Connect API 키 생성
# App Store Connect > 사용자 및 액세스 > 키 > API 키 > "+" 클릭
# - 이름: Zellyy Finance CI/CD
# - 액세스: App Manager 또는 Developer
# - 키 다운로드 (.p8 파일)

3. Xcode 프로젝트 설정

Team 및 Bundle Identifier 설정

# ios/App/App.xcodeproj 열기
# 프로젝트 설정 > Signing & Capabilities
# - Team: Apple Developer 팀 선택
# - Bundle Identifier: com.zellyy.finance
# - Signing Certificate: iOS Distribution

빌드 설정 확인

# ios/App/App/Info.plist 확인
CFBundleIdentifier: com.zellyy.finance
CFBundleDisplayName: Zellyy Finance
CFBundleShortVersionString: 1.0.0
CFBundleVersion: 10000

4. GitHub Actions용 인증서 내보내기

인증서를 P12로 내보내기

# 키체인 접근에서:
# 1. iOS Distribution 인증서 선택
# 2. 개인키와 함께 내보내기 선택
# 3. .p12 파일로 저장
# 4. 내보내기 비밀번호 설정

Base64로 인코딩

# P12 파일을 base64로 인코딩
base64 -i ios-distribution.p12 | pbcopy
# 결과를 IOS_CERTIFICATES_P12_BASE64 시크릿에 저장

프로비저닝 프로파일 내보내기

# ~/Library/MobileDevice/Provisioning Profiles/ 에서 찾거나
# Apple Developer Portal에서 다운로드
base64 -i ZellyyFinance_AppStore.mobileprovision | pbcopy

5. GitHub Secrets 설정

iOS 관련 시크릿들

• IOS_CERTIFICATES_P12_BASE64: P12 인증서 파일의 base64 인코딩
• IOS_CERTIFICATES_P12_PASSWORD: P12 파일 내보내기 시 설정한 비밀번호
• IOS_PROVISIONING_PROFILE_BASE64: 프로비저닝 프로파일의 base64 인코딩

App Store Connect API 시크릿들

• APPSTORE_ISSUER_ID: App Store Connect API 발급자 ID
• APPSTORE_KEY_ID: App Store Connect API 키 ID
• APPSTORE_PRIVATE_KEY: App Store Connect API 개인 키 (.p8 파일 내용)

6. ExportOptions.plist 설정 확인

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
    <key>provisioningProfiles</key>
    <dict>
        <key>com.zellyy.finance</key>
        <string>Zellyy Finance App Store</string>
    </dict>
    <key>signingCertificate</key>
    <string>iPhone Distribution</string>
    <key>signingStyle</key>
    <string>manual</string>
</dict>
</plist>

7. 로컬 빌드 테스트

릴리즈 빌드 테스트

# 웹 앱 빌드
npm run build:prod

# Capacitor 동기화
npm run mobile:sync

# iOS 프로젝트 열기
npm run ios:open

# Xcode에서 Archive 빌드
# Product > Archive 선택
# Archive 성공 시 Organizer에서 확인

명령어로 빌드 테스트

cd ios/App

# CocoaPods 의존성 설치
pod install

# 릴리즈 빌드
xcodebuild -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath App.xcarchive \
  archive

# IPA 내보내기
xcodebuild -exportArchive \
  -archivePath App.xcarchive \
  -exportPath ./build \
  -exportOptionsPlist ExportOptions.plist

8. TestFlight 배포 설정

자동 업로드 설정

# fastlane 설치 (옵션)
gem install fastlane

# TestFlight 업로드
xcrun altool --upload-app \
  --type ios \
  --file "App.ipa" \
  --username "your-apple-id@example.com" \
  --password "app-specific-password"

GitHub Actions 통합

# .github/workflows/mobile-build.yml에서 사용
- name: Upload to TestFlight
  uses: Apple-Actions/upload-testflight-build@v1
  with:
    app-path: ios/App/build/App.ipa
    issuer-id: ${{ secrets.APPSTORE_ISSUER_ID }}
    api-key-id: ${{ secrets.APPSTORE_KEY_ID }}
    api-private-key: ${{ secrets.APPSTORE_PRIVATE_KEY }}

9. 보안 고려사항

인증서 관리

• P12 파일 및 프로비저닝 프로파일은 git에 커밋하지 않음
• Apple Developer 계정의 2단계 인증 활성화
• App Store Connect API 키는 최소 권한으로 설정

CI/CD 보안

• GitHub Secrets로 모든 민감 정보 보호
• 릴리즈 브랜치에서만 서명된 빌드 생성
• 빌드 로그에서 민감 정보 노출 방지

10. 문제 해결

일반적인 오류들

• Code signing error: 인증서 또는 프로비저닝 프로파일 문제
• Bundle ID mismatch: Bundle Identifier 불일치
• Provisioning profile expired: 프로비저닝 프로파일 만료
• Team ID not found: Apple Developer 팀 설정 오류

디버깅 명령어

# 코드 서명 정보 확인
security find-identity -v -p codesigning

# 프로비저닝 프로파일 확인
ls ~/Library/MobileDevice/Provisioning\ Profiles/

# Xcode 빌드 로그 확인
xcodebuild -workspace App.xcworkspace -scheme App -configuration Release build | xcpretty

유용한 도구들

• iOS App Signer: GUI 코드 서명 도구
• fastlane: iOS 배포 자동화 도구
• xcpretty: Xcode 빌드 로그 포맷터