문제 해결

Capgo Cloud Build와 함께 네이티브 앱을 빌드할 때 발생하는 일반적인 문제의 해결책입니다.

빌드 실패

”Upload failed” or “Connection timeout”

Symptoms:

• 증상:
• 프로젝트 업로드 중 빌드가 실패합니다.

60초 이상 시간 초과 오류

1. 해결책:

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. 프로젝트 크기를 줄이기

   • 보장 node_modules/ __CAPGO_KEEP_0__이 업로드되지 않고(자동으로 제외되어야 함)
   • 프로젝트에 큰 파일이 있는지 확인:

   find . -type f -size +10M

3. 업로드 URL 만료 확인

   • 업로드 URL은 1시간 후 만료
   • 만료된 URL 오류가 발생하면 다시 빌드 명령어를 실행

Tip

대형 프로젝트는 빌드 시간 제한 (see 알려진 제한 사항)을 초과할 수 있습니다. 기업 옵션에 대한 지원을 문의하세요.

10분 이내의 빌드 타임아웃

증상:

• 빌드 시간이 최대 허용 시간을 초과합니다.
• 상태는 timeout

해결 방법:

1. 의존성 최적화

   • 사용하지 않는 npm 패키지를 제거
   • 사용하기 npm prune --production __CAPGO_KEEP_0__

2. 네트워크 문제가 있는지 확인하기

   • 빌드 중에 일부 의존성이 큰 파일을 다운로드 할 수 있습니다
   • 특정 사용 사례에 대해 한정된 시간을 조정할 수 있습니다

3. 자연어 의존성 검토

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. 지원 문의

   • 앱이 합법적으로 더 많은 시간이 필요하다면
   • 인증 문제

인증 문제

API 키가 유효하지 않음

증상:

• 인증 오류로 인해 빌드가 즉시 실패합니다.
• 401 또는 403 오류

해결 방법:

1. API 키가 올바른지 확인하세요.

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. API 키 권한을 확인하세요.

   • 키는 반드시 write 또는 all 권한
   • Capgo Capgo 대시보드의 API 키 아래에서 확인

3. API 키가 읽히고 있는지 확인

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. 재인증

   bunx @capgo/cli@latest login

”App not found” or “No permission for this app”

앱이 없거나 앱에 대한 권한이 없습니다

• 인증이 작동하지만 앱 특정 오류

해결책:

1. 앱이 등록되어 있는지 확인하세요

   bunx @capgo/cli@latest app list

2. 앱 ID가 일치하는지 확인하세요

   • 확인 capacitor.config.json appId
   • 사용하는 명령어에 올바른 앱 ID를 사용하는지 확인하세요

3. 조직 접근 권한이 있는지 확인하세요

   • 올바른 조직에 있는지 확인하세요
   • API key must have access to the app’s organization

iOS 빌드 문제

”Code signing failed”

증상:

• Build fails during code signing phase
• Xcode는 인증서 또는 프로파일과 관련된 오류를 표시합니다.

해결책:

1. 인증서의 유형이 빌드 유형과 일치하는지 확인하십시오.

   • 개발 빌드는 개발 인증서가 필요합니다.
   • 앱 스토어 빌드는 배포 인증서가 필요합니다.

2. 인증서와 프로파일이 일치하는지 확인하십시오.

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. 프로비저닝 프로파일이 유효한지 확인하세요

   • 만료일을 확인하세요
   • 앱 ID가 포함되어 있는지 확인하세요
   • 인증서가 포함되어 있는지 확인하세요

4. 인증서/프로파일을 재생성

   • 기존 인증서/프로파일 삭제
   • 애플 개발자 포털에서 새로운 인증서/프로파일 생성
   • 환경 변수를 재인코딩하고 업데이트

“인증서가 포함되지 않은 프로비저닝 프로파일”

__CAPGO_KEEP_0__:

• Xcode에서 프로파일에 인증서가 없다고 말합니다.

__CAPGO_KEEP_1__:

1. 최신 프로파일을 Apple에서 다운로드하세요.

   • Apple Developer → 인증서, ID 및 프로파일로 이동하세요.
   • 프로비전 프로파일을 다운로드하세요.
   • 인증서가 포함되어 있는지 확인하세요.

2. 프로파일에 인증서가 있는지 확인하세요.

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. 인증서가 올바른 인증서인지 다시 생성하세요.

   • Apple Developer 포털에서 프로파일을 편집하세요.
   • __CAPGO_KEEP_0__ 인증서를 선택하십시오
   • 다운로드 및 재 인코딩

애플 스토어 연결 인증이 실패했습니다

증상:

• 테스트 플라이트로 업로드가 실패합니다
• API 키 오류

해결책:

1. API 키 인증서를 확인하십시오

   • APPLE_KEY_ID (10자리여야 함)를 확인하십시오
   • APPLE_ISSUER_ID (UUID 형식이어야 함)를 확인하십시오
   • APPLE_KEY_CONTENT가 올바르게 base64 인코딩되어 있는지 확인하십시오

2. __CAPGO_KEEP_0__

   • __CAPGO_KEEP_1__
   • __CAPGO_KEEP_2__
   • __CAPGO_KEEP_3__ __CAPGO_KEEP_4__ __CAPGO_KEEP_5__ __CAPGO_KEEP_6__
   • __CAPGO_KEEP_7__ __CAPGO_KEEP_8__ __CAPGO_KEEP_9__
   • __CAPGO_KEEP_10__ timedatectl status __CAPGO_KEEP_11__
   • After Capgo를 다시 동기화 한 후, Capgo 빌드 또는 자격 증명 명령을 다시 실행하세요.

   See Apple의 API 요청에 대한 토큰을 생성하는 방법 App Store Connect 토큰 유효 기간 규칙에 대한 문서를 참조하세요.

3. API 키를 로컬에서 테스트하세요.

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. API 키 권한을 확인하세요.

   • 키가 '개발자' 역할 이상이어야 합니다.
   • App Store Connect -> 사용자 및 액세스 -> 키에서 확인하세요.

5. 키가 취소되지 않았는지 확인하세요.

   • App Store Connect에서 확인하세요.
   • 새 키가 필요하면 생성하세요

”Pod 설치 실패”

증상:

• 코코아팟(CocoaPods) 설치 중 빌드 실패
• Podfile 오류

해결 방법:

1. Podfile.lock이 커밋되었는지 확인하세요

   git status ios/App/Podfile.lock

2. 지역적으로 pod 설치 테스트

   cd ios/App
   pod install

3. 비호환성 있는 pods를 확인하세요

   • Podfile의 버전 충돌을 검토하세요
   • iOS 배포 대상이 지원하는 모든 pods가 있는지 확인하세요

4. pod 캐시를 삭제하세요

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Android 빌드 문제

Keystore 비밀번호가 잘못되었습니다

증상:

• 빌드가 서명 중에 실패합니다.
• Gradle에서 키 스토어에 대한 오류

해결 방법:

1. 키 스토어 비밀번호를 확인하세요.

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. 환경 변수를 확인하세요.

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. base64 인코딩을 확인하세요.

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

키 별칭이 없습니다

증상:

• 별칭 오류로 서명이 실패합니다

해결책:

1. 키 스토어 별칭 목록

   keytool -list -keystore my-release-key.keystore

2. 별칭이 정확히 일치하는지 확인

   • 별칭은 대소문자를 구분합니다
   • KEYSTORE_KEY_ALIAS에 오류가 있는지 확인

3. 키 스토어에서 올바른 별칭을 사용

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

”Gradle build failed”

증상:

• 일반적인 Gradle 오류
• 컴파일 또는 의존성 문제

해결책:

1. 지역 테스트 빌드 먼저 확인

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 의존성 누락 여부 확인

   • Gradle 파일을 검토하세요
   • 모든 플러그인을 의존성에 나열하십시오

3. Gradle 버전 호환성을 확인하십시오

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Gradle 캐시를 삭제하십시오

   cd android
   ./gradlew clean
   rm -rf .gradle build

플레이 스토어 업로드 실패

증상:

• 빌드가 성공하지만 업로드가 실패합니다
• __CAPGO_KEEP_0__

해결 방법:

1. 서비스 계정 JSON을 확인하세요

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. 서비스 계정 권한을 확인하세요

   • Play Console → 설정 → API 접근으로 이동
   • 서비스 계정에 앱에 대한 접근 권한이 있는지 확인하세요
   • '테스트 트랙으로 출시' 권한을 부여하세요

3. Play Console에서 앱을 설정했는지 확인하세요

   • Play Console에서 앱을 먼저 생성해야 합니다
   • 최소한 한 개의 APK를 수동으로 업로드해야 합니다

4. API이 활성화되어 있는지 확인하세요.

   • API 활성화가 Google Play Developer에 필요합니다.
   • Google Cloud Console에서 확인하세요.

일반적인 문제

”Job not found” or “Build status unavailable”

증상:

• 빌드 상태를 확인할 수 없습니다.
• Job ID 오류

해결책:

1. 잠시 기다리세요. 다시 시도해 보세요.

   • 작업을 초기화하는 데 몇 초가 걸릴 수 있습니다.

2. 작업 ID가 정확한지 확인하세요.

   • 초기 빌드 응답에서 작업 ID를 확인하세요.

3. 빌드가 만료되지 않았는지 확인하세요.

   • 빌드 데이터는 24시간 동안 사용할 수 있습니다.

프로젝트 동기화 실패

증상:

• 컴파일이 시작되기 전에 빌드가 실패합니다.
• 파일이 누락된 오류

해결책:

1. Capacitor를 로컬에서 동기화하세요.

   bunx cap sync

2. 모든 네이티브 파일이 커밋된 것을 확인하세요

   git status ios/ android/

3. gitignored 네이티브 파일을 확인하세요

   • .gitignore 파일을 검토하세요
   • 중요한 설정 파일이 무시되지 않는지 확인하세요

성공적으로 빌드되었지만 출력을 볼 수 없어요

증상:

• 빌드가 성공했지만 다운로드 링크가 보이지 않습니다

해결책:

1. 빌드 설정 확인

   • 아티팩트 저장소가 설정되지 않았을 수 있습니다
   • 아티팩트 접근이 불가능한 빌드에 대한 지원을 받으세요

2. iOS TestFlight 제출을 위해

   • App Store Connect 확인
   • 업로드 후 처리는 5-30분이 소요될 수 있습니다

3. Android Play Store를 위해

   • Play Console → Testing → Internal testing 확인
   • 처리 시간은 몇 분 정도 소요될 수 있습니다

CI/CD 관련 문제

GitHub Actions: “명령어를 찾을 수 없습니다”

증상:

• bunx @capgo/cli@latest … CI에서 “명령어를 찾을 수 없습니다”로 실패합니다

해결 방법:

1. Bun을 먼저 설정하세요 그렇다면 bunx __CAPGO_KEEP_0__이 사용 가능합니다.

   - uses: oven-sh/setup-bun@v2

2. 그 다음 CLI을 실행하세요 — bunx __CAPGO_KEEP_0__은 필요할 때만 다운로드하여 글로벌 설치가 필요하지 않습니다:

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub Actions: “Secrets not found”

증상:

• 빌드 시 환경 변수가 비어 있습니다.

해결 방법:

1. 비밀 키가 설정되어 있는지 확인하세요.

   • Repo 설정 → Secrets 및 변수 → Actions로 이동하세요.
   • 필요한 모든 비밀 키를 추가하세요.

2. 정확한 문법을 사용하세요.

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. 비밀 키 이름이 일치하는지 확인하세요.

   • 이름은 대소문자를 구분합니다.
   • 비밀 참조에 오류가 없는지 확인하세요

더 많은 도움말 얻기

Verbose 로깅을 활성화하세요

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

빌드 정보 수집

사용한 빌드 명령어

1. 터미널 창

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. 오류 메시지 (전체 출력)

3. 작업 ID (빌드 출력에서)

4. 빌드 로그 (터미널 출력 전체 복사)

5. 환경 정보

   node --version
   npm --version
   bunx @capgo/cli@latest --version

지원 문의

• __CAPGO_KEEP_0__: __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__: capgo@capgo.app
• __CAPGO_KEEP_0__: Capgo Capgo

__CAPGO_KEEP_0__ __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

• 10분
• ~500MB
• iOS 빌드는 24시간 Mac 렌탈이 필요하며 Mac에서 빌드하면 최적의 사용을 위해 큐에 등록됩니다.
• 빌드 아티팩트 다운로드 가능성은 빌드 목적지와 아티팩트 저장 설정에 따라 다릅니다.

이 제한 사항은 피드백에 따라 조정될 수 있습니다.

추가 리소스

• 시작하기 - 초기 설정 가이드
• iOS 빌드 - iOS 전용 설정
• Android 빌드 - Android 전용 설정
• CLI 참조 - 완전한 명령어 문서