iOS 빌드

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

Capgo의 전용 Mac 인프라를 사용해 iOS 앱을 빌드하고 TestFlight와 App Store에 제출하세요.

배우게 될 내용

Capgo Native Build를 통해 앱을 업로드하는 방법을 배웁니다.
Capgo Native Build 인증서를 설정하는 방법을 배웁니다.

사전 요구사항

Capgo 계정 (무료 체험으로도 시작하기에 충분합니다)
Capgo에 앱이 이미 등록되어 있음 (실행 bunx @capgo/cli@latest app add 등록되지 않은 경우)
Mac 불필요: Capgo Build는 클라우드에서 iOS 앱을 컴파일하고 서명하므로 macOS, Windows, Linux 어디서든 실행할 수 있습니다.
유효한 Apple Developer 계정 (연 $99) (Apple Developer 계정에서 관리자 또는 소유자 권한이 있어야 합니다)
앱이 성공적으로 빌드되어야 합니다 (로컬 Xcode 또는 Capgo Build 사용)
Capacitor 앱
앱에 설정된 아이콘. 아이콘이 없는 앱은 App Store에 업로드할 수 없습니다.

Apple 포털에서 시작하기 전

인증서를 설정하거나 첫 TestFlight 업로드를 트리거하기 전에, Apple 계정과 팀이 준비되어 있는지 확인하세요:

가입에 사용하는 Apple 계정의 이중 인증을 켜세요
적절한 멤버십 유형을 선택하세요:
- 개인 / 개인 사업자개인 계정: 법적 실명이 App Store의 판매자 이름이 됩니다
- 조직: 법인, D-U-N-S 번호, 공개된 회사 웹사이트, 회사 도메인의 업무용 이메일, Apple 계약에 조직을 구속할 권한이 있는 담당자가 필요합니다
인증서, 앱 레코드, API 키 및 TestFlight를 위해 Apple Developer와 App Store Connect 모두에 접근 가능한 계정을 사용하세요
최종 bundle ID를 조기에 확정하세요. 나중에 변경하면 보통 App Store 설정을 처음부터 다시 해야 합니다
App Review 전에 다음 App Store Connect 항목을 준비하세요: 지원 URL, 개인정보 처리방침 URL, 연령 등급, 스크린샷, 수출 규정 준수, App Review 연락처 정보

이 모든 걸 직접 할 필요는 없습니다. Capgo의 온보딩이 iOS 서명 자격 증명(배포 인증서 + 프로비저닝 프로필)을 생성하고 설정해 줍니다. 권장되는 방법입니다:

bunx @capgo/cli@latest build init --platform ios

아래 수동 안내는 자격 증명을 직접 설정하려는 분, 또는 Capgo가 내부에서 정확히 어떻게 동작하는지 이해하려는 분만을 위한 것입니다.

첫 번째 수동 빌드

Capgo로 앱 빌드를 생각하기 전에, 먼저 설정을 마치고 첫 TestFlight 빌드를 직접 해봐야 합니다. 수동 빌드를 먼저 해보면 몇 가지 장점이 있습니다:

로컬 머신에 배포 인증서를 설정하게 됩니다
아직 App Store 레코드를 만들지 않았다면 이때 생성하게 됩니다
앱 code와 관련된 빌드 프로세스 문제를 파악할 수 있게 됩니다

시작하기 전에 로컬 머신에 배포 인증서가 설치되어 있어야 합니다. 꽤 복잡한 과정이지만, 아래에서 설명하겠습니다.

배포 인증서 설정

Xcode 열기
클릭하세요 Xcode -> Settings... 대신 단축키를 사용할 수도 있습니다 Cmd + ,
다음으로 이동: Accounts
Apple Developer Account에 추가된 Apple 계정을 찾으세요
앱 배포에 사용할 팀을 찾으세요
다음을 클릭하세요: Manage Certificates... 버튼을 클릭하세요
목록에서 배포 인증서가 보이는지 확인하세요
목록에 없다면 새 인증서를 생성해야 합니다

Apple은 배포 인증서를 최대 3개까지만 보유할 수 있습니다. 인증서가 3개를 초과하면 새 인증서를 만들기 위해 하나를 삭제해야 합니다. 이 부분은 튜토리얼에서 다루지 않겠습니다.
1. 다음을 클릭하세요: + 버튼을 누른 다음 Apple Distribution
2. 인증서가 자동으로 생성됩니다. 목록에서 확인할 수 있습니다. 이전 단계를 보고 인증서가 보이는지 확인하세요.

이제 배포 인증서가 설치되었으니 빌드 프로세스를 시작할 수 있습니다.

TestFlight로 수동 빌드

Xcode에서 앱을 엽니다

실행 bunx cap open ios Xcode에서 앱을 엽니다.
을(를) 찾아 클릭합니다 archive 버튼을 클릭하세요

Xcode 툴바에서 을(를) 찾아 클릭합니다 product -> archive 버튼을 클릭하세요.
빌드가 완료될 때까지 기다립니다
다음을 클릭하세요: Distribute App 버튼을 클릭하세요
선택 TestFlight Internal Only 배포 방법으로 선택하고 다음을 클릭하세요 Distribute 버튼을 클릭하세요
앱 레코드 설정

다음 필드를 입력하세요:
1. 이름: 앱 이름 - App Store에 표시됨
2. SKU - 앱 SKU - App Store에서 앱을 식별하는 데 사용됨
3. 기본 언어 - 앱의 기본 언어
그 다음, next 버튼을 클릭하세요
앱 기록 생성에 실패하면 창을 닫고 앱을 다시 아카이브해 보세요.
업로드가 완료될 때까지 기다립니다
모든 과정이 정상적으로 완료되면 다음 화면이 표시됩니다
다음을 클릭하세요: Done 버튼을 클릭하세요

이제 모든 것이 잘 되었다고 생각할 수 있지만, TestFlight에서 앱을 보려면 아직 몇 가지 단계를 더 완료해야 합니다:

TestFlight에 본인 추가
내보내기 규정 준수를 완료하여 빌드를 테스트 가능하게 만듭니다
지원 URL, 개인정보 처리방침 URL, 연령 등급 등 필수 App Store Connect 메타데이터를 입력하세요
실제로 지원하는 기기에 맞는 스크린샷을 준비하세요
프로덕션 제출 전에 앱 리뷰 연락처 정보와 테스트 자격 증명을 추가하세요

첫 번째 항목부터 시작해 보겠습니다:

TestFlight에 본인 추가

다음으로 이동하세요: App Store Connect 페이지
Apple Developer 계정으로 로그인하세요
앱 레코드를 생성할 때 사용한 팀을 선택하세요. 개발자 계정이 하나뿐이라면 이 단계를 건너뛸 수 있습니다.
다음을 클릭하세요: Apps 버튼을 클릭하세요
이전 단계에서 생성한 앱을 찾아 클릭하세요
다음을 클릭하세요: TestFlight 버튼을 클릭하세요
다음을 클릭하세요: Internal Testers plus 버튼을 클릭하세요
새 그룹 생성

그룹 이름은 “internal”로 하겠습니다. 원하는 이름으로 해도 됩니다.
클릭하세요 Invite testers 버튼을 클릭하세요
그룹에 본인 추가하기

목록에서 본인을 찾아 이름 옆의 체크박스를 선택하세요. (목록에 보이지 않으면 페이지를 새로고침해야 할 수도 있습니다) 그 다음, Add 버튼을 클릭하세요.
그룹에 추가되었는지 확인하세요

이제 그룹에서 본인을 확인할 수 있습니다.

축하합니다 🎉 TestFlight에 본인을 추가했습니다. 이제 Capgo Native Build을 설정하기 전에 해야 할 일이 하나만 남았습니다.

컴플라이언스 정보 설정

이제 Apple에 앱이 비표준(예: 사용자 정의 알고리즘) 암호화를 사용하지 않는다고 약속해야 합니다. 앱에서 비표준 암호화를 사용하는 경우, 다음을 읽는 것을 권장합니다. Apple 문서 에서 이 문제를 처리하는 방법을 확인하세요. 두 가지 방법이 있습니다:

앱을 빌드할 때마다 수동으로 설정할 수 있습니다.
plist 파일을 구성하여 이 값을 자동으로 false.

첫 번째 방법부터 시작해 보겠습니다:

이전 섹션의 모든 단계를 따라 App Store Connect에서 TestFlight 섹션을 찾으세요
클릭하세요 Builds -> iOS
준수 정보가 누락된 빌드를 찾아 클릭하세요 Manage
앱을 가장 잘 설명하는 옵션을 선택하세요

제 경우엔 none이지만, 사용자에 따라 다를 수 있습니다. 이후 저장 버튼을 클릭하세요
이제 앱에 다음과 같이 표시되어야 합니다 ready to test

두 번째 항목에 대한 단계는 다음과 같습니다:

다음을 엽니다: Info.plist 파일

다음 키를 추가하세요:

<key>ITSAppUsesNonExemptEncryption</key>
<false/>

파일을 저장하세요

TestFlight 앱 설치 및 초대 수락

이제 거의 TestFlight에서 앱을 테스트할 준비가 되었습니다. 먼저 다음 사항을 수행해야 합니다:

다음을 다운로드한 뒤 TestFlight 앱 iOS/iPadOS 기기의 App Store에서
앱 테스트 초대 수락하기

기기에 TestFlight 앱을 설치하는 방법은 자세히 설명하지 않겠습니다. 앱 설치 방법이 확실하지 않다면 Google에 좋은 가이드가 있습니다.

초대 수락은 Apple에서 보내는 이메일의 초대 링크로 진행할 수 있습니다.

초대 링크가 포함된 Apple 이메일 열기
클릭하세요 View in TestFlight 버튼을 클릭하세요
다음을 클릭하세요: Install 버튼을 클릭하세요
기기에 앱 설치하기

이전에 Xcode를 사용하여 앱을 설치한 경우 다음 화면이 표시될 수 있습니다. 다음을 클릭하세요. install 버튼을 클릭하세요.
앱 설치가 완료될 때까지 기다리세요
다음을 클릭하세요: Open 버튼을 클릭하세요

축하합니다 🎉 TestFlight에서 앱을 테스트하기 위한 초대 수락을 완료했습니다. 이제 Capgo Native Build을(를) 설정하여 앱을 빌드하고 TestFlight에 제출할 수 있습니다.

Capgo Native Build 구성

앱을 빌드하고 TestFlight에 제출하려면 Capgo Native Build에서 몇 가지 항목을 설정해야 합니다. 다음은 Capgo CLI에 전달할 항목 목록입니다:

파라미터	설명
`--platform`	빌드 대상 플랫폼 (`ios`)
`--apple-team-id`	Apple Developer 팀 ID ( Apple Developer Portal에서 확인))
`--apple-key`	App Store Connect API 키 파일 경로 (`.p8` 파일)
`--apple-key-id`	App Store Connect API 키의 Key ID
`--apple-issuer-id`	App Store Connect Issuer ID
`--certificate`	배포 인증서 경로 (`.p12` 파일)
`--ios-provisioning-profile`	Provisioning profile 매핑 (`bundleId=path` 또는 단일 프로필의 경우 경로만 입력)

예시 명령어:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile '/path/to/profile.mobileprovision'

팀 ID

Team ID부터 시작해 보겠습니다. 찾는 방법은 꽤 간단합니다.

다음으로 이동: Apple Developer Account 아래로 스크롤하여
다음 Team ID

Apple key, Apple key ID 및 Apple issuer ID

이제 Apple 키로 넘어가 보겠습니다.

다음으로 이동: App Store Connect 사용자 및 접근 권한 페이지

제 경우 링크가 가끔 작동하지 않더라고요. 링크가 작동하지 않으면 페이지를 새로고침하세요.
드롭다운에서 올바른 팀을 선택하세요
1. 우측 상단에 있는 이름을 클릭하세요
2. 사용할 팀을 클릭하세요
다음을 클릭하세요: Integrations 버튼을 클릭하세요
다음 issuer

이 반드시 저장해야 합니다 - 나중에 필요합니다

다음을 클릭하세요: copy 이슈어 복사 버튼
더하기(+) 버튼을 클릭하세요
키 이름을 설정하고 접근 권한을 App manager 를 클릭하세요 Generate 버튼을 클릭하세요
키 ID 저장

이 반드시 저장해야 합니다 - 나중에 필요합니다
키 다운로드

이 반드시 저장해야 합니다 - 나중에 필요합니다

키를 절대 누구와도 공유하지 마세요 - CAPGO CLI 에서만 사용하세요.

축하합니다 🎉 Apple key, Apple key ID, Apple issuer ID 생성을 완료했습니다.

인증서

이제 인증서를 내보낼 준비가 되었습니다. 기억하시겠지만, 이 가이드의 첫 단계 중 하나가 배포용 인증서(distribution certificate)를 설정하는 것이었습니다.

하지만 Apple은 그 놀라운 지혜로 인증서를 내보내는 방식이 생성하는 방식과 꽤 다르다고 정해버렸습니다 🙃 이제 설정을 시작해 보겠습니다:

Keychain Access 열기
1. 클릭 Command + Space 검색창을 열려면
2. 검색: Keychain Access
3. 다음을 클릭하세요: Keychain Access 앱
다음을 선택하세요: login 카테고리에서 My Certificates 버튼을 클릭하세요
목록에서 인증서를 찾습니다

인증서 이름은 다음과 같아야 합니다 Apple Distribution: [Your Name/Company] (your team ID)
인증서를 우클릭하여 선택 Export
인증서를 로 저장 .p12 파일

이 반드시 저장해야 합니다 - 나중에 필요합니다
1. 인증서 파일 이름을 잘 지어 주세요
2. 파일 형식이 로 설정되어 있는지 확인 Personal Information Exchange (.p12)
3. 다음을 클릭하세요: Save 버튼을 클릭하세요
비밀번호를 입력하라는 메시지가 뜨면 다음 중 하나를 선택할 수 있습니다:
- 비밀번호 건너뛰기(간편한 설정을 위해 권장): 클릭 OK 비밀번호 입력 없이
- 비밀번호 설정: 인증서를 비밀번호로 보호하려면 여기서 설정할 수 있습니다. 비밀번호로 보호된 .p12 파일은 Capgo CLI에서 완전히 지원됩니다. 구성 명령어를 실행할 때 --p12-password 해당 옵션으로 비밀번호를 제공하기만 하면 됩니다.
“login keychain password”를 묻는 메시지가 뜨면 Mac에 로그인할 때 사용하는 비밀번호를 입력하세요.

Mac에 로그인할 때 사용하는 비밀번호를 입력한 후, 다음을 클릭하세요. Allow 버튼을 클릭하세요.

축하합니다 🎉 인증서 내보내기에 성공했습니다.

프로비저닝 프로파일

이제 provisioning profile을 내보낼 준비가 되었습니다. 약속할게요, 이게 Apple에서 받아야 할 마지막 항목입니다.

다음으로 이동: Apple Developer 프로필
드롭다운에서 올바른 팀을 선택하세요
1. 우측 상단에 있는 이름을 클릭하세요
2. 사용할 팀을 클릭하세요
올바른 페이지에 있는지 확인하세요 다음과 같아야 합니다. 그렇지 않다면 클릭하세요 profiles 사이드바에서
다음을 클릭하세요: + 버튼을 클릭하세요
프로필 유형 선택 선택 App Store Connect 를 클릭하세요 Continue 버튼을 클릭하세요
빌드할 앱을 선택하세요

드롭다운에서 앱을 찾아 클릭하세요 Continue 버튼을 클릭하세요
올바른 배포 인증서를 선택하세요

이전 단계에서 내보낸 인증서를 선택한 후 클릭하세요 Continue 버튼을 클릭하세요

어떤 인증서를 선택해야 할지 확실하지 않다면 Keychain Access로 돌아가 내보낸 인증서를 찾으세요. 그런 다음 만료 날짜를 확인하세요.
프로파일 이름 지정

프로파일에 이름을 입력한 후 클릭하세요 Generate 버튼을 클릭하세요

프로파일 이름은 Capgo CLI에서 자동으로 추출되므로 따로 기억할 필요가 없습니다.
프로필 다운로드

다음을 클릭하세요: Download 프로필 다운로드 버튼

이 파일은 반드시 저장해야 합니다 - 나중에 필요합니다

축하합니다 🎉 이제 Capgo Native Build 설정을 위한 모든 준비가 완료되었습니다.

설정 명령 실행

완료했습니다! 이제 Capgo Native Build 설정에 필요한 모든 것이 준비되었습니다.

실행해야 하는 명령은 다음과 같습니다:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --ios-provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision

모든 과정이 성공하면 다음과 같은 결과가 출력됩니다:

Capgo CLI 자격 증명 저장 출력

CI/CD 설정 (GitHub Actions)

이미 완료했다면 팀 ID, Apple key, Apple key ID 및 Apple issuer ID, 인증서, 그리고 프로비저닝 프로파일, CI/CD에 필요한 모든 것이 이미 준비되어 있습니다. 이 섹션은 해당 값을 GitHub Actions 시크릿 및 환경 변수로 전달하는 방법만 다룹니다.

1) 자격 증명 파일을 단일 줄 base64로 변환

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

2) 저장소 시크릿 생성

다음에서 GitHub > Repository > Settings > Secrets and variables > Actions, 추가:

Secret 이름	값
`CAPGO_TOKEN`	Capgo API 토큰
`APP_STORE_CONNECT_TEAM_ID`	Team ID 출처 팀 ID
`APPLE_KEY_ID`	Key ID 출처 Apple key, Apple key ID 및 Apple issuer ID
`APPLE_ISSUER_ID`	Issuer ID 출처 Apple key, Apple key ID 및 Apple issuer ID
`BUILD_CERTIFICATE_BASE64`	내용 `certificate_base64.txt`
`CAPGO_IOS_PROVISIONING_MAP`	CLI에서 생성됨 — 다음에서 복사: `.capgo-credentials` 파일
`APPLE_KEY_CONTENT`	내용 `apple_key_base64.txt`
`P12_PASSWORD` (선택 사항)	여러분의 `.p12` 내보내기 시 설정된 비밀번호

3) GitHub Actions 워크플로에서 환경 변수 사용

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

빌드 실행하기

이제 첫 번째 빌드를 실행할 준비가 되었습니다.

다음 명령을 실행하여 앱을 빌드하세요:

bunx @capgo/cli@latest build request --platform ios

축하합니다 🎉 이 시점에서 앱을 성공적으로 빌드했으며 App Store에 제출할 준비가 되었습니다.

App Store 심사 제출

일반적인 App Store 빌드 경로는 빌드를 App Store Connect/TestFlight에 업로드합니다. CI 릴리스에서 처리된 TestFlight 빌드를 App Store 버전에 첨부하고 App Review에 제출하려면 --submit-to-store-review 릴리스 빌드와 함께:

npx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --build-mode release \
  --ios-distribution app_store \
  --submit-to-store-review \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales" \
  --no-ios-automatic-release

App Store Connect API 키 자격 증명(APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, 그리고 APP_STORE_CONNECT_TEAM_ID)이 필요합니다. 앱 전용 비밀번호 업로드 및 ad_hoc 배포는 빌드를 심사에 제출할 수 없습니다. --store-release-name 은(는) App Store 버전입니다. 생략하면 Capgo이(가) MARKETING_VERSION Xcode 프로젝트에서 읽습니다. --store-release-notes 은(는) App Store '새로운 기능' 텍스트의 대체값이며, 각 --store-release-notes-locale "locale=notes" 항목은 스토어 로케일별로 이를 재정의할 수 있습니다. --ios-automatic-release Apple 승인 후 자동으로 릴리스하려면 사용하세요, 또는 --no-ios-automatic-release 수동 릴리스를 기다리기 위해 --ios-testflight-groups 외부 베타 배포에는 여전히 사용 가능하지만, App Store 심사 제출에는 필요하지 않습니다.

Ad-Hoc 배포 모드

기본적으로 Capgo는 App Store 배포(TestFlight + App Store)용 iOS 앱을 빌드합니다. 내부 테스트나 CI 아티팩트 수집을 위해 ad-hoc 빌드가 필요한 경우 --ios-distribution flag.

Ad-hoc 모드 사용 시점

TestFlight 없이 등록된 기기에 IPA를 직접 배포하려는 경우
App Store Connect API 키가 없거나 사용하지 않으려는 경우
App Store 제출 없이 빌드 산출물을 다음을 통해 수집하려는 경우 --output-upload App Store에 제출하지 않고

요구 사항

Ad-hoc 빌드는 App Store 빌드보다 요건이 적습니다:

자격 증명	필수 여부
배포 인증서 (`.p12`)	지원
Ad-hoc 프로비저닝 프로필 (`.mobileprovision`)	지원
팀 ID (`--apple-team-id`)	지원
App Store Connect API 키 (`.p8`)	아니요
Apple 키 ID / 발급자 ID	아니요

ad-hoc 프로비저닝 프로파일 생성

다음과 동일한 단계를 따르세요: 프로비저닝 프로파일, 하지만 5단계에서는 선택하세요 Ad Hoc 를 전달하고 App Store:

다음으로 이동: Apple Developer 프로필
Members 섹션에서 + 버튼을 클릭하세요
선택 Ad Hoc 그리고 Continue를 클릭하세요
앱과 배포 인증서를 선택하세요
등록할 기기를 선택하세요
프로필 이름 지정 및 다운로드

Ad-hoc 자격 증명 저장

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --ios-provisioning-profile './adhoc_profile.mobileprovision'

아니요 --apple-key, --apple-key-id, 또는 --apple-issuer-id 필요합니다.

Ad-hoc 빌드 실행

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

IPA를 빌드 아티팩트로 수집하려면 다음을 추가하세요: --output-upload:

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

ad-hoc 빌드를 활용한 CI/CD

GitHub Actions의 경우, App Store 빌드보다 적은 secrets가 필요합니다:

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_ADHOC }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

확장 기능이 있는 앱 (멀티 타겟 서명)

앱에 extension(share extension, widget, notification service extension 등)이 포함된 경우, 각 extension target에 고유한 provisioning profile이 필요합니다. Capgo는 반복 가능한 --ios-provisioning-profile flag.

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile "com.example.app=./app_profile.mobileprovision" \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

각 --ios-provisioning-profile flag은 번들 ID를 해당 프로비저닝 프로필 파일로 매핑합니다. CLI:

각 mobileprovision 파일을 읽습니다.
내장된 plist에서 프로필 이름을 자동으로 추출합니다.
파일을 Base64로 인코딩합니다.
모든 정보를 하나의 CAPGO_IOS_PROVISIONING_MAP credential로 저장합니다.

Single Profile에서 마이그레이션

이전에 BUILD_PROVISION_PROFILE_BASE64 (single profile)을 사용했다면, 다음을 실행하세요:

bunx @capgo/cli@latest build credentials migrate --platform ios

이 명령은 기존 단일 프로필 인증 정보를 새로운 CAPGO_IOS_PROVISIONING_MAP 형식으로 변환하고 레거시 키를 삭제합니다 (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

마이그레이션 후, 다음 명령어로 확장 프로필을 추가하세요 update (추가 병합):

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

문제 해결

Provisioning profile에 XYZ capability가 포함되어 있지 않습니다.

가끔 다음과 같은 에러가 표시될 수 있습니다:

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

이는 provisioning profile이 생성된 후 새로운 capability를 활성화했기 때문입니다. 기존 provisioning profile에는 아직 새로운 capability가 포함되어 있지 않습니다.

이를 해결하려면 provisioning profile을 다시 생성해야 합니다.

열기 Apple Developer Portal
드롭다운에서 올바른 팀을 선택하세요
다음을 클릭하세요: Profiles 버튼을 클릭하세요
재생성할 프로비저닝 프로필 찾기
다음을 클릭하세요: Edit 버튼을 클릭하세요
다음을 클릭하세요: Save 버튼을 클릭하세요
다음을 클릭하세요: Download 버튼을 클릭하세요
Capgo Native Build 설정 명령어를 다시 실행하세요 새로 다운로드한 프로필을 사용해.

이렇게 하면 문제가 해결됩니다.

기타 문제

Capgo Native Build 사용, 자격 증명 설정 또는 앱 빌드 중 어떤 이유로든 문제가 발생한다면, 주저하지 말고 다음을 통해 문의해 주세요: 고객 지원.

iOS Builds에서 계속하기

사용 중이라면 iOS 빌드 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.