iOS 빌드

Build and submit iOS apps to TestFlight and the App Store using Capgo’s dedicated Mac infrastructure.

iOS 앱을 TestFlight 및 App Store에 제출하는 데 사용할 수 있는 __CAPGO_KEEP_0__의 전용 Mac 인프라를 사용하여 앱을 빌드하고 제출하세요.

• You will learn how to upload your app via Capgo Native build
• Capgo 네이티브 빌드에서 앱을 업로드하는 방법

__CAPGO_KEEP_0__ 네이티브 빌드에 대한 인증서를 구성하는 방법

• Capgo 계정 (무료试用도 충분합니다)
• Capgo에 앱이 이미 등록되어 있습니다 (run bunx @capgo/cli@latest app add 만약 그렇지 않다면)
• 맥 컴퓨터와 Xcode가 설치된 상태 (linux/windows 머신에서 빌드를 설정할 수 있지만 아직 문서화되지 않았습니다)
• 유효한 Apple Developer 계정 ($99/년) (Apple Developer 계정에 관리자 또는 소유권이 있는 권한이 있어야 함)
• 앱이 Xcode를 통해 성공적으로 빌드될 수 있어야 함
• Capacitor 앱
• 앱에 아이콘을 구성했습니다. 아이콘을 설정하지 않은 앱은 앱 스토어에 업로드할 수 없습니다

주의

이 튜토리얼에서 사용할 앱은 다음과 같습니다: https://github.com/Cap-go/capgo-native-build-tutorial-app

애플의 포털에서 시작하기 전에

애플 계정과 팀이 준비된 상태인지 확인하기 전에 인증서를 설정하거나 첫 번째 테스트 플라이트 업로드를 트리거하지 마십시오

• Apple 계정에 등록된 두 단계 인증을 활성화하세요.
• 적절한 회원 유형을 선택하세요:
  • 개인/개인사업자: 판매자 이름은 App Store에서 판매자 이름으로 설정됩니다.
  • 기업: 법적 엔터티, D-U-N-S 번호, 공공 회사 웹사이트, 회사 도메인에 속한 이메일, Apple의 계약에 결합할 수 있는 권한이 있는 사람을 필요로 합니다.
• Apple Developer와 App Store Connect에 접근할 수 있는 계정을 사용하세요. 인증서, 앱 레코드, API 키, 테스트 플라이트를 위해.
• 최종 번들 ID를 일찍 설정하세요. 변경하면 일반적으로 App Store 설정을 다시 시작해야 합니다.
• App Review 전에 App Store Connect 항목을 계획하세요: 지원 URL, 개인 정보 정책 URL, 연령 등급, 스크린샷, 수출 준수, App Review 연락처 정보.

참고

유용한 공식 참고 자료:

• Apple 개발자 프로그램의 회원이 되세요
• 앱과 게임을 제출하세요
• 앱 스토어 연결에서 플랫폼 버전 정보

주의

Apple은 매월 SDK 최소 요구 사항을 업데이트합니다. 2026년 4월 28일 기준으로 2026년 4월 28일iPhone과 iPad 앱을 앱 스토어 연결에 업로드하려면 앱 스토어 연결에서 앱을 빌드해야 합니다. iOS & iPadOS 26 SDK or later.

권장: 자동 온보딩

Capgo의 온보딩은 iOS signing 인증서 및 배포 프로파일을 자동으로 생성 및 구성합니다. 이 방법이 권장되는 이유는 다음과 같습니다:

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

Capgo의 온보딩을 자동으로 처리할 필요가 없습니다. Capgo의 온보딩은 iOS signing 인증서 및 배포 프로파일을 자동으로 생성 및 구성합니다. 이 방법이 권장되는 이유는 다음과 같습니다:

수동 온보딩

Capgo의 온보딩을 자동으로 처리할 필요가 없습니다. Capgo의 온보딩은 iOS signing 인증서 및 배포 프로파일을 자동으로 생성 및 구성합니다. 이 방법이 권장되는 이유는 다음과 같습니다:

• 첫 번째 수동 빌드
• 첫 번째 수동 빌드 섹션 제목
• You will be able to figure out any issues with the build process linked to your app code

시작하기 전에, 앱 개발자 계정에 등록된 인증서를 로컬 머신에 설치해야 합니다. 이것은 매우 복잡한 과정입니다. 하지만 아래에 설명하겠습니다.

인증서 설정

1. Xcode를 열어주세요

2. 클릭하세요 Xcode -> Settings... 대안으로, 단축키를 사용할 수 있습니다 Cmd + ,

   

3. 로 가세요 Accounts

4. 애플 개발자 계정에 등록된 애플 계정을 찾으세요

5. 앱을 배포할 팀을 찾으세요.

6. 버튼을 클릭하세요. Manage Certificates... 버튼

7. 인증서 목록에서 배포 인증서가 보이도록 확인하세요.

8. 인증서가 보이지 않으면 새로운 인증서를 생성해야 합니다.

   주의

   애플은 배포 인증서의 최대 수를 3개로 제한합니다. 3개 이상의 인증서가 있는 경우 하나를 삭제해야 새로운 인증서를 생성할 수 있습니다. 이 튜토리얼에서는 그 과정을 다루지 않습니다.

   1. 버튼을 클릭하세요. + 버튼을 클릭하고 Apple Distribution
   2. 인증서가 자동으로 생성됩니다. 목록에서 확인할 수 있습니다. 이전 단계를 확인하여 인증서가 생성되었는지 확인하세요.

분산 인증서가 설치되면 빌드 프로세스를 시작할 수 있습니다.

TestFlight로 수동 빌드

1. Xcode에서 앱을 열기

   실행 bunx cap open ios Xcode에서 앱을 열기.

2. 버튼 archive Xcode 도구栏에서

   버튼 product -> archive 버튼.

   

3. 빌드를 완료하기까지 기다려 주세요

4. 버튼을 클릭하세요. Distribute App 버튼

   

5. 배포 방법으로 TestFlight Internal Only 버튼을 클릭하세요. Distribute Xcode TestFlight 내부 배포 방법

   

6. 다음 필드를 입력하세요:

   __CAPGO_KEEP_0__

   1. 애플리케이션 이름: 애플리케이션 이름 - 앱 스토어에서 표시됩니다.
   2. SKU - 앱의 SKU - 앱 스토어에서 앱을 식별하는 데 사용됩니다.
   3. 기본 언어 - 앱의 기본 언어

   그런 다음 next 버튼

   

7. 앱 기록 생성이 실패한 경우 창을 닫고 앱을 다시 압축해 보세요.

8. 업로드를 기다려 주세요.

9. 모든 것이 잘 되었으면 다음 화면을 볼 수 있어야 합니다.

10. 버튼 Done button

이제 모든 것이 잘 될 것 같고 테스트 플라이트에서 앱을 볼 수 있을 것 같지만, 여전히 몇 가지 더 해야 할 일들이 있습니다:

1. 테스트 플라이트에 자신을 추가하세요
2. 수출 규정 완료하여 빌드가 테스트 가능하도록 하세요
3. 지원 URL, 개인 정보 보호 정책 URL, 연령 등 App Store Connect에서 필수 입력해야 하는 메타데이터를 입력하세요
4. 지원하는 실제 기기에 맞는 스크린샷을 준비하세요
5. 제품 제출 전에 App Review 연락처 및 테스트 자격증명을 추가하세요

첫 번째 것을 시작해 보겠습니다:

테스트 플라이트에 자신을 추가하는 것입니다

1. App Store Connect 페이지 페이지

2. 애플 개발자 계정으로 로그인하세요

3. 앱 레코드를 만들 때 사용한 팀을 선택하세요. 단일 개발자 계정만 있는 경우 이 단계를 건너뛸 수 있습니다.

4. 버튼 Apps 애플리케이션 스토어 연결 앱 버튼

5. 애플리케이션 스토어 연결 앱 선택

6. 애플리케이션 스토어 연결 테스트 플라이트 버튼 TestFlight __CAPGO_KEEP_0__

7. 애플 스토어 연결 내부 테스터 플러스 버튼을 클릭하세요. Internal Testers plus 버튼

8. 새 그룹 만들기

   내 그룹 이름은 '내부'라고 지칭합니다. 그룹 이름은 원하는 대로 지어질 수 있습니다.

   

9. 버튼 Invite testers App Store Connect - 테스터 초대 버튼

10. 리스트에서 자신을 찾고 이름 옆에 체크박스를 선택하세요. (자신을 찾을 수 없다면 페이지를 새로 고침해 보세요) 그 다음에

    버튼을 클릭하세요. Add 버튼

    

11. 그룹에 추가된 것을 확인하세요

    현재 그룹에 자신이 보이시나요?

    

축하합니다 🎉 TestFlight에 자신을 추가했습니다. 이제 Capgo Native Build을 구성하기 전에 마지막 단계가 하나 남았습니다.

규정 준수 정보 설정

애플이 앱이 비표준 암호화 알고리즘(커스텀 알고리즘)을 사용하지 않는다는 것을 약속해야 합니다. 앱이 비표준 암호화를 사용한다면, 나는 애플 문서 비표준 암호화 사용을 처리하는 방법에 대해 읽어보세요. 다음 두 가지 방법이 있습니다:

1. 매 빌드마다 이 작업을 수동으로 수행할 수 있습니다.
2. plist 파일을 자동으로 설정할 수 있습니다. false.

Let's start with the first one:

1. 이전 섹션에서 설명한 단계를 모두 따르세요. 테스트 플라이트 섹션을 앱 스토어 연결에서 찾으세요.

2. 클릭하세요. Builds -> iOS

3. 미흡한 준수 정보가 있는 빌드를 찾고 클릭하세요. Manage

4. 앱에 가장 적합한 옵션을 선택하세요.

   저의 경우는 none하지만 당신의 경우에는 다를 수 있습니다. 그 후에 저장을 클릭하세요.

   

5. 앱이 이제 ready to test

   

두 번째 경우에 대해, 다음 단계를 참조하세요:

1. 열기 Info.plist 파일

2. 다음 키를 추가하세요:

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

3. 파일 저장

주의

여기 Apple에서 암호화 수출 규제 준수에 대한 정보를 제공하는 공식 문서입니다.

테스트 플라이트 앱 설치 및 초대 수락

이제, 당신은 가장 가까운 테스트 플라이트에서 앱을 테스트할 준비가 거의 다 됐습니다. 앱을 테스트하기 전에 다음 몇 가지 작업을 수행해야 합니다:

1. 테스트 플라이트 앱을 다운로드하십시오. App Store에서 iOS/iPadOS 기기에서
2. 테스트 플라이트 앱을 다운로드하십시오.

테스트 플라이트 앱을 설치하는 방법에 대한 세부 정보는 생략하겠습니다. 앱을 설치하는 방법에 대해 불확실한 경우, Google은 설치 방법에 대한 훌륭한 안내서를 제공하고 있습니다.

Apple에서 앱 테스트 초대장을 수락하는 방법에 대해 설명하겠습니다.

1. Apple에서 초대장 수락을 위한 링크가 포함된 이메일을 열으십시오.

2. 초대장 수락을 위한 링크가 포함된 이메일을 열으십시오. View in TestFlight 초대장 수락을 위한 링크가 포함된 이메일을 열으십시오.

3. Xcode를 사용하여 앱을 이전에 설치한 경우 다음 화면이 나타날 수 있습니다. Install 버튼

4. 앱을 장치에 설치하세요

   Xcode를 사용하여 앱을 이전에 설치한 경우 다음 화면이 나타날 수 있습니다. install 버튼

5. 앱을 설치하기만 기다리세요

6. 버튼 Open 버튼을 클릭하고 클릭하세요

축하합니다 🎉 테스트 플라이트에서 앱을 테스트하기 위한 초대장을 수락했습니다. 이제 Capgo 네이티브 빌드를 구성하여 앱을 테스트 플라이트에 제출할 수 있습니다.

Capgo Native Build 설정

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

매개 변수	설명
--platform	빌드할 플랫폼 (ios)
--apple-team-id	__CAPGO_KEEP_0__ Key 파일의 경로 ( __CAPGO_KEEP_0__ Key의 Key ID)
--apple-key	API Key의 발급자 ID.p8 Apple Developer Portal
--apple-key-id	The Key ID of your App Store Connect API Key
--apple-issuer-id	Apple Developer Portal
--certificate	iOS 배포 인증서 경로 (.p12 파일)
--ios-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

팀 ID를 찾는 건 매우 쉬워요. 시작하기 전에 팀 ID를 찾는 건 정말 쉽습니다.

1. Apple Developer Account로 이동 Apple Developer 계정으로 이동 스크롤을 내려보세요

2. 개발자 계정에서 Team ID

   

Apple 키, Apple 키 ID 및 Apple 발급자 ID

Apple 키로 넘어가겠습니다.

macOS: Capgo이 이 키를 생성해 주세요

macOS에서 capgo build init 이 App Store Connect API 키를 생성해 주세요. "No — create one for me"를 선택하세요. ‘No — create one for me’를 선택하세요. ‘No — create one for me’를 선택하세요.

1. 애플리케이션 App Store Connect 사용자 및 액세스 페이지

   주의

   링크가 작동하지 않는 경우에는 나에게도 같은 경우가 있습니다. 페이지를 다시 로드해 보세요.

2. 정확한 팀을 드롭다운 메뉴에서 선택하세요

   1. 상단 우측에서 이름을 클릭하세요
   2. 사용하고 싶은 팀을 클릭하세요

3. 클릭하세요 Integrations 버튼

4. iOS 빌더 issuer

   주의

   이 이것은 나중에 필요합니다. 이것을 클릭하여 복사하세요.

   App Store Connect에서 발급자 복사 copy App Store Connect에서 플러스 버튼 클릭

5. 키 이름을 설정하고 접근 권한을 설정하세요.

6. __CAPGO_KEEP_1__ App manager 그리고 버튼을 클릭하세요. Generate 버튼

7. 키 ID를 저장하세요.

   주의

   이 이것은 나중에 필요하므로 저장하세요. App Store Connect에서 키 ID를 복사하세요.

   

8. 주의

   주의

   이것은 이것은 저장해야 합니다 이것을 나중에 다시 사용할 것입니다

   위험

   이 키를 누구에게도 공유하지 마세요 - CAPGO CLI에서만 사용하세요

   

   

축하합니다 🎉 애플 키, 애플 키 ID 및 애플 발급자 ID를 생성했습니다.

인증서

이제 인증서를 내보낼 준비가 되었습니다. 이 가이드의 첫 번째 단계 중 하나로 인증서 배포 인증서를 설정하는 것을 기억하나요?

그러나 애플은 무한 지혜로, 인증서를 내보내는 방법은 인증서를 만들 때와는 다릅니다. 🙃 인증서를 설정하는 방법에 대해 알아보겠습니다:

1. 키 체인 액세스 열기

   1. 클릭 Command + Space 검색 바를 열기
   2. 검색 Keychain Access
   3. 클릭 Keychain Access 앱

2. 카테고리 선택하고 버튼 클릭 login 버튼 My Certificates 앱

3. 리스트에서 인증서를 찾으세요

   인증서 이름은 Apple Distribution: [Your Name/Company] (your team ID)

4. 인증서 오른쪽 클릭하고 선택하세요 Export

5. 인증서를 파일로 저장하세요 .p12 파일

   주의

   이 저장해야 합니다 - 나중에 필요할 것입니다.

   1. 인증서 파일의 이름을 좋은 이름으로 선택하십시오.
   2. 인증서 파일의 형식이 설정되어 있는지 확인하십시오. Personal Information Exchange (.p12)
   3. 버튼을 클릭하십시오. Save 버튼

   

6. 비밀번호를 묻는 경우, 다음 중 하나를 선택하십시오:

   • 비밀번호를 입력하지 않고 클릭하십시오. OK 비밀번호를 설정하십시오. 비밀번호를 설정하면 인증서를 보호할 수 있습니다. 비밀번호가 설정된 파일은 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__에서 완전히 지원됩니다. 비밀번호를 입력할 때 옵션을 사용하십시오.
   • 설정 명령어를 실행할 때 비밀번호를 제공하십시오. .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password option

   

7. 로그인 키체인 비밀번호를 묻는 경우, Mac에 로그인하는 비밀번호를 입력하세요.

   Mac에 로그인하는 비밀번호를 입력하세요. 그런 다음, Allow 버튼을 클릭하세요.

   

축하합니다! 🎉 인증서를 성공적으로 내보냈습니다.

인증서 배포 프로파일

인증서 배포 프로파일 섹션

1. 이제 인증서 배포 프로파일을 내보내실 준비가 되었습니다. 정말로, Apple에서 다시 가져올 필요가 없습니다. Apple Developer Profiles로 이동하세요.

2. 정확한 팀을 드롭다운 메뉴에서 선택하세요.

   1. 오른쪽 위 코너의 이름을 클릭하세요.
   2. 사용할 팀을 클릭하세요.

3. 올바른 페이지인지 확인하세요. 이런 모습이면 좋습니다. 그렇지 않다면 profiles 사이드바에 있습니다.

   

4. 클릭하세요. + 버튼

5. 프로필 유형을 선택하세요. 선택 App Store Connect 버튼 Continue 프로필 유형을 선택하세요. 선택

   

6. 빌드할 앱을 선택하세요

   다운로드 드롭다운에서 앱을 찾고 버튼을 클릭하세요 Continue 버튼

   

7. 정확한 배포 인증서를 선택하세요

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

   

   인증서를 선택할 수 없다면 Keychain Access로 돌아가서 내보낸 인증서를 찾고 만료일을 확인하세요

   

8. 프로파일 이름을 지정하세요

   이름을 지어주고 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 버튼을 클릭하세요. Generate 버튼

   팁

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

   

9. 프로필 다운로드

   다운로드 버튼을 클릭하여 프로필을 다운로드하세요 Download 주의

   이 파일

   __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 저장해야 합니다 이것을 나중에 필요로 하실 것입니다

   

축하합니다 🎉 Capgo 네이티브 빌드를 구성하기 위해 필요한 모든 것을 이제 가지고 있습니다.

주의

생성한 인증서를 저장소에 커밋하지 마세요. 그것들을 안전하게 지키세요! 🔒

설정 명령어를 실행하는 방법

축하합니다! Capgo 네이티브 빌드를 구성하기 위해 필요한 모든 것을 이제 가지고 있습니다.

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

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

위치 홀더 값 대체

위치 홀더 값 위에 실제 인증서를 수집한 이전 단계에서 수집한 실제 인증서를 대체하십시오:

• --apple-team-id: Apple 팀 ID
• --apple-key: 다운로드 한 .p8 키 파일
• --apple-key-id: Apple 키 ID
• --apple-issuer-id: Apple 발급자 ID
• --certificate: 내보낸 .p12 인증서
• --ios-provisioning-profile: 내보낸 .mobileprovision 파일 (프로파일이 하나일 경우 자동으로 추론되는 번들 ID)

모든 것이 잘 되었으면 다음 출력을 볼 수 있을 것입니다.

애플 인증이 실패했습니다. 시계를 동기화하세요.

앱 스토어 연결 API 키가 올바르게 보이지만 인증이 여전히 실패한다면 컴퓨터 시계를 동기화하고 다시 시도하세요. Capgo은 로컬 시스템 시간과 Apple의 JWT를 서명하며, Apple은 20분 이상 유효하지 않은 토큰을 거부합니다. 시계가 몇 초만 틀려도 이 단계를 실패할 수 있습니다.

시계 동기화 방법을 참조하세요. 시계 동기화 방법을 참조하세요. CI/CD 설정 (__CAPGO_KEEP_0__ Actions)

CI/CD 설정 (GitHub Actions)

CI/CD 설정 방법을 참조하세요. 팀 ID, 애플 키, 애플 키 ID 및 애플 이슈어 ID, 인증서, 그리고 프로비전 프로파일, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

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

팁

GitHub secret은 한 줄의 값이어야 합니다. tr -d '\n' base64 출력에서 줄 바꿈을 제거합니다.

2) 저장소 비밀번호를 생성하세요

그리고 GitHub > Repository > Settings > Secrets and variables > Actions에 추가하세요:

비밀 이름	값
CAPGO_TOKEN	Capgo API 토큰
APP_STORE_CONNECT_TEAM_ID	팀 ID 팀 ID
APPLE_KEY_ID	키 ID 애플 키, 애플 키 ID 및 애플 발급자 ID
APPLE_ISSUER_ID	발급자 ID 애플 키, 애플 키 ID 및 애플 발급자 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) __CAPGO_KEEP_0__ Actions 워크플로우에서 환경 변수 사용

제목 ‘3) GitHub Actions 워크플로우에서 환경 변수 사용’

/github/workflows/ios-build.yml

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 }}

팁

이 설정을 사용하면 CI는 환경 변수만을 통해 자격 증명을 전송합니다. 서명 파일을 커밋하거나 워크플로 아티팩트로 업로드할 필요가 없습니다.

빌드 실행

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

아래 명령어를 실행하여 앱을 빌드하세요:

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

축하합니다 🎉 이제 앱 빌드가 성공적으로 완료되었으며 앱 스토어에 제출할 준비가 되었습니다.

애플 스토어 리뷰 제출

일반적인 애플 스토어 빌드 경로에서는 빌드를 애플 스토어 연결/테스트 플라이트에 업로드합니다. CI 릴리즈가 또한 처리된 테스트 플라이트 빌드를 애플 스토어 버전과 함께 첨부하고 리뷰 제출을 위해 제출할 경우, App Store Connect __CAPGO_KEEP_0__ 키 자격증서 ( --submit-to-store-review with a release build:

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

이것은 애플 스토어 연결 API 키 자격증서 (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT및 APP_STORE_CONNECT_TEAM_ID) 앱별 암호 업로드 및 배포는 리뷰 제출을 위해 빌드를 제출할 수 없습니다. ad_hoc 애플 스토어 버전입니다. 생략 시 __CAPGO_KEEP_0__은 Xcode 프로젝트에서 읽습니다. --store-release-name App Store 버전입니다. 생략 시 Capgo은 Xcode 프로젝트에서 읽습니다. MARKETING_VERSION App Store 버전입니다. 생략 시 __CAPGO_KEEP_0__은 Xcode 프로젝트에서 읽습니다. --store-release-notes App Store의 기본 What's New 텍스트이며, 각 --store-release-notes-locale "locale=notes" 스토어의 지역화에 따라 이를 오버라이드할 수 있습니다. 사용 --ios-automatic-release 애플 승인 후 자동으로 릴리즈하거나 --no-ios-automatic-release 수동 릴리즈를 기다릴 수 있습니다. --ios-testflight-groups App Store 리뷰 제출에 필요한 것은 아니지만, 외부 베타 배포를 위해 여전히 사용할 수 있습니다.

Ad-Hoc 배포 모드

기본적으로 Capgo은 iOS 앱을 App Store 배포용으로 빌드합니다 (TestFlight + App Store). 내부 테스트 또는 CI 아티팩트 수집을 위해 ad-hoc 빌드를 필요로 한다면, --ios-distribution flag를 사용할 수 있습니다.

주의

ad-hoc 배포는 아니요 the same as Enterprise (In-House) distribution. Enterprise distribution requires a separate Apple Developer Enterprise account and uses different provisioning profiles. Capgo currently supports app_store 현재 __CAPGO_KEEP_0__는 ad_hoc 및

모드만 지원합니다.

• 등록된 장치에 IPA를 직접 배포하고 싶습니다(테스트 플라이트를 사용하지 않습니다)
• App Store Connect API 키를 사용하지 않거나 사용할 수 없을 때
• 빌드 아티팩트를 __CAPGO_KEEP_0__를 통해 수집하고 싶습니다 --output-upload 앱 스토어에 제출하지 않고 배포하고 싶습니다

요구 사항

iOS 빌더에서 App Store 빌드보다 fewer requirements

than App Store builds:	인증
필요한가요?.p12)	Distribution certificate (
Yes.mobileprovision)	Ad-hoc provisioning profile (
Yes--apple-team-id)	Team ID (
App Store Connect API key (.p8)	아니요
애플 키 ID / 발급자 ID	아니요

주의

모드에서 ad_hoc 모드, 그리고 --apple-key, --apple-key-id지원되지 않으며 무시됩니다. 이러한 이유로 위의 App Store Connect 두 줄은 ad-hoc __CAPGO_KEEP_0__ 플래그를 표시하지 않습니다; 이러한 옵션은 --apple-issuer-id are not supported and are ignored. This is why the two App Store Connect rows above do not show ad-hoc CLI flags; these options apply to app_store 주의

translations

Without an App Store Connect API key, build number auto-increment uses a timestamp-based fallback. To suppress the warning, pass --skip-build-number-bump.

어드혹 프로비전 프로파일 생성

같은 단계를 따르세요 프로비전 프로파일역할: Capgo Builder / 네이티브 클라우드 빌드 제품 페이지. UI 레이블 또는 네비게이션 아이템. 페이지: native-build.astro. 메시지 키: Native Build V2 Wiz Ios S3 L , 그러나 5단계에서 어드혹 대신:

1. 애플 스토어 애플 개발자 프로파일로 이동
2. 클릭 + 버튼
3. 선택 Ad Hoc 계속하기를 클릭하세요
4. 앱과 배포 인증서를 선택하세요
5. 등록하고 싶은 기기를 선택하세요
6. 프로파일 이름과 다운로드

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 needed.

신희 빌드 실행

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

CI/CD와 함께신희 빌드

GitHub 액션의 경우, 앱 스토어 빌드보다 비밀번호를 적게 입력해야합니다:

/github/workflows/ios-adhoc-build.yml

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

팁

주의하십시오 APPLE_KEY_ID, APPLE_ISSUER_ID, 그리고 APPLE_KEY_CONTENT 이용되지 않는다.

확장 프로그램이 포함된 앱 (다중 대상 인증)

앱이 확장 프로그램을 포함하고 있다면 (공유 확장 프로그램, 위젯, 알림 서비스 확장 프로그램 등), 각 확장 프로그램 대상에는 riêng의 인증서가 필요합니다. 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:

1. 모바일 프로비전 파일을 읽습니다.
2. 내장된 plist에서 프로파일 이름을 자동으로 추출합니다.
3. 파일을 Base64로 인코딩합니다.
4. 모든 것을 단일 CAPGO_IOS_PROVISIONING_MAP 인증 정보

팁

모든 대상에 대해 하나의 배포 인증서가 필요합니다. — 단, 대상당만 프로비전 프로파일이 다릅니다.

싱글 프로파일에서 마이그레이션

이전에는 BUILD_PROVISION_PROFILE_BASE64 싱글 프로파일을 사용했다면 다음을 실행하세요:

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"

팁

사용 update (아니면 save)을 사용하여 기존 인증서에 프로파일을 추가합니다. 명령어는 기존 프로파일과 새로운 프로파일을 병합합니다. 기존 인증서의 모든 프로파일을 설정할 때만 사용하세요. update 문제 해결 save 문제 해결

프로비전 프로파일에는 XYZ 기능이 포함되어 있지 않습니다.

프로비전 프로파일에는 XYZ 기능이 포함되어 있지 않습니다.

일부 경우, 다음 오류를 볼 수 있습니다:

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

이러한 오류는 프로비저닝 프로파일이 생성된 후에 새로운 기능을 활성화한 경우에 발생합니다. 기존의 프로비저닝 프로파일에는 새로운 기능이 포함되지 않았습니다.

이 문제를 해결하려면 프로비저닝 프로파일을 다시 생성해야 합니다.

1. 열기 애플 개발자 포털
2. 정확한 팀을 드롭다운 메뉴에서 선택하세요
3. 버튼 클릭 Profiles 프로파일 버튼
4. Copy to clipboard
5. 프로필 편집 버튼을 클릭하세요. Edit 버튼
6. 프로필 저장 버튼을 클릭하세요. Save 버튼
7. 버튼 Download 애플 개발자 프로필 다운로드
8. Re-run the Capgo Native Build setup command 다시 실행한 __CAPGO_KEEP_0__ 네이티브 빌드 설정 명령어와 함께 새로 다운로드한 프로필을 사용하세요.

이 문제를 해결해야 합니다.

기타 문제

어떤 이유로든 Capgo 네이티브 빌드, 인증 정보를 구성하거나 앱을 빌드하는 문제가 있으시다면, Capgo에 문의해 주세요. 지원.

iOS 빌드에서 계속 진행하세요

iOS 빌드 를 사용하여 CI/CD 자동화 계획을 세우고 __CAPGO_KEEP_0__ CI/CD와 연결하세요. __CAPGO_KEEP_0__ CI/CD Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, CI/CD 통합 CI/CD 통합을 위한 구현 세부 정보 GitHub Actions Integration for the implementation detail in GitHub Actions Integration.