시작하기

Capgo Cloud Build로 시작하고 몇 분 만에 첫 iOS 또는 Android 네이티브 빌드를 만들어 보세요.

준비 사항

시작하기 전에 다음 사항을 확인하세요:

• 로컬에서 정상적으로 빌드되는 Capacitor 앱
• Node.js 20 이상 설치
• Capgo 계정 (무료 체험으로도 시작하기에 충분합니다)
• Capgo에 앱이 이미 등록되어 있음 (실행 npx @capgo/cli@latest app add 등록되지 않은 경우)
• (서명 자격 증명을 미리 준비할 필요는 없습니다 — 다음 단계에서 설정합니다.)

서명 자격 증명 설정

Capgo는 앱을 빌드하고 제출하려면 서명 자격 증명이 필요합니다 — 하지만 직접 씨름할 필요는 없습니다. 몇 가지 질문에 답하면 실행할 정확한 명령어를 알려드립니다:

첫 번째 빌드 실행

빌드하려면 Capgo에 인증되어 있어야 합니다. 아직 인증하지 않았다면:

npx @capgo/cli@latest login
# or, in CI, set the token directly:
export CAPGO_TOKEN=your_api_key

방금 실행했다면 build init, 이미 준비가 끝났습니다. 온보딩 마지막에 빌드를 시작하도록 제안하므로, 첫 번째 빌드가 이미 진행 중일 수 있습니다. 🎉

아니면, 직접 빌드를 시작하세요 build request — --platform 를 빌드하려는 플랫폼으로 설정하세요:

npx @capgo/cli@latest build request com.example.app --platform <android|ios> --build-mode debug

CLI은 준비된 네이티브 프로젝트를 업로드하고 터미널에 빌드 로그를 실시간으로 스트리밍합니다. Capgo 빌드는 서명된 아티팩트를 반환하거나, 적절한 릴리스 플로우를 구성하면 App Store Connect 또는 Google Play에 제출할 수 있습니다.

빌드 프로세스 이해하기

빌드 명령을 실행하면 다음과 같은 일이 발생합니다:

flowchart LR
    A[Your CI] -->|1. Prepare Native Project| B[Prepared iOS / Android Project]
    B -->|2. Upload| C[Capgo Build]
    C -->|3. Compile and Sign| D[Dedicated Build Infrastructure]
    D -->|4. Stream Logs| E[Your Terminal]
    D -->|Return Signed Artifact or Store Delivery| F[Output]
    D -->|5. Clean Temporary Project Data| G[Cleanup]

1. CI에서 준비 - 웹 레이어를 빌드하고, 비공개 의존성을 해결하며, 완성된 에셋을 네이티브 프로젝트에 동기화합니다.
2. 업로드 - 준비된 네이티브 프로젝트가 빌드를 위해 보안 클라우드 스토리지에 업로드됩니다.
3. 빌드 실행 - Capgo가 전용 인프라에서 네이티브 프로젝트를 컴파일하고 서명합니다.
4. 로그 스트리밍 - 실시간 로그가 Server-Sent Events를 통해 터미널로 스트리밍됩니다.
5. 정리 - 빌드 환경과 임시 프로젝트 데이터는 빌드 후 정리됩니다. 출력물 보존 기간은 선택한 아티팩트 및 스토어 배포 옵션에 따라 달라집니다.

Bitrise 또는 다른 CI에서 Capgo Build 사용

Capgo Build는 기존 CI를 대체하지 않습니다. Bitrise 또는 다른 CI 시스템에서 비공개 접근이 필요한 단계(비공개 레지스트리 설치, SSH를 통한 비공개 CocoaPods 해결, 커스텀 네이티브 설정 실행, 웹 레이어 빌드 및 실행)는 그대로 유지하세요. npx cap sync.

준비된 네이티브 프로젝트로 Capgo Build를 호출합니다. Capgo은 컴파일 및 서명을 위해 준비된 ios/ 또는 android/ 프로젝트를 수신하므로, 비공개 Nexus, CocoaPods SSH 또는 웹 빌드 자격 증명이 필요하지 않습니다. 컴파일된 웹 에셋은 이미 해당 준비된 네이티브 프로젝트 내에 포함되어 있으며, 소스 저장소로 보관되는 것이 아니라 빌드에 사용됩니다.

빌드되는 내용

Capgo Build는 앱 컴파일에 필요한 준비된 네이티브 프로젝트를 수신합니다. 웹 소스 code, 비공개 의존성 설치 및 Capacitor 동기화는 CI에 유지됩니다.

업로드되는 내용

포함됨	설명
ios/ 또는 android/	빌드 중인 네이티브 플랫폼 폴더
package.json, package-lock.json	의존성 매니페스트
capacitor.config.*	Capacitor 설정
resources/	앱 아이콘, 스플래시 화면
네이티브 플러그인 code	오직 ios/ 또는 android/ 각 Capacitor 플러그인의 하위 폴더만

업로드 제외 항목

제외됨	이유
node_modules/ (대부분)	네이티브 플러그인 code만 포함되며, JS 의존성은 제외됩니다
src/	웹 소스 code는 로컬에 유지됩니다
dist/, www/, build/ (루트 레벨)	을(를) 통해 네이티브 폴더에 동기화됨 cap sync
.git/	버전 관리 히스토리
.gradle/, .idea/, .swiftpm/	빌드 캐시 및 IDE 설정
.env, 시크릿	업로드되지 않음

참고

빌드된 웹 에셋(JS, CSS, HTML)은 다음 이유만으로 업로드됩니다 npx cap sync 네이티브 프로젝트에 복사합니다. 웹 소스 및 의존성 설치 단계는 CI에 유지되며, 준비된 네이티브 프로젝트는 바이너리 빌드에 사용된 후 정리됩니다.

귀하의 책임

실행 전 npx @capgo/cli@latest build request:

1. CI에서 준비 - Bitrise 또는 기존 CI에서 프라이빗 패키지 레지스트리, SSH 기반 CocoaPods, 디바이스 SDK, 확장 기능 및 기타 사용자 정의 네이티브 준비 작업을 처리합니다.
2. 웹 에셋 빌드하기 - 실행 npm run build (또는 프레임워크의 빌드 명령).
3. 네이티브로 동기화 - 실행 npx cap sync 컴파일된 웹 자산을 준비된 네이티브 프로젝트로 복사합니다.
4. 네이티브 빌드 요청 - 준비된 ios/ 또는 android/ 프로젝트를 Capgo Build로 전송합니다.

Capgo Build가 처리하는 항목

• 네이티브 iOS 컴파일 (Xcode, Fastlane)
• 네이티브 Android 컴파일 (Gradle)
• 사용자 자격 증명을 이용한 Code 서명
• 선택 사항: App Store Connect 또는 Google Play 제출
• 환경 변수로 전달되는 지원되는 네이티브 빌드 구성 및 자격 증명 값

CI가 네이티브 프로젝트를 준비한 후에는 Capgo Build가 사용자의 비공개 Nexus 레지스트리나 SSH 자격 증명에 접근할 필요가 없습니다. 참고 빌드 구성 지원되는 환경 변수 및 저장 옵션을 확인하세요.

MDM을 통해 배포되는 키오스크 플레버의 경우, Android 프로젝트/빌드를 APK 생성하도록 구성하세요. 빌드를 요청할 때 Google Play를 건너뛰고 서명된 출력을 가져오려면 두 플래그를 모두 사용하세요:

npx @capgo/cli@latest build request YOUR_APP_ID --platform android --no-playstore-upload --output-upload

--no-playstore-upload Play 자격 증명이 저장되어 있더라도 Play Store 업로드를 방지합니다; --output-upload 서명된 출력에 대한 시간 제한 링크를 제공합니다. 해당 APK를 MDM을 통해 배포하세요.

다음 단계

첫 번째 빌드를 생성했으니 이제:

• iOS 빌드 구성 - 인증서 및 프로필 설정
• Android 빌드 설정 - Keystore 및 Play Store 설정
• 문제 해결 - 일반적인 문제 및 해결 방법
• CLI 레퍼런스 - 전체 명령어 문서

도움이 필요하신가요?

• 앱 통합의 트러블슈팅 가이드
• 가입하기 Discord 커뮤니티에
• 이메일로 문의하기 support@capgo.app