인증서 관리
복사할 수 있는 설치 지시와 전체 마크다운 가이드를 포함한 플러그인 설정 지시를 복사하세요.
iOS 및 Android 빌드 인증서를 관리하여 편리한 클라우드 빌드를 위해 로컬에서 빌드합니다.
Capgo CLI에서 빌드 인증서를 저장합니다. 컴퓨터에 저장 — Capgo의 서버에 저장하지 않습니다. 기본적으로 모든 프로젝트에 공유되는 하나의 전역 파일에 저장됩니다. ~/.capgo-credentials/credentials.json프로젝트당 --local 저장 프로젝트당 in .capgo-credentials.json 대신. 빌드가 완료될 때 저장된 인증 정보가 자동으로 사용되고 Capgo로 안전하게 전송되고 빌드가 완료된 후 삭제됩니다.
명령어
명령어 섹션인증서 관리
인증서 관리 섹션저장된 인증서와 작업하기 가장 빠른 방법은 인터랙티브 매니저입니다. 인터랙티브 매니저는 TUI(터미널 사용자 인터페이스)를 열어 저장된 인증서를浏览하고 앱 및 플랫폼에 대한 설정을 확인할 수 있습니다. 또한 CI/CD-준비된 파일을 내보내거나 플랫폼의 인증서를 삭제할 수 있습니다. build init 터미널 창 .env 복사
bunx @capgo/cli@latest build credentials manage| Option | 설명 |
|---|---|
--appId <appId> | 앱을 관리하세요 (생략 시 선택하도록 유도합니다) |
--platform <ios|android> | 관리할 플랫폼을 선택하세요 (생략 시 선택하도록 유도합니다) |
--local | 프로젝트별로 사용하세요 .capgo-credentials.json 전역 파일 대신 |
일회성 스크립트 명령어를 선호하세요? 아래 개별 명령어를 사용하세요.
인증서 저장
인증서 저장 섹션자동 사용을 위해 로컬에 인증서 저장하세요:
bunx @capgo/cli@latest build credentials save --platform <ios|android> [options]업데이트 인증서
업데이트 인증 정보기존 인증 정보 일부만 업데이트하려면 다시 모든 것을 제공하지 않아도 됩니다:
bunx @capgo/cli@latest build credentials update --platform <ios|android> [options]The update 명령어는 합쳐서 추가하는 방법을 사용하여 프로비전 프로파일을 제공합니다 — 새로운 프로파일은 기존 프로파일과 합쳐집니다. 전체 프로비전 맵을 대체하려면 예시 — 기존 인증 정보에 확장 프로파일을 추가: --overwrite-ios-provisioning-map.
업데이트 명령어는
bunx @capgo/cli@latest build credentials update \ --platform ios \ --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"동일한 옵션을 받습니다. save 모든 항목은 선택적이지만, 제공한 필드만 업데이트됩니다.
인증서 목록
인증서 목록 제목현재 저장된 인증서(비밀번호는 가려져 있습니다)를 보려면:
bunx @capgo/cli@latest build credentials list
# List credentials for a specific appbunx @capgo/cli@latest build credentials list --appId com.example.app페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).
인증서 삭제인증서 삭제 제목
# Clear all credentialsbunx @capgo/cli@latest build credentials clear
# Clear credentials for a specific app + platformbunx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios저장된 인증서를 로컬 기기에서 삭제합니다.:
인증 정보 이관기존 단일 프로파일 형식에서 새로운 다중 대상 형식으로 변환:
bunx @capgo/cli@latest build credentials migrate --platform ios컨텍스트: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label). BUILD_PROVISION_PROFILE_BASE64 이전 CAPGO_IOS_PROVISIONING_MAP인증 정보를 변환하고 , 그리고 레거시 키를 제거합니다. 자세한 내용은 Single Profile에서 다중 대상으로 마이그레이션
세부 정보
iOS 인증 정보 저장완전한 예시
제목이 "완전한 예시"인 섹션bunx @capgo/cli@latest build credentials save \ --platform ios \ --certificate ./cert.p12 \ --p12-password "YourP12Password" \ --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \ --apple-key ./AuthKey_ABC1234567.p8 \ --apple-key-id "ABC1234567" \ --apple-issuer-id "00000000-0000-0000-0000-000000000000" \ --apple-team-id "TEAM123456"iOS 옵션
iOS 옵션| Option | 설명 | 필수 |
|---|---|---|
--certificate <path> | .p12 인증서 파일 경로 | 예 (릴리즈) |
--p12-password <password> | .p12 인증서 암호 | 예 (릴리즈) |
--ios-provisioning-profile <mapping> | 프로비전 프로파일 매핑 (bundleId=path) 다중 타겟 앱에 대해 반복 가능합니다. 단일 프로파일 및 Bundle ID 접두사가 없는 경우 CLI 프로파일에서 자동으로 추론됩니다. | 예 (릴리즈) |
--apple-key <path> | 애플 스토어 연결 API .p8 키 경로 | 참고 ¹ |
--apple-key-id <id> | 애플 스토어 연결 API 키 ID | 참고사항 ¹ |
--apple-issuer-id <id> | 애플 스토어 연결 API 발급자 ID (UUID) | 참고사항 ¹ |
--apple-team-id <id> | 애플 스토어 연결 팀 ID | 네 |
--apple-id <email> | 애플 ID 이메일 (앱별 암호 업로드 대안, API 키 대신) | 참고사항 ² |
--apple-app-specific-password <password> | 애플 스토어 연결 앱별 암호xxxx-xxxx-xxxx-xxxx) | 참고사항 ² |
--apple-app-id <id> | 숫자형 애플 스토어 연결 앱 ID (예: 1234567890) | 참고사항 ² |
--ios-distribution <mode> | 배포 모드: app_store (기본) 또는 ad_hoc | 아니오 |
--output-upload | 빌드 아티팩트에 대한 시간 제한 Capgo 다운로드 링크를 활성화합니다. | 아니오 (기본:) false) |
--output-retention <seconds> | 빌드 출력을 얼마나 유지할 것인지 (예:) 3600s) | 아니오 (기본:) 3600s) |
--skip-build-number-bump | 자동 빌드 번호 증가를 생략합니다. | 아니오 |
저장되는 항목에 대한 설명
iOS 인증서를 저장할 때 __CAPGO_KEEP_0__:iOS 인증 정보를 저장할 때, CLI
- base64 인코딩으로 변환합니다.
- 저장합니다.
- Saves them to
~/.capgo-credentials/credentials.json(또는.capgo-credentials.jsonwith--local) - 비밀번호와 ID를 평문으로 저장합니다 (로컬 파일만)
저장된 파일 구조:
{ "ios": { "BUILD_CERTIFICATE_BASE64": "...", "CAPGO_IOS_PROVISIONING_MAP": "{\"com.example.app\":{\"profile\":\"...\",\"name\":\"match AppStore com.example.app\"}}", "APPLE_KEY_CONTENT": "...", "P12_PASSWORD": "...", "APPLE_KEY_ID": "ABC1234567", "APPLE_ISSUER_ID": "...", "APP_STORE_CONNECT_TEAM_ID": "TEAM123456", "CAPGO_IOS_DISTRIBUTION": "app_store" }}안드로이드 인증서 저장
안드로이드 인증서 저장완전한 예제
제목 "완전한 예제"bunx @capgo/cli@latest 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페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).
Android 옵션| Option | 옵션 | 설명 |
|---|---|---|
--keystore <path> | 필수 | keystore 또는 jks 파일의 경로 |
--keystore-alias <alias> | Keystore의 키 별칭 | Yes (release) |
--keystore-key-password <password> | 키 별칭의 비밀번호 | Yes (release) |
--keystore-store-password <password> | Keystore의 비밀번호 | Yes (release) |
--play-config <path> | Play Store 서비스 계정 JSON의 경로 | Yes (제출) |
저장되는 내용
저장되는 내용Android 인증서를 저장할 때 CLI:
- Keystore와 서비스 계정 JSON 파일을 읽습니다
- base64 인코딩으로 변환합니다.
- 파일로 저장합니다.
~/.capgo-credentials/credentials.json(또는.capgo-credentials.jsonwith--local) - 와 함께
비밀번호와 별칭을 평문으로 저장합니다 (로컬 파일만).
{ "android": { "ANDROID_KEYSTORE_FILE": "...", "PLAY_CONFIG_JSON": "...", "KEYSTORE_KEY_ALIAS": "my-key-alias", "KEYSTORE_KEY_PASSWORD": "...", "KEYSTORE_STORE_PASSWORD": "..." }}클립보드에 복사
저장된 자격 증명 사용자격 증명 저장 후 사용
# Credentials automatically loaded from ~/.capgo-credentials/credentials.jsonbunx @capgo/cli@latest build request com.example.app --platform ios환경 변수를 사용하여 저장된 자격 증명을 재정의할 수도 있습니다:
# Environment variables take precedence over saved credentialsBUILD_CERTIFICATE_BASE64="..." \P12_PASSWORD="different-password" \bunx @capgo/cli@latest build request com.example.app --platform ios우선 순위 순서:
- 환경 변수 (가장 높은 우선 순위)
- 저장된 자격 증명 (
~/.capgo-credentials/credentials.json, 또는 로컬.capgo-credentials.json) - 자격 증명이 없는 경우 (가장 낮은 우선 순위)
저장된 자격 증명 보기
저장된 자격 증명 보기 섹션저장된 자격 증명을 모두 나열합니다:
bunx @capgo/cli@latest build credentials list예시 출력:
📋 Saved Build Credentials:
iOS Credentials: ✓ Certificate (base64) ✓ Provisioning Map (JSON) ✓ Apple Key Content (base64) ✓ P12 Password: ******** ✓ Apple Key ID: ABC1234567 ✓ Apple Issuer ID: 00000000-0000-0000-0000-000000000000 ✓ Team ID: TEAM123456
Android Credentials: ✓ Keystore (base64) ✓ Play Store Config (base64) ✓ Keystore Alias: my-key-alias ✓ Key Password: ******** ✓ Store Password: ********
Location: ~/.capgo-credentials/credentials.json
🔒 These credentials are stored locally on your machine only. When building, they are sent to Capgo but NEVER stored there. They are auto-deleted after build completion.보안 최적화
보안 최적화로컬 스토리지 보안
로컬 스토리지 보안-
파일 권한
터미널 창 # Global credentials directory + filechmod 700 ~/.capgo-credentialschmod 600 ~/.capgo-credentials/credentials.json# Local (per-project) credentials, if you use --localchmod 600 .capgo-credentials.json -
인증 정보는 절대 커밋하지 마세요
터미널 창 # Ignore the per-project credentials file (used with --local)echo ".capgo-credentials.json" >> .gitignore전역 파일은 저장소 외부의 홈 디렉토리에 있습니다.
-
분리된 자격증명
- CI/CD 환경과 로컬 개발 환경에서 다른 자격증명을 사용하세요.
- 자격증명을 정기적으로轮换하세요.
- 팀원들 사이에 자격증명을 공유하지 마세요.
CI/CD 사용
CI/CD 사용CI/CD 환경에서 환경 변수를 선호하세요. 저장된 자격증명보다 환경 변수를 사용하세요. 준비된 자격증명을 내보내세요.
Export 하기 쉬운 .env (권장)
환경 변수로 export할 수 있는 .env 파일을 생성하는 방법각 자격 증명 파일을 base64로 인코딩하는 것을 수동으로 처리하는 대신 (아래 참조) below파일을 생성해 줍니다: build credentials manage 터미널 창
bunx @capgo/cli@latest build credentials manage# pick your app → choose "Export to .env"또는 .env.capgo.<appId>.<platform> 파일(권한) 0600) containing every saved credential as an environment variable — each line is one secret to add to your CI/CD provider. Both platforms are combined by default; add --platform ios or --platform android scope을 한 가지로 제한하세요.
환경 변수 전체 참조
제목 "환경 변수 전체 참조"CLI는 다음 환경 변수를 읽어 인증 정보로 사용합니다:
iOS 인증 정보:
| 변수 | 설명 | 형식 | 필수 |
|---|---|---|---|
BUILD_CERTIFICATE_BASE64 | code 인증서에 대한 P12/PKCS12 인증서 | Base64 | 예 (릴리즈) |
CAPGO_IOS_PROVISIONING_MAP | 앱 스토어 연결 __CAPGO_KEEP_0__ 프로파일 데이터를 위한 번들 ID 맵 | JSON 문자열 | 예 (릴리즈) |
P12_PASSWORD | __CAPGO_KEEP_0__ 인증서의 암호 | 평문 | 선택 |
APPLE_KEY_ID | API 키 ID (앱 스토어 연결) | 문자열 (예: "ABC1234567") | 참고 사항¹ |
APPLE_ISSUER_ID | 애플리케이션 스토어 연결 API 발급자 ID | UUID 문자열 | 참고 사항¹ |
APPLE_KEY_CONTENT | 애플리케이션 스토어 연결 API 키 (.p8 파일 내용) | Base64 | 참고 사항¹ |
APP_STORE_CONNECT_TEAM_ID | 애플리케이션 개발자 팀 ID | 문자열 (예: "XXXXXXXXXX") | 네 |
CAPGO_IOS_DISTRIBUTION | 배포 모드: app_store (기본값) 또는 ad_hoc | 문자열 | 없음 |
안드로이드 인증서:
| 변수 | 설명 | 형식 | 필수 |
|---|---|---|---|
ANDROID_KEYSTORE_FILE | APK/AAB을 위한 키스토어 파일 | Base64 | Yes (릴리즈) |
KEYSTORE_KEY_ALIAS | 키스토어 내의 키 별칭 | 문자열 | 예 (릴리즈) |
KEYSTORE_KEY_PASSWORD | 키 별칭의 비밀번호 | 평문 | 예* |
KEYSTORE_STORE_PASSWORD | keystore 파일의 비밀번호 | 평문 | 예* |
PLAY_CONFIG_JSON | Google Play 서비스 계정 JSON | Base64 | 예 (제출) |
*만 비밀번호 하나만 제공하면 두 개 모두 사용됩니다. KEYSTORE_KEY_PASSWORD 그리고 KEYSTORE_STORE_PASSWORD.
GitHub 액션 예시
GitHub Actions 예시name: Cloud Build
on: push: branches: [main]
jobs: build-ios: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: oven-sh/setup-bun@v2 - run: bun install - run: bunx @capgo/cli@latest build request com.example.app --platform ios env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }} CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }} P12_PASSWORD: ${{ secrets.P12_PASSWORD }} APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }} APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }} APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }} APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
build-android: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: oven-sh/setup-bun@v2 - run: bun install - run: bunx @capgo/cli@latest build request com.example.app --platform android env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }} KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }} KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }} KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }} PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}기본 Base64 값 준비
__CAPGO_KEEP_0__ Actions 예시 제목기본 Base64 값 준비 제목
# iOS Certificate (.p12)base64 -i certificate.p12 | tr -d '\n' > certificate_base64.txt
# iOS Provisioning Profiles — use the CLI to generate CAPGO_IOS_PROVISIONING_MAP:bunx @capgo/cli@latest build credentials save --platform ios \ --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \ # ... other options# Then copy CAPGO_IOS_PROVISIONING_MAP from ~/.capgo-credentials/credentials.json to your CI secrets
# iOS App Store Connect Key (.p8)base64 -i AuthKey_XXXXXX.p8 | tr -d '\n' > apple_key_base64.txt
# Android Keystore (.keystore or .jks)base64 -i release.keystore | tr -d '\n' > keystore_base64.txt
# Google Play Service Account JSONbase64 -i play-store-service-account.json | tr -d '\n' > play_config_base64.txt환경 변수가 왜 더 안전한가요?
환경 변수가 왜 더 안전한가요?라는 섹션This approach는 더 안전합니다.
- 비밀은 CI/CD 플랫폼에 의해 관리됩니다.
- 실행자에 credential 파일이 없습니다.
- 비밀을 쉽게轮换하고 접근 제어를 할 수 있습니다.
- 비밀 사용 기록을 남깁니다.
비밀轮换
비밀轮换라는 섹션정기적으로 비밀을轮환하세요.
- iOS: 연간 새로운 인증서 및 API 키를 생성하세요.
- 안드로이드: 연간 키 스토어 비밀번호를 변경하세요.
- 팀 구성 변경 후: 팀 구성원 이탈 시 회전하세요.
저장된 인증서를 업데이트하세요:
# Re-run save command with new credentialsbunx @capgo/cli@latest build credentials save --platform ios --certificate ./new-cert.p12 ...Troubleshooting
문제 해결페이지/영역: 지원 / 프리미엄 지원 페이지 또는 푸터 지원 섹션. 역할: 섹션 또는 페이지 제목. 표시되는 곳: page support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (Support Policy Troubleshooting Title).
문제 해결 섹션입니다.만들기에서 인증 정보가 발견되지 않았다고 말한다면:
-
인증 정보가 저장되어 있는지 확인하세요:
터미널 창 bunx @capgo/cli@latest build credentials list -
페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).:
터미널 창 bunx @capgo/cli@latest build credentials save --platform ios ... -
인증 정보가 누락된 경우 인증 정보를 저장하세요:
터미널 창 ls -la ~/.capgo-credentials/credentials.json # globalls -la .capgo-credentials.json # local (--local)
인증 정보 파일이 존재하는지 확인하세요
인증 정보를 읽을 때권한 설정을 수정하세요:
chmod 600 ~/.capgo-credentials/credentials.json # globalchmod 600 .capgo-credentials.json # local인증 정보가 사용되지 않습니다
인증 정보가 사용되지 않는다정확한 플랫폼이 지정되었는지 확인하세요:
# Make sure --platform matches saved credentialsbunx @capgo/cli@latest build request com.example.app --platform ios # Uses ios credentialsbunx @capgo/cli@latest build request com.example.app --platform android # Uses android credentials인증 정보를 삭제하고 다시 저장하세요
인증 정보가 손상된 것처럼 보인다면:권한 설정을 수정하세요:
# Clear all credentialsbunx @capgo/cli@latest build credentials clear
# Save againbunx @capgo/cli@latest build credentials save --platform ios ...환경 변수에서 마이그레이션
환경 변수에서 마이그레이션현재 환경 변수를 사용 중이라면 저장된 자격 증명을 사용할 수 있습니다.
-
현재 환경 변수를 추출하세요
터미널 창 echo $BUILD_CERTIFICATE_BASE64 # Verify they exist -
base64 파일을 원본 파일로 디코딩하세요 (필요한 경우) (필요한 경우)
터미널 창 echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision -
저장(CLI)
터미널 창 bunx @capgo/cli@latest build credentials save \--platform ios \--certificate ./cert.p12 \--ios-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"기존의 오래된 형식으로 저장된 인증 정보가 있다면 (단일
BUILD_PROVISION_PROFILE_BASE64이 명령어를 실행하세요.터미널 창 bunx @capgo/cli@latest build credentials migrate --platform ios이 명령어는 레거시 단일 프로파일을 프로파일
CAPGO_IOS_PROVISIONING_MAP과 변환하고 오래된BUILD_PROVISION_PROFILE_BASE64과APPLE_PROFILE_NAMEkeys. -
빌드 테스트
터미널 창 bunx @capgo/cli@latest build request com.example.app --platform ios -
환경 변수 제거 (선택 사항)
터미널 창 unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64
파일 위치
파일 위치 섹션인증 정보는 단일 JSON 파일에 저장됩니다:
- 전역 (기본값):
~/.capgo-credentials/credentials.json— 모든 프로젝트에 걸쳐 공유됩니다 - 로컬 (with)
--local):.capgo-credentials.json프로젝트 루트 폴더 — 프로젝트별로 전역 파일을 덮어씁니다.
파일은 처음으로 인증 정보를 저장할 때 자동으로 생성됩니다. 인증 정보를 추가하세요. .capgo-credentials.json 프로젝트에 .gitignore 이러한 프로젝트별 인증 정보는 절대 커밋되지 않습니다.
다음 단계
다음 단계- 시작하기 - 첫 번째 빌드를 생성하세요.
- iOS 빌드 - iOS 전용 빌드 설정
- Android 빌드 - 안드로이드 전용 빌드 설정
- 문제 해결 페이지/영역: 지원 / 프리미엄 지원 페이지 또는 footer 지원 섹션. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (지원 정책 문제 해결 제목)
- 일반적인 문제와 해결책
도움이 필요하세요?- 📚 ‘도움이 필요하세요?’라는 섹션
- 💬 문제 해결 가이드
- 디스코드 커뮤니티 support@capgo.app
support@__CAPGO_KEEP_0__.app
관리 인증서에서 계속 진행관리 인증서에서 계속 진행 관리 인증서 CI/CD 자동화 계획을 위해 연결하세요. Capgo CI/CD 제품 워크플로우에서 Capgo CI/CD를 사용하세요. Capgo 네이티브 빌드 제품 워크플로우에서 Capgo 네이티브 빌드를 사용하세요. Capgo 통합 제품 워크플로우에서 Capgo 통합을 사용하세요. CI/CD 통합 CI/CD 통합 GitHub 액션 통합 GitHub 액션 통합