자격 증명 관리

편리한 클라우드 빌드를 위해 로컬 머신에서 iOS 및 Android 빌드 자격 증명을 관리하세요.

개요

Capgo CLI를 사용하면 .capgo-credentials 폴더에 빌드 자격 증명을 로컬 머신에 저장할 수 있습니다. 빌드를 실행하면 이러한 자격 증명이 자동으로 사용되어 Capgo의 빌드 서버로 안전하게 전송됩니다.

자격 증명 얻기 도움이 필요하신가요?

아직 인증서와 자격 증명이 없다면 다음 포괄적인 가이드를 확인하세요:

iOS:

• iOS 인증서 얻는 방법 - 단계별 가이드
• iOS 인증서 가이드 (Capawesome) - 스크린샷이 포함된 자세한 튜토리얼
• 블로그: 자동 iOS 빌드 - 전체 CI/CD 설정

Android:

• 키스토어 생성하기 - 단계별 가이드
• Android 인증서 가이드 (Capawesome) - 스크린샷이 포함된 자세한 튜토리얼
• 블로그: 자동 Android 빌드 - 전체 CI/CD 설정

보안 보장

귀하의 자격 증명은 Capgo 서버에 영구적으로 저장되지 않습니다:

• ✅ 활성 빌드 프로세스 중에만 사용됩니다
• ✅ 빌드 완료 후 자동 삭제됩니다
• ✅ 최대 보관 기간: 24시간 (빌드 실패 시에도)
• ✅ 앱은 App Store/Play Store로 직접 전송됩니다 - 저희는 아무것도 저장하지 않습니다
• ✅ HTTPS를 통해 안전하게 전송됩니다

명령어

자격 증명 저장

자동 사용을 위해 빌드 자격 증명을 로컬에 저장합니다:

npx @capgo/cli build credentials save --platform <ios|android> [options]

자격 증명 목록

현재 저장된 자격 증명 보기 (비밀번호는 마스킹됨):

npx @capgo/cli build credentials list

자격 증명 지우기

로컬 머신에서 저장된 자격 증명을 제거합니다:

# 모든 자격 증명 지우기
npx @capgo/cli build credentials clear

# iOS 자격 증명만 지우기
npx @capgo/cli build credentials clear --platform ios

# Android 자격 증명만 지우기
npx @capgo/cli build credentials clear --platform android

iOS 자격 증명 저장

참고

아직 iOS 인증서가 없으신가요? 인증서 및 프로비저닝 프로파일 생성 지침은 iOS 빌드 가이드를 참조하세요.

전체 예시

npx @capgo/cli build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "YourP12Password" \
  --provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id "ABC1234567" \
  --apple-issuer-id "00000000-0000-0000-0000-000000000000" \
  --apple-team-id "TEAM123456"

iOS 옵션

옵션	설명	필수
--certificate <path>	.p12 인증서 파일 경로	예 (릴리스)
--p12-password <password>	.p12 인증서 비밀번호	예 (릴리스)
--provisioning-profile <path>	.mobileprovision 파일 경로	예 (릴리스)
--provisioning-profile-prod <path>	프로덕션 프로비저닝 프로파일 (선택사항)	아니오
--apple-key <path>	App Store Connect API .p8 키 경로	예 (제출)
--apple-key-id <id>	App Store Connect API 키 ID	예 (제출)
--apple-issuer-id <id>	App Store Connect API Issuer ID (UUID)	예 (제출)
--apple-team-id <id>	App Store Connect 팀 ID	예 (제출)
--apple-id <email>	Apple ID 이메일 (대체 인증)	아니오
--apple-app-password <password>	앱별 비밀번호 (대체 인증)	아니오

저장되는 내용

iOS 자격 증명을 저장하면 CLI는:

1. 인증서 및 프로비저닝 프로파일 파일을 읽습니다
2. base64 인코딩으로 변환합니다
3. .capgo-credentials 폴더에 자격 증명을 저장합니다
4. 비밀번호와 ID를 일반 텍스트로 저장합니다 (로컬 파일만)

저장된 파일 구조:

{
  "ios": {
    "BUILD_CERTIFICATE_BASE64": "...",
    "BUILD_PROVISION_PROFILE_BASE64": "...",
    "APPLE_KEY_CONTENT": "...",
    "P12_PASSWORD": "...",
    "APPLE_KEY_ID": "ABC1234567",
    "APPLE_ISSUER_ID": "...",
    "APP_STORE_CONNECT_TEAM_ID": "TEAM123456"
  }
}

Android 자격 증명 저장

참고

아직 키스토어가 없으신가요? 키스토어 생성 및 Play Store 자격 증명 설정 지침은 Android 빌드 가이드를 참조하세요.

전체 예시

npx @capgo/cli build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "KeyPassword123" \
  --keystore-store-password "StorePassword123" \
  --play-config ./play-store-service-account.json

Android 옵션

옵션	설명	필수
--keystore <path>	.keystore 또는 .jks 파일 경로	예 (릴리스)
--keystore-alias <alias>	키스토어의 키 별칭	예 (릴리스)
--keystore-key-password <password>	키 별칭의 비밀번호	예 (릴리스)
--keystore-store-password <password>	키스토어의 비밀번호	예 (릴리스)
--play-config <path>	Play Store 서비스 계정 JSON 경로	예 (제출)

저장되는 내용

Android 자격 증명을 저장하면 CLI는:

1. 키스토어 및 서비스 계정 JSON 파일을 읽습니다
2. base64 인코딩으로 변환합니다
3. .capgo-credentials 폴더에 자격 증명을 저장합니다
4. 비밀번호와 별칭을 일반 텍스트로 저장합니다 (로컬 파일만)

저장된 파일 구조:

{
  "android": {
    "ANDROID_KEYSTORE_FILE": "...",
    "PLAY_CONFIG_JSON": "...",
    "KEYSTORE_KEY_ALIAS": "my-key-alias",
    "KEYSTORE_KEY_PASSWORD": "...",
    "KEYSTORE_STORE_PASSWORD": "..."
  }
}
}

저장된 자격 증명 사용

자격 증명을 저장하면 빌드 시 자동으로 사용됩니다:

# .capgo-credentials 폴더에서 자격 증명이 자동으로 로드됩니다
npx @capgo/cli build com.example.app --platform ios

환경 변수를 사용하여 저장된 자격 증명을 재정의할 수도 있습니다:

# 환경 변수가 저장된 자격 증명보다 우선합니다
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
npx @capgo/cli build com.example.app --platform ios

우선 순위:

1. 환경 변수 (최우선)
2. .capgo-credentials 폴더의 저장된 자격 증명
3. 자격 증명 없음 (최하위)

저장된 자격 증명 보기

저장한 자격 증명 목록 확인:

npx @capgo/cli build credentials list

예시 출력:

📋 저장된 빌드 자격 증명:

iOS 자격 증명:
  ✓ Certificate (base64)
  ✓ Provisioning Profile (base64)
  ✓ Apple Key Content (base64)
  ✓ P12 Password: ********
  ✓ Apple Key ID: ABC1234567
  ✓ Apple Issuer ID: 00000000-0000-0000-0000-000000000000
  ✓ Team ID: TEAM123456

Android 자격 증명:
  ✓ Keystore (base64)
  ✓ Play Store Config (base64)
  ✓ Keystore Alias: my-key-alias
  ✓ Key Password: ********
  ✓ Store Password: ********

위치: .capgo-credentials/

🔒 이러한 자격 증명은 귀하의 머신에만 로컬로 저장됩니다.
   빌드 시 Capgo로 전송되지만 절대 저장되지 않습니다.
   빌드 완료 후 자동 삭제됩니다 (최대 24시간).

보안 모범 사례

로컬 저장소 보안

1. 파일 권한

   # 자격 증명 폴더를 다른 사람이 읽을 수 없도록 설정
   chmod 700 .capgo-credentials
   chmod 600 .capgo-credentials/*

2. 자격 증명 커밋 금지

   # .gitignore에 추가
   echo ".capgo-credentials/" >> .gitignore

3. 자격 증명 분리

   • 로컬 개발과 CI/CD에 다른 자격 증명 사용
   • 자격 증명을 정기적으로 교체
   • 팀 구성원 간에 자격 증명을 공유하지 마세요

CI/CD 사용

CI/CD 환경의 경우 저장된 자격 증명보다 환경 변수를 선호하세요:

# GitHub Actions
env:
  BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
  P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
  # ... 기타 시크릿

이것이 더 안전한 이유:

• 시크릿이 CI/CD 플랫폼에서 관리됩니다
• 러너에 자격 증명 파일이 없습니다
• 쉬운 교체 및 액세스 제어
• 시크릿 사용에 대한 감사 추적

자격 증명 교체

자격 증명을 정기적으로 교체하세요:

1. iOS: 매년 새 인증서 및 API 키 생성
2. Android: 매년 키스토어 비밀번호 변경
3. 팀 변경 후: 팀 구성원이 떠날 때 교체

저장된 자격 증명 업데이트:

# 새 자격 증명으로 저장 명령 다시 실행
npx @capgo/cli build credentials save --platform ios --certificate ./new-cert.p12 ...

문제 해결

”자격 증명을 찾을 수 없습니다”

빌드에서 자격 증명을 찾을 수 없다고 표시되면:

1. 자격 증명이 저장되어 있는지 확인:

   npx @capgo/cli build credentials list

2. 누락된 경우 자격 증명 저장:

   npx @capgo/cli build credentials save --platform ios ...

3. 자격 증명 폴더가 존재하는지 확인:

   ls -la .capgo-credentials/

“자격 증명 읽기 권한이 거부되었습니다”

파일 권한 수정:

chmod 700 .capgo-credentials
chmod 600 .capgo-credentials/*

자격 증명이 사용되지 않음

올바른 플랫폼이 지정되었는지 확인:

# --platform이 저장된 자격 증명과 일치하는지 확인
npx @capgo/cli build com.example.app --platform ios  # iOS 자격 증명 사용
npx @capgo/cli build com.example.app --platform android  # Android 자격 증명 사용

자격 증명 지우기 및 다시 저장

자격 증명이 손상된 것 같으면:

# 모든 자격 증명 지우기
npx @capgo/cli build credentials clear

# 다시 저장
npx @capgo/cli build credentials save --platform ios ...

환경 변수에서 마이그레이션

현재 환경 변수를 사용 중이라면 저장된 자격 증명으로 마이그레이션할 수 있습니다:

1. 현재 환경 변수 추출

   echo $BUILD_CERTIFICATE_BASE64  # 존재하는지 확인

2. base64 파일을 원본 파일로 다시 디코딩 (필요한 경우)

   echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
   echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

3. CLI를 사용하여 저장

   npx @capgo/cli build credentials save \
     --platform ios \
     --certificate ./cert.p12 \
     --provisioning-profile ./profile.mobileprovision \
     --p12-password "$P12_PASSWORD" \
     --apple-key-id "$APPLE_KEY_ID" \
     --apple-issuer-id "$APPLE_ISSUER_ID" \
     --apple-team-id "$APP_STORE_CONNECT_TEAM_ID"

4. 빌드 테스트

   npx @capgo/cli build com.example.app --platform ios

5. 환경 변수 제거 (선택사항)

   unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

파일 위치

자격 증명은 .capgo-credentials 폴더에 저장됩니다:

• macOS/Linux: .capgo-credentials/ (프로젝트 루트 또는 홈 디렉토리)
• Windows: .capgo-credentials\ (프로젝트 루트 또는 홈 디렉토리)

폴더는 처음 자격 증명을 저장할 때 자동으로 생성됩니다.

다음 단계

• 시작하기 - 첫 번째 빌드 생성
• iOS 빌드 - iOS 전용 빌드 구성
• Android 빌드 - Android 전용 빌드 구성
• 문제 해결 - 일반적인 문제 및 해결 방법

도움이 필요하신가요?

• 📚 문제 해결 가이드
• 💬 Discord 커뮤니티
• 📧 이메일: support@capgo.app