__CAPGO_KEEP_0__ 문제 해결

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

빌드 실패

업로드 실패

증상:

• 프로젝트 업로드 중 빌드가 실패합니다.
• 60초 후 시간 초과 오류

해결 방법:

1. 인터넷 연결을 확인하세요

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

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

   • 업로드가 진행 중인지 확인하세요 (자동으로 제외되어야 함) node_modules/ 프로젝트 내에 큰 파일이 있는지 확인하세요:
   • 터미널 창

   find . -type f -size +10M

3. __CAPGO_KEEP_0__

   • 1시간 이내에 만료되는 업로드 URL
   • 만료된 URL 오류가 발생한 경우 다시 빌드 명령어를 실행하세요

팁

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

10분 이내에 빌드 시간 초과

증상:

• 빌드 시간이 최대 허용 시간을 초과
• 상태 표시 timeout

해결책:

1. 의존성 최적화

   • 사용하지 않는 npm 패키지 제거
   • 사용 npm prune --production 빌드하기 전에

2. 네트워크 문제 확인

   • 빌드 중에 대용량 파일 다운로드하는 의존성 있을 수 있습니다
   • 프리 캐싱을 위해 lock 파일 사용

3. 자연어 의존성 검토

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

4. 지원 문의

   • __CAPGO_KEEP_0__ 키가 유효하지 않거나 인증 오류가 발생할 때
   • __CAPGO_KEEP_0__ 키의 유효성을 확인할 수 있습니다.

인증 오류

API 키가 유효하지 않거나 인증 오류가 발생할 때

증상:

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

해결 방법:

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

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

2. API 키 권한 확인

   • 키는 write 또는 all 권한
   • 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

”앱이 존재하지 않거나” 또는 “이 앱에 대한 권한이 없습니다””

증상:

• 인증이 작동하지만 앱 관련 오류가 발생합니다

해결 방법:

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

   bunx @capgo/cli@latest app list

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

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

3. __CAPGO_KEEP_0__ 인증을 확인하세요

   • __CAPGO_KEEP_0__가 올바른 조직에 속해 있는지 확인하세요
   • API 키는 앱의 조직에 접근할 수 있어야 합니다

iOS 빌드 문제

Code 인증에 실패했습니다

증상:

• code 인증 단계에서 빌드가 실패합니다
• 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. 새로운 인증서/프로파일을 생성

   • 기존 인증서/프로파일을 삭제
   • 새로운 인증서/프로파일을 Apple Developer Portal에서 생성
   • 환경 변수를 재인코딩하고 업데이트

”Provisioning profile doesn’t include signing certificate”

증상:

• Xcode는 프로파일에서 인증서를 찾을 수 없습니다

해결책:

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. 정확한 인증서로 프로필 다시 생성

   • 애플 개발자 포털에서 프로필 편집
   • 배포 인증서가 선택되어 있는지 확인
   • 다운로드 및 재 인코딩

”App Store Connect authentication failed”

증상:

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

해결책:

1. API 키 인증 정보 확인

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

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

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

3. API 키의 권한을 확인하세요

   • 키는 '개발자' 역할 이상이여야 합니다
   • App Store Connect → 사용자 및 액세스 → 키 → 확인

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

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

Pod 설치 실패

증상:

• CocoaPods 설치 중 빌드 실패
• Podfile 오류

해결책:

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

   git status ios/App/Podfile.lock

2. 로컬에서 pod install 테스트

   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 password incorrect”

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"

__CAPGO_KEEP_1__

__CAPGO_KEEP_3__

• __CAPGO_KEEP_4__
• __CAPGO_KEEP_5__

__CAPGO_KEEP_6__

1. __CAPGO_KEEP_7__

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. __CAPGO_KEEP_10__

   • __CAPGO_KEEP_11__
   • __CAPGO_KEEP_0__을 모두 의존성 목록에 포함시켜야 합니다.

3. __CAPGO_KEEP_0__ Gradle 버전 호환성을 확인하세요.

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

4. Gradle 캐시를 지웁니다.

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

'Play Store 업로드 실패'

증상:

• 빌드가 성공했지만 업로드가 실패합니다.
• 서비스 계정 오류

해결책:

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

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

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

   • Play Console → 설정 → API 접근으로 이동
   • 앱에 대한 서비스 계정 접근 권한이 있는지 확인하세요
   • Grant “Release to testing tracks” permission

3. Play Console에서 앱이 설정되어 있는지 확인하세요

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

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

   • Google Play Developer API이 활성화되어야 함
   • Google Cloud Console에서 확인하십시오

일반적인 문제

'작업이 발견되지 않음' 또는 '빌드 상태가 사용할 수 없음'

증상:

• 빌드 상태를 확인할 수 없음
• 작업 ID 오류

해결 방법:

1. 잠시 기다리십시오 그리고 다시 시도하십시오

   • 빌드 작업이 몇 초 동안 초기화될 수 있습니다

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

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

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

   • 24시간 동안 빌드 데이터가 사용 가능합니다

프로젝트 동기화 실패

증상:

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

해결 방법:

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

   bunx cap sync

2. 모든 원본 파일이 커밋되었는지 확인하세요

   git status ios/ android/

3. gitignored 원본 파일이 있는지 확인하세요

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

성공적으로 빌드했지만 출력을 보지 못합니다

증상:

• 다운로드 링크가 보이지 않아 빌드가 성공적으로 완료된 것처럼 보입니다

해결책:

1. __CAPGO_KEEP_0__ Actions: “명령어 찾을 수 없음”

   • 빌드 설정 확인
   • 아티팩트 저장소가 구성되지 않았을 수 있습니다

2. 빌드에 대한 아티팩트 접근이 불가능한 경우 지원팀에 문의하세요

   • iOS TestFlight 제출을 위해
   • App Store Connect 확인

3. 업로드 후 처리가 5-30분 정도 소요될 수 있습니다

   • Android Play Store를 위해
   • Play Console → 테스트 → 내부 테스트 → 확인

처리 시간이 몇 초 정도 소요될 수 있습니다

GitHub Actions: “Command not found”

증상:

• 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 명령어: "비밀번호 찾을 수 없음"

증상:

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

해결책:

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

   • Repo 설정 → Secrets 및 변수 → 액션으로 이동하세요.
   • 필요한 모든 비밀번호를 추가하세요.

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

지원에 문의

• 디스코드: 우리社区에 가입하세요
• 이메일: support@capgo.app
• 문서: Capgo 문서

알려진 제한 사항

현재 제한 사항:

• 최대 빌드 시간: 10분
• 최대 업로드 크기: ~500MB
• iOS 빌드는 24시간 Mac 임대가 필요하며 Mac에서 빌드하면 최적의 사용을 보장하기 위해 대기열에 등록됩니다.
• 빌드 아티팩트 다운로드 가능성은 빌드 목적지와 아티팩트 저장소 구성에 따라 다릅니다.

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

추가 리소스

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