인증 정보 관리
설치 단계와 이 플러그인의 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
iOS 및 Android 빌드 인증서를 로컬로 관리하여 편리한 클라우드 빌드를 관리하세요.
Overview
'Overview'라는 제목의 섹션Capgo CLI에서 빌드 인증서를 저장합니다. 컴퓨터에 저장 — Capgo의 서버에 저장하지 않습니다. 기본적으로 모든 프로젝트에 공유되는 하나의 전역 파일에서 저장됩니다. ~/.capgo-credentials/credentials.json프로젝트별로 저장 --local 을 유지하기 위해 __CAPGO_KEEP_0__를 전달하세요. __CAPGO_KEEP_1__ .capgo-credentials.json Capgo
명령어
명령어인증 정보를 직접 관리
인증 정보를 직접 관리저장된 인증 정보를 작업하기 위해 가장 빠른 방법은 인터랙티브 매니저입니다. 인터랙티브 매니저는 TUI(터미널 사용자 인터페이스)를 열어 저장된 것들을浏览할 수 있고, 앱 및 플랫폼에 대한 설정을 확인할 수 있으며, CI/CD에 적합한 파일을 내보내거나 플랫폼의 인증 정보를 삭제할 수 있습니다. build init 터미널 창 .env 클립보드에 복사
bunx @capgo/cli@latest build credentials manage| Option | Description |
|---|---|
--appId <appId> | 앱을 관리하세요 (생략 시 선택하도록 유도합니다) |
--platform <ios|android> | 플랫폼을 관리하세요 (생략 시 선택하도록 유도합니다) |
--local | 프로젝트별로 사용하세요 .capgo-credentials.json global 파일 대신 |
한 번에 실행할 수 있는 스크립트를 선호하세요? 아래의 개별 명령어를 사용하세요.
인증서버
인증서버 저장자동 사용을 위해 로컬에 빌드 인증서를 저장하세요:
bunx @capgo/cli@latest build credentials save --platform <ios|android> [options]인증서버 업데이트
인증서버 업데이트__CAPGO_KEEP_0__:
bunx @capgo/cli@latest build credentials update --platform <ios|android> [options]The update __CAPGO_KEEP_1__ existing credentials을 업데이트하기 위해 예시 — 기존 인증서에 확장 프로파일을 추가하는 경우: --overwrite-ios-provisioning-map.
__CAPGO_KEEP_0__
bunx @capgo/cli@latest build credentials update \ --platform ios \ --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"but all are optional — only the fields you provide are updated. save CLI 명령어는
List Credentials
List Credentials현재 저장된 자격 증명 보기 (암호는 가려져 있습니다):
bunx @capgo/cli@latest build credentials list
# List credentials for a specific appbunx @capgo/cli@latest build credentials list --appId com.example.appClear Credentials
Clear Credentials저장된 자격 증명 제거:
# 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자격 증명 이동하기
자격 증명 이동하기__CAPGO_KEEP_0__을 새로운 다중 목표 형식으로 변환합니다.
bunx @capgo/cli@latest build credentials migrate --platform ios__CAPGO_KEEP_0__ 명령은 오래된 BUILD_PROVISION_PROFILE_BASE64 __CAPGO_KEEP_0__, 이를 __CAPGO_KEEP_1__으로 변환하고, 레거시 키를 제거합니다. 자세한 내용은 CAPGO_IOS_PROVISIONING_MAP__CAPGO_KEEP_0__에서 단일 프로파일을 다중 목표로 마이그레이션하는 방법 을 참조하세요. iOS 인증서 저장
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__예제 완성
예제 완성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 옵션| 옵션 | 설명 | 필수 |
|---|---|---|
--certificate <path> | __CAPGO_KEEP_0__ 인증서 파일 경로 | 예 (릴리즈) |
--p12-password <password> | __CAPGO_KEEP_0__ 인증서 파일의 암호 | 예 (릴리즈) |
--ios-provisioning-profile <mapping> | __CAPGO_KEEP_0__ 프로비전 프로파일 매핑 (, ) 반복 가능. 여러 대상 앱에 대한 경우. 단일 프로파일만 있고 __CAPGO_KEEP_0__ bundleId 접두어가 없는 경우, __CAPGO_KEEP_0__는 프로파일에서 자동으로 추론합니다.bundleId=path). Repeatable for multi-target apps. If only one profile and no bundleId prefix, CLI auto-infers from the profile. | __CAPGO_KEEP_0__ App Store Connect .p8 키 경로 |
--apple-key <path> | Path to App Store Connect API .p8 key | __CAPGO_KEEP_0__ App Store Connect 키 ID |
--apple-key-id <id> | App Store Connect API Key ID | __CAPGO_KEEP_0__ |
--apple-issuer-id <id> | App Store Connect API 발급자 ID (UUID) | See note¹ |
--apple-team-id <id> | App Store Connect 팀 ID | Yes |
--apple-id <email> | 애플 ID 이메일 (앱별 암호 업로드 대체로 API 키 사용) | See note² |
--apple-app-specific-password <password> | 앱별 암호 (xxxx-xxxx-xxxx-xxxx) | See note² |
--apple-app-id <id> | 숫자 App Store Connect 앱 ID (예 1234567890) | See note² |
--ios-distribution <mode> | 배포 모드: app_store (기본값) 또는 ad_hoc | No |
--output-upload | Capgo 다운로드 링크를 시간 제한으로 설정하여 빌드 아티팩트를 활성화하세요. | No (기본값: false) |
--output-retention <seconds> | 빌드 출력을 유지하는 기간 (예: 3600s) | No (기본값: 3600s) |
--skip-build-number-bump | 자동 빌드 번호 증가를 생략합니다. | No |
저장된 iOS 인증서 정보
인증서와 배포 프로파일 파일을 읽습니다.When you save iOS credentials, the CLI:
- 저장합니다.
- 또는
- Section titled “What Gets Stored”
~/.capgo-credentials/credentials.jsonWhen you save iOS credentials, the __CAPGO_KEEP_0__:.capgo-credentials.json__CAPGO_KEEP_0__--local) - __CAPGO_KEEP_0__
__CAPGO_KEEP_1__
{ "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" }}__CAPGO_KEEP_3__
__CAPGO_KEEP_4__완전한 예제
완전한 예제 섹션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안드로이드 옵션
안드로이드 옵션 섹션| 옵션 | 설명 | 필수 |
|---|---|---|
--keystore <path> | keystore(.keystore 또는 .jks) 파일 경로 | Yes (release) |
--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 (submission) |
저장되는 내용
저장되는 내용Android 인증서를 저장할 때 CLI:
- keystore 및 서비스 계정 JSON 파일을 읽어 base64 인코딩으로 변환합니다.
- keystore 및 서비스 계정 JSON 파일을 읽어 base64 인코딩으로 변환합니다.
- 저장합니다.
~/.capgo-credentials/credentials.json(또는.capgo-credentials.json와--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) - 인증 정보가 없는 경우 (가장 낮은 우선 순위)
저장된 자격 증명을 보는 중
Section titled “저장된 자격 증명을 보는 중”저장된 자격 증명 목록:
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 환경에서 환경 변수를 저장된 자격증명보다 선호합니다. 준비된 사용 가능한
(권장) .env (recommended)
Export 하기 쉬운 .env (권장) 섹션 제목수동으로 각 자격 증명 파일을 base64로 인코딩하는 대신 (아래 참조), 파일을 생성해 주세요:터미널 창 build credentials manage 복사
bunx @capgo/cli@latest build credentials manage# pick your app → choose "Export to .env"또는 .env.capgo.<appId>.<platform> 을 추가하세요. 0600터미널 창 --platform ios 복사 --platform android CI/CD 제공자에 추가할 비밀을 포함하는 파일 (권한
환경 변수 전체 참조
환경 변수 전체 참조CLI는 다음 환경 변수를 읽어 인증 정보로 사용합니다.
iOS 인증 정보:
| 변수 | 설명 | 형식 | 필수 |
|---|---|---|---|
BUILD_CERTIFICATE_BASE64 | P12/PKCS12 인증서를 위한 code 서명 | Base64 | 예 (릴리즈) |
CAPGO_IOS_PROVISIONING_MAP | __CAPGO_KEEP_0__ 번들 ID를 위한 프로비전 프로파일 데이터의 JSON 맵 | JSON 문자열 | 예 (릴리즈) |
P12_PASSWORD | __CAPGO_KEEP_0__ P12 인증서의 비밀번호 | 평문 | 선택 |
APPLE_KEY_ID | 애플 스토어 연결 API 키 ID | 문자열 (예: "ABC1234567") | 참고 ¹을 참조하십시오 |
APPLE_ISSUER_ID | App Store Connect API 발급자 ID | UUID 문자열 | 참고사항 ¹ |
APPLE_KEY_CONTENT | App Store Connect API 키 (.p8 파일 내용) | Base64 | 참고사항 ¹ |
APP_STORE_CONNECT_TEAM_ID | Apple 개발자 팀 ID | 문자열 (예: “XXXXXXXXXX”) | 예 |
CAPGO_IOS_DISTRIBUTION | 배포 모드: app_store (기본값) 또는 ad_hoc | 문자열 | No |
안드로이드 인증 정보:
| 변수 | 설명 | 형식 | 필수 |
|---|---|---|---|
ANDROID_KEYSTORE_FILE | APK/AAB을 위한 서명 키스토어 파일 | Base64 | Yes (release) |
KEYSTORE_KEY_ALIAS | 키스토어 내의 키 별칭 | 문자열 | Yes (release) |
KEYSTORE_KEY_PASSWORD | __CAPGO_KEEP_0__ 키 별칭의 비밀번호 | 평문 | Yes* |
KEYSTORE_STORE_PASSWORD | __CAPGO_KEEP_0__ 키 스토어 파일의 비밀번호 | 평문 | Yes* |
PLAY_CONFIG_JSON | Google Play 서비스 계정 JSON | Base64 | Yes (submission) |
*만 비밀번호 하나가 제공되면, 두 개 모두에 사용됩니다. KEYSTORE_KEY_PASSWORD 그리고 KEYSTORE_STORE_PASSWORD.
GitHub 액션 예시
GitHub 액션 예제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 }}CI/CD 비밀을 위해 Base64로 변환하는 방법
CI/CD 비밀을 위해 Base64로 변환하는 방법인증 파일을 Base64로 변환하여 CI/CD 비밀을 만드는 방법:
# 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환경 변수는 왜 더 안전한가
환경 변수는 왜 더 안전한가이 접근 방식은 더 안전합니다.
- CI/CD 플랫폼에서 비밀을 관리합니다.
- 실행자에 credential 파일이 없습니다.
- 비밀을 쉽게轮换하고 접근 제어를 합니다.
- 비밀 사용 기록을 남깁니다.
비밀轮换
비밀轮换정기적으로 비밀을轮환하세요.
- iOSAPI
- 안드로이드1년마다 키 스토어 비밀번호를 변경하세요
- 팀 구성원 변경 후팀 구성원이 떠날 때 키 스토어를 회전하세요
저장된 자격 증명 업데이트:
# Re-run save command with new credentialsbunx @capgo/cli@latest build credentials save --platform ios --certificate ./new-cert.p12 ...문제 해결
'문제 해결' 섹션'자격 증명이 없습니다'
'자격 증명이 없습니다' 섹션빌드가 자격 증명이 없다고 말할 때:
-
인증 정보가 저장되어 있는지 확인합니다.:
터미널 창 bunx @capgo/cli@latest build credentials list -
인증 정보가 없으면 저장:
터미널 창 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 ...__CAPGO_KEEP_0__
환경 변수에서 이주하기현재 환경 변수를 사용 중이라면 저장된 자격 증명을 사용할 수 있습니다.
-
현재 환경 변수를 추출하세요
터미널 창 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_NAME키를 삭제합니다. -
빌드 테스트
터미널 창 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 빌드 - Android 전용 빌드 구성
- 문제 해결 - 일반적인 문제와 해결 방법
도움이 필요하세요?
제목이 "도움이 필요하세요?"인 섹션- 📚 문제 해결 가이드
- 💬 디스코드 커뮤니티
- 📧 이메일: support@capgo.app
관리 인증서에서 계속
제목이 "관리 인증서에서 계속"인 섹션관리 인증서를 사용 중이라면 관리 인증서 CI/CD 자동화 계획을 수립하기 위해 연결하세요. Capgo CI/CD Capgo CI/CD에서 제품 워크플로우를 위해 Capgo 네이티브 빌드 Capgo 네이티브 빌드에서 제품 워크플로우를 위해 Capgo 통합 Capgo 통합에서 제품 워크플로우를 위해 CI/CD 통합 CI/CD 통합 구현 세부 사항에 대해 GitHub 액션 통합 GitHub 액션 통합 구현 세부 사항에 대해