본문 바로가기

클라우드에서 Capacitor 앱에 서명하고 빌드하는 방법

클라우드에서 Capacitor 앱을 서명하고 빌드하세요: Android keystore와 iOS 인증서를 생성하고, 인증 정보를 안전하게 저장하고, CI에서 서명된 빌드를 실행하세요.

클라우드 빌드에서 Capacitor 앱 서명에 사용하는 iOS 인증서와 Android 키스토어

클라우드에서 Capacitor 앱을 서명하고 빌드하려면 서명 자료(Android 키스토어, iOS 배포 인증서 및 프로비저닝 프로필)를 한 번 생성해 클라우드 빌드 서비스에 제공한 다음 터미널 또는 CI에서 빌드를 트리거합니다. 이 서비스는 네이티브 프로젝트를 컴파일하고 서명하며, TestFlight 또는 Google Play에 바로 업로드할 수 있습니다. 이 가이드에서는 각 서명 파일, Mac 없이 생성하는 방법, Capgo Build로 설정하는 방법, 서명된 빌드를 안전하게 자동화하는 방법을 다룹니다.

“클라우드 서명”이란

두 스토어 모두 서명된 바이너리만 허용합니다. 서명은 빌드가 본인에게서 나왔고 이후 아무도 변경하지 않았음을 증명합니다. 로컬에서는 Xcode와 Android Studio가 이 과정을 대부분 숨겨주지만, 클라우드에서는 암묵적으로 처리되는 게 없으므로 어떤 파일이 관련되는지 정확히 알아야 합니다:

플랫폼 파일 무엇인가요? 용도
Android .jks / .keystore upload 키를 보관하는 Keystore AAB 또는 APK 서명
Android 서비스 계정 .json Google Cloud 자격 증명 Google Play에 업로드
iOS .p12 Apple Distribution 인증서 및 개인 키 IPA 서명
iOS .mobileprovision Bundle ID, 인증서, Capabilities를 묶는 Provisioning profile 앱을 실행하고 배포할 수 있도록 허용
iOS .p8 + Key ID + Issuer ID App Store Connect API 키 TestFlight 업로드 및 빌드 번호 확인

Git에 커밋하지 마세요. 아래의 모든 방법은 이 값들을 로컬 자격 증명 파일이나 CI의 secret store에 저장합니다.

Android 서명

업로드용 keystore 생성하기

앱이 이미 Google Play에 출시되어 있다면 기존 keystore를 재사용하세요. Play Console의 upload key 재설정 과정을 거치지 않고 다른 키로 업데이트를 서명하면 거부됩니다.

새 앱의 경우:

keytool -genkeypair -v \
  -storetype PKCS12 \
  -keystore release.jks \
  -alias upload \
  -keyalg RSA -keysize 2048 \
  -validity 10000

참고:

  • Google Play에서는 키가 최소 2033년 10월 22일까지 유효해야 합니다. -validity 10000 (약 27년 정도)면 충분합니다.
  • PKCS12 스토어 타입을 사용하면 키 비밀번호와 스토어 비밀번호가 동일합니다.
  • JDK가 없나요? Android 키스토어 생성기 브라우저에서 동일한 파일을 생성할 수 있습니다.

Play App Signing과 upload key

Google Play의 새 앱은 Play App Signing을 사용합니다. Google이 앱 서명 키 가 사용자가 다운로드하는 항목에 다시 서명합니다. 키스토어는 키 업로드입니다. 분실해도 Play Console 지원팀에서 새 업로드 키를 등록할 수 있으므로, 분실은 지연일 뿐 재앙은 아닙니다. 그래도 백업해 두세요.

업로드용 서비스 계정

클라우드에서 업로드하려면 Google Cloud에서 서비스 계정을 만들고, Google Play Android Developer API를 사용 설정한 뒤 JSON 키를 다운로드하고, 서비스 계정을 초대하려면 Play Console의 사용자 및 권한 앱에 대한 릴리스 권한이 필요합니다. 아래에 표시된 대로 Google 로그인으로 Capgo 온보딩을 통해 이 작업을 수행할 수 있습니다.

iOS 서명

Apple의 세 가지 구성 요소

  • Apple Distribution 인증서. 팀당 하나면 충분하며 유효 기간은 1년입니다. Apple은 보유 수에 제한을 두므로 개발자별로 생성하지 마세요.
  • Provisioning 프로필. Bundle ID, 인증서, 푸시 알림과 같은 기능을 연결합니다. TestFlight와 App Store에는 App Store Connect 프로필을, 등록된 기기 설치에는 Ad Hoc 프로필을 사용하세요. 각 앱 확장(위젯, 공유 확장, 알림 서비스)에는 자체 프로필이 필요합니다.
  • App Store Connect API 키. 생성 위치 사용자 및 액세스 > 통합 App Manager 액세스 권한으로. .p8 파일은 한 번만 다운로드됩니다.

Apple Developer 팀에서 이러한 항목을 생성하려면 관리자 또는 계정 소유자 권한이 필요합니다.

Mac 없이 인증서 생성

Keychain Access 플로우에는 macOS가 필요하지만, OpenSSL은 어디서든 작동합니다:

# 1. Private key and certificate signing request
openssl req -new -newkey rsa:2048 -nodes \
  -keyout dist.key -out dist.csr \
  -subj "/emailAddress=dev@example.com/CN=Example Inc/C=US"

# 2. Upload dist.csr at developer.apple.com > Certificates > + > Apple Distribution
#    and download distribution.cer

# 3. Convert and bundle into a .p12
openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -legacy \
  -inkey dist.key -in distribution.pem \
  -out distribution.p12 -passout pass:choose-a-password

이 -legacy OpenSSL 3에서는 플래그가 중요합니다. 없으면 macOS 빌드 머신에서 .p12 “MAC verification failed” 오류와 함께. 브라우저 기반 iOS 인증서 생성기 을 사용하면 동일한 단계를 수행할 수 있습니다.

그 다음 개발자 포털에서 프로비저닝 프로필을 생성하세요 (Profiles > + > App Store Connect). 앱 ID와 새 인증서를 선택한 후 다운로드하세요.

Capgo Build로 서명 설정하기

Capgo 빌드 Capacitor은 Capgo 관리 머신에서 Capacitor 앱을 컴파일하고 서명하므로, Windows나 Linux에서도 iOS 빌드가 가능합니다. 로그인하고 앱을 등록하는 것부터 시작하세요:

bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build init --platform android

iOS의 경우 온보딩 과정에서 App Store Connect API 키를 사용하여 배포 인증서와 App Store 프로비저닝 프로필을 생성하거나 재사용합니다. macOS에서는 해당 API 키 생성 과정을 안내해 줄 수도 있습니다. Android의 경우 키스토어를 생성하거나 가져오며, Google 로그인으로 Google Cloud 서비스 계정과 Play Console 초대장을 프로비저닝할 수 있습니다. 마지막에 첫 빌드를 시작하도록 제안합니다.

옵션 B: 기존 파일 저장

이전 섹션에서 파일을 이미 보유하고 있다면:

# iOS
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./distribution.p12 \
  --p12-password "choose-a-password" \
  --ios-provisioning-profile ./AppStore.mobileprovision \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id 00000000-0000-0000-0000-000000000000 \
  --apple-team-id TEAM123456

# Android
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.jks \
  --keystore-alias upload \
  --keystore-key-password "store-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

확장 기능이 있는 앱의 경우 반복하세요 --ios-provisioning-profile 와 함께 bundleId=path 각 타깃별 매핑:

  --ios-provisioning-profile com.example.app=./App.mobileprovision \
  --ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision

자격 증명은 ~/.capgo-credentials/credentials.json에 앱 ID와 플랫폼을 키로 저장됩니다. 추가하려면 --local 을(를) 사용하여 프로젝트의 .capgo-credentials.json 에 대신 저장하고, 해당 파일을 .gitignore에 추가하세요. 저장된 내용을 확인하려면 bunx @capgo/cli@latest build credentials list.

서명된 빌드 실행

네이티브 프로젝트를 준비한 후 빌드를 요청하세요:

bun run build
bunx cap sync

# iOS: sign with the App Store profile and upload to TestFlight
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

# Android: sign the AAB and upload to the internal track
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release --android-track internal

로그가 터미널로 스트리밍됩니다. 사전 빌드 스캔이 업로드 전에 인증서 만료, 비밀번호, 프로필 페어링을 확인하므로 대부분의 서명 오류는 몇 분이 아니라 몇 초 만에 실패합니다. 단독으로 실행하려면 bunx @capgo/cli@latest build prescan --platform ios.

유용한 옵션:

목표 플래그
등록된 iPhone에서 테스트 빌드 --ios-distribution ad_hoc --ios-provisioning-profile ./adhoc.mobileprovision --output-upload
MDM 또는 키오스크용 APK --platform android --no-playstore-upload --output-upload
App Review로 바로 제출 --submit-to-store-review --store-release-name 2.4.0
직접 지정한 빌드 번호 유지 --skip-build-number-bump
캐시 없는 클린 빌드 --no-cache

ad hoc 빌드의 경우, 먼저 기기의 UDID를 수집한 뒤 iOS UDID 찾기 프로파일에 추가하세요.

CI에서 서명된 빌드 자동화

CI에서는 자격 증명 파일을 대신 환경 변수로 자격 증명을 전달하세요. CLI은 필요한 것만 정확히 내보냅니다:

bunx @capgo/cli@latest build credentials manage --appId com.example.app
# choose "Export to .env"

GitHub에서 모든 줄을 한 명령으로 리포지토리 시크릿에 푸시한 뒤 파일을 삭제하세요:

gh secret set -f .env.capgo.com.example.app
gh secret set CAPGO_TOKEN --body "your-capgo-api-key"
rm .env.capgo.com.example.app

태그 시 두 플랫폼 모두를 서명하고 배포하는 릴리스 워크플로:

name: Signed release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}
      - run: bunx @capgo/cli@latest build request com.example.app --platform ${{ matrix.platform }} --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

작업은 Linux에서 실행됩니다. macOS 러너도, 키체인 명령도, fastlane도 필요 없습니다. 동일한 환경 변수를 모든 CI에서 사용할 수 있습니다: GitLab CI/CD 변수, Bitbucket 보안 변수, Gitea 시크릿 또는 Azure DevOps 변수 그룹. 플랫폼별 가이드: Bitbucket Pipelines, Gitea Actions, 그리고 GitHub Actions 문서.

키 관리 방식

클라우드 서비스에 서명 키를 맡기기 전, 당연히 궁금할 수 있는 부분입니다. Capgo Build의 경우:

  • 자격 증명은 로컬 머신(~/.capgo-credentials/) 또는 CI secret store에 저장됩니다. Capgo는 사용자의 키를 별도로 보관하지 않습니다.
  • 빌드 시마다 CLI는 HTTPS를 통해 키를 전송합니다. 키는 해당 빌드 중에만 사용되며 빌드가 완료되면 즉시 삭제됩니다.
  • 준비된 네이티브 프로젝트만 업로드됩니다. 웹 소스 .git, 그리고 .env 파일은 포함되지 않습니다.
  • 빌드된 앱은 App Store Connect 또는 Google Play로 직접 전송되거나, 요청하면 일정 기간 유효한 다운로드 링크로 제공됩니다.

주의할 점: 자격 증명을 교체하려면 CI secrets를 직접 업데이트해야 합니다. 다시 export한 뒤 build credentials manage 파일을 다시 push하세요.

만료 및 교체

항목 누적 해결 방법
Apple Distribution 인증서 1년 새로 생성, 프로필 재생성, 다시 저장, CI 업데이트
프로비저닝 프로파일 1년 또는 인증서가 폐기될 때까지 재생성 후 다시 저장
App Store Connect API 키 폐기될 때까지 액세스 권한이 있는 사람이 떠날 때 폐기
Android 업로드 키스토어 유효기간 동안 (수십 년으로 설정) 백업; 분실 시 Play Console에서 재설정
Play 서비스 계정 키 삭제될 때까지 연 1회 또는 액세스 변경 시 로테이션

Apple 날짜를 공유 캘린더에 기록하세요. 만료된 인증서는 이미 사용자 기기에 설치된 앱에는 영향을 주지 않지만, 모든 신규 빌드를 차단합니다.

문제 해결

오류 원인 및 해결 방법
Provisioning profile doesn't include signing certificate 다른 인증서로 프로파일이 생성되었습니다. 현재 인증서로 다시 생성하세요.
Provisioning profile doesn't match bundle ID 다른 앱 ID로 프로파일이 생성되었거나 확장성 대상이 누락되었습니다. 각 대상에 대해 bundleId=path 매핑을 추가하세요.
MAC verification failed 잘못된 .p12 비밀번호, 또는 OpenSSL 3 내보내기에 -legacy.
Keystore was tampered with, or password was incorrect 스토어 비밀번호가 잘못되었거나, base64 줄바꿈으로 파일이 손상되었습니다.
Key alias not found 키스토어의 것과 별칭이 다릅니다. 다음으로 목록을 확인하세요: keytool -list -keystore release.jks.
App Store Connect 인증 실패 키 ID 또는 발급자 ID가 잘못되었거나, 키가 폐기되었거나, 토큰에 서명하는 기기의 시스템 시계가 어긋나 있습니다.
Play 업로드: 호출자에게 권한이 없습니다 Play Console에 서비스 계정이 초대되지 않았거나, Android Developer API가 활성화되지 않았습니다.

추가 수정 사항은 Capgo 빌드 문제 해결 가이드에 있습니다 및 Capacitor를 위한 CI/CD: 흔한 함정.

첫 서명 빌드 이후

서명된 네이티브 빌드는 네이티브 code가 변경될 때만 필요합니다. JavaScript, CSS, HTML 변경 사항은 live update를 대신 설치된 앱에 배포하고, 플러그인이나 네이티브 설정을 건드리는 릴리스에만 스토어 빌드를 사용하세요. Mac 기반 환경에서 넘어왔다면, Capgo Build로 Windows에서 iOS 앱 빌드하기 macOS 없이 전체 워크플로우를 보여줍니다.

Capacitor 앱용 Live updates

웹 레이어 버그가 라이브 상태라면, 앱 스토어 승인을 며칠씩 기다리지 말고 Capgo를 통해 수정 사항을 배포하세요. 네이티브 변경 사항은 정상 리뷰 절차를 그대로 따르는 반면, 사용자는 백그라운드에서 업데이트를 받습니다.

블로그 최신 글

Capgo는 정말 프로페셔널한 모바일 앱을 만드는 데 필요한 최고의 인사이트를 제공합니다.