내용으로 건너뛰기

인증 관리

Overview

Capgo CLI stores your build credentials — __CAPGO_KEEP_0__ 서버에 저장하지 않습니다. 기본적으로 모든 프로젝트에 공유되는 하나의 — never on Capgo’s servers. By default they live in one 파일에 저장됩니다. 전역 ~/.capgo-credentials/credentials.json, 모든 프로젝트에 공유되는 하나의 --local 파일에 저장됩니다. Pass 프로젝트별 에서 .capgo-credentials.json 대신. 빌드를 실행할 때 저장된 인증 정보가 자동으로 사용되고 Capgo로 안전하게 전송되고 빌드가 완료되면 삭제됩니다.

저장된 인증서를 관리하는 가장 빠른 방법은 인터랙티브 매니저입니다. 이 매니저는 TUI(터미널 사용자 인터페이스)를 열어 저장된 항목을浏览하고 앱 및 플랫폼별로 구성된 항목을 확인하고 CI/CD 준비된 파일을 내보내거나 플랫폼의 인증서를 삭제할 수 있습니다.

인증서 관리

인증서 관리 섹션 build init 저장된 인증서를 관리하는 가장 빠른 방법은 인터랙티브 매니저입니다. 이 매니저는 TUI(터미널 사용자 인터페이스)를 열어 저장된 항목을浏览하고 앱 및 플랫폼별로 구성된 항목을 확인하고 CI/CD 준비된 파일을 내보내거나 플랫폼의 인증서를 삭제할 수 있습니다. .env 터미널 창

클립보드에 복사
bunx @capgo/cli@latest build credentials manage
옵션설명
--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]

그 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 하지만 모든 옵션은 선택 사항이며, 제공한 field만 업데이트됩니다.

인증서 목록

인증서 목록 섹션

현재 저장된 인증서(비밀번호는 가려져 있습니다)를 보려면:

터미널 창
bunx @capgo/cli@latest build credentials list
# List credentials for a specific app
bunx @capgo/cli@latest build credentials list --appId com.example.app

인증서 지우기

인증서 지우기 섹션

저장된 인증서를 로컬 머신에서 삭제하려면:

터미널 창
# Clear all credentials
bunx @capgo/cli@latest build credentials clear
# Clear credentials for a specific app + platform
bunx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios

Migrate Credentials

Migrate Credentials 섹션

기존 단일 프로파일 형식에서 새로운 다중 대상 형식으로 변환:

터미널 창
bunx @capgo/cli@latest build credentials migrate --platform ios

이전 BUILD_PROVISION_PROFILE_BASE64 인증서를 변환하고 legacy 키를 제거합니다. CAPGO_IOS_PROVISIONING_MAPSee Single Profile에서 마이그레이션 iOS 인증서 저장

iOS 인증서 저장 섹션

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"
설정설명필수
--certificate <path>__CAPGO_KEEP_0__ 인증서 파일 경로예 (릴리즈)
--p12-password <password>__CAPGO_KEEP_0__ 인증서 파일의 암호예 (릴리즈)
--ios-provisioning-profile <mapping>__CAPGO_KEEP_0__ 프로비전 프로파일 매핑 (bundleId=path ) 반복 가능. 여러 대상 앱을 위한 프로파일이 여러 개일 경우. 단일 프로파일이 있고 CLI bundleId 접두어가 없으면 CLI auto-infers from the profile.예 (릴리즈)
--apple-key <path>API App Store Connect API .p8 키 경로참고 ¹
--apple-key-id <id>애플 스토어 연결 API 키 ID참고사항 1을 참조하십시오
--apple-issuer-id <id>애플 스토어 연결 API 발급자 ID (UUID)참고사항 1을 참조하십시오
--apple-team-id <id>애플 스토어 연결 팀 ID예
--apple-id <email>애플 ID 이메일 (앱별 암호 업로드 대체 옵션, API 키)참고사항 2를 참조하십시오
--apple-app-specific-password <password>애플 스토어 연결 앱별 암호xxxx-xxxx-xxxx-xxxx)참고사항 2를 참조하십시오
--apple-app-id <id>숫자 애플 스토어 연결 앱 ID (예: 1234567890)참고사항 2를 참조하십시오
--ios-distribution <mode>Distribution mode: app_store (기본값) 또는 ad_hocNo
--output-upload빌드 아티팩트에 대한 시간 제한 Capgo 다운로드 링크를 활성화합니다.No (기본값: false)
--output-retention <seconds>빌드 출력을 유지하는 기간 (예: 3600s)No (기본값: 3600s)
--skip-build-number-bump자동 빌드 번호 증가를 생략합니다.No

iOS 인증서를 저장할 때 CLI:

  1. 인증서와 배포 프로파일 파일을 읽습니다.
  2. base64 인코딩으로 변환합니다.
  3. Android 인증서를 저장합니다. ~/.capgo-credentials/credentials.json 또는 .capgo-credentials.json 와 --local)
  4. 비밀번호와 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"
}
}

Android 인증서 저장

제목 "Android 인증서 저장"
터미널 창
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 또는 jks 파일의 경로Yes (release)
--keystore-alias <alias>키 저장소의 별칭Yes (release)
--keystore-key-password <password>키 별칭의 비밀번호Yes (release)
--keystore-store-password <password>키 저장소의 비밀번호Yes (release)
--play-config <path>Play Store 서비스 계정 JSON 파일의 경로Yes (submission)

Android 인증서를 저장할 때 저장되는 내용은 CLI:

  1. 키 스토어와 서비스 계정 JSON 파일을 읽습니다.
  2. base64 인코딩으로 변환합니다.
  3. 그것들을 저장합니다. ~/.capgo-credentials/credentials.json (또는) .capgo-credentials.json with --local)
  4. 비밀번호와 별칭을 평문으로 저장합니다 (로컬 파일만)

저장된 파일 구조:

{
"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.json
bunx @capgo/cli@latest build request com.example.app --platform ios

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

터미널 창
# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
bunx @capgo/cli@latest build request com.example.app --platform ios

우선 순위 순서:

  1. 환경 변수 (가장 높은 우선 순위)
  2. 저장된 자격 증명 (~/.capgo-credentials/credentials.json, 또는 로컬 .capgo-credentials.json)
  3. 자격 증명이 없는 (가장 낮은 우선 순위)

저장된 자격 증명 목록을 표시합니다:

터미널 창
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.

보안 최선의 방법

보안 최선의 방법 섹션

로컬 스토리지 보안

로컬 스토리지 보안 섹션
  1. 파일 권한

    터미널 창
    # Global credentials directory + file
    chmod 700 ~/.capgo-credentials
    chmod 600 ~/.capgo-credentials/credentials.json
    # Local (per-project) credentials, if you use --local
    chmod 600 .capgo-credentials.json
  2. 보안 자격 증명 절대 커밋하지 마세요

    터미널 창
    # Ignore the per-project credentials file (used with --local)
    echo ".capgo-credentials.json" >> .gitignore

    전역 파일은 홈 디렉토리 내에 저장되며, 저장소 외부에 위치합니다.

  3. 분리된 자격 증명

    • CI/CD 환경과 로컬 개발 환경에서 서로 다른 자격 증명을 사용합니다.
    • 정기적으로 자격 증명을 회전합니다.
    • 팀원들 사이에 자격 증명을 공유하지 마세요.

CI/CD 사용

CI/CD 사용

CI/CD 환경에서 환경 변수를 선호하는 것이 좋습니다. 저장된 자격 증명보다. CI/CD 환경에서 환경 변수를 선호하는 것이 좋습니다.

__CAPGO_KEEP_2__

__CAPGO_KEEP_3__ __CAPGO_KEEP_4____CAPGO_KEEP_5__ build credentials manage __CAPGO_KEEP_6__

__CAPGO_KEEP_7__
bunx @capgo/cli@latest build credentials manage
# pick your app → choose "Export to .env"

__CAPGO_KEEP_9__ .env.capgo.<appId>.<platform> __CAPGO_KEEP_10__ 0600__CAPGO_KEEP_11__ --platform ios 또는 --platform android 한 가지로 제한

절대 커밋하지 마세요.

환경 변수 전체 참조

The CLI reads the following environment variables for credentials:

__CAPGO_KEEP_0__는 다음 환경 변수를 읽어 인증 정보를 읽습니다:

iOS 인증 정보:변수명형식필수
BUILD_CERTIFICATE_BASE64code 서명에 사용되는 P12/PKCS12 인증서Base64Yes (release)
CAPGO_IOS_PROVISIONING_MAP앱 번들 ID를 키로 하는 프로비전 프로파일 데이터의 JSON 맵JSON 문자열Yes (release)
P12_PASSWORDP12 인증서의 비밀번호평문선택
APPLE_KEY_IDAPI 키 ID문자열 (예: "ABC1234567")참고 1을 참조하십시오
APPLE_ISSUER_IDApp Store Connect API 발급자 IDUUID 문자열참고 1을 참조하십시오
APPLE_KEY_CONTENTApp Store Connect API 키 (.p8 파일 내용)Base64참고 1을 참조하십시오
APP_STORE_CONNECT_TEAM_ID애플 개발자 팀 ID문자열 (예: "XXXXXXXXXX")예
CAPGO_IOS_DISTRIBUTION배포 모드: app_store (기본) 또는 ad_hoc문자열아니오

안드로이드 인증 정보:

변수설명형식필수
ANDROID_KEYSTORE_FILEAPK/AAB을 위한 키스토어 파일Base64예 (릴리즈)
KEYSTORE_KEY_ALIAS키스토어 내의 키 별칭문자열Yes (release)
KEYSTORE_KEY_PASSWORD키 별칭의 비밀번호평문Yes*
KEYSTORE_STORE_PASSWORDkeystore 파일의 비밀번호평문Yes*
PLAY_CONFIG_JSONGoogle Play 서비스 계정 JSONBase64Yes (submission)

*만 비밀번호 하나만 제공하면 두 개 모두 사용됩니다. KEYSTORE_KEY_PASSWORD 및 KEYSTORE_STORE_PASSWORD.

GitHub Actions Example

GitHub Actions 예시
github/workflows/build.yml
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 }}

터미널 창

클립보드에 복사
# 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 JSON
base64 -i play-store-service-account.json | tr -d '\n' > play_config_base64.txt

보안이 더 뛰어난 환경 변수의 이유

보안이 더 뛰어난 환경 변수의 이유

이 방법은 더 안전합니다.

  • Secrets는 CI/CD 플랫폼에서 관리됩니다.
  • 실행자에 credential 파일이 없습니다.
  • 쉽게 rotation 및 access control
  • secret 사용에 대한 감사 기록

인증서의 rotation

  1. iOS: 연간 새로운 인증서와 API 키를 생성하세요.
  2. Android: 연간 키 스토어 비밀번호를 변경하세요.
  3. 팀 구성원 변경 후: 팀 구성원이 떠날 때 rotate

저장된 인증서를 업데이트하세요:

터미널 창
# Re-run save command with new credentials
bunx @capgo/cli@latest build credentials save --platform ios --certificate ./new-cert.p12 ...

만약 빌드가 인증 정보가 없다고 말한다면:

  1. 인증 정보가 저장되어 있는지 확인하세요:

    터미널 창
    bunx @capgo/cli@latest build credentials list
  2. 인증 정보가 없으면 저장하세요:

    터미널 창
    bunx @capgo/cli@latest build credentials save --platform ios ...
  3. 인증 정보 파일이 존재하는지 확인하세요:

    터미널 창
    ls -la ~/.capgo-credentials/credentials.json # global
    ls -la .capgo-credentials.json # local (--local)

인증 정보를 읽을 때 “권한이 거부됨”

권한이 거부된 경우 인증서를 읽을 때

파일 권한을 수정하세요:

터미널 창
chmod 600 ~/.capgo-credentials/credentials.json # global
chmod 600 .capgo-credentials.json # local

인증서가 사용되지 않는다

인증서가 사용되지 않는다

정확한 플랫폼이 지정되었는지 확인하세요:

터미널 창
# Make sure --platform matches saved credentials
bunx @capgo/cli@latest build request com.example.app --platform ios # Uses ios credentials
bunx @capgo/cli@latest build request com.example.app --platform android # Uses android credentials

인증서를 삭제하고 다시 저장하세요

인증서가 손상된 것처럼 보인다면:

인증서를 삭제하고 다시 저장하세요

터미널 창
# Clear all credentials
bunx @capgo/cli@latest build credentials clear
# Save again
bunx @capgo/cli@latest build credentials save --platform ios ...

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

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

현재 환경 변수를 사용 중이라면 저장된 자격 증명을 사용할 수 있습니다:

  1. 현재 환경 변수를 추출하세요

    터미널 창
    echo $BUILD_CERTIFICATE_BASE64 # Verify they exist
  2. base64 파일을 원본 파일로 디코딩하세요 (필요한 경우) 터미널 창

    클립보드에 복사
    echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
    echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision
  3. 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 and APPLE_PROFILE_NAME 인증

  4. 테스트 빌드

    터미널 창
    bunx @capgo/cli@latest build request com.example.app --platform ios
  5. 환경 변수 삭제 (선택 사항)

    터미널 창
    unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

인증 정보는 단일 JSON 파일에 저장됩니다:

  • 전역 (기본값): ~/.capgo-credentials/credentials.json 모든 프로젝트에 공유됩니다
  • Local (with --local): .capgo-credentials.json 프로젝트 루트 내에 — 해당 프로젝트에 대한 전역 파일을 덮어씁니다

The file is created automatically the first time you save credentials. Add .capgo-credentials.json 프로젝트에 .gitignore 로

Next Steps

다음 단계

도움이 필요합니다.

도움이 필요합니다.

관리 인증서에서 계속

관리 인증서에서 계속

CI/CD 자동화에 사용 중인 경우 인증 관리 CI/CD 자동화를 계획하고 구축하려면 Capgo CI/CD Capgo CI/CD에서 제품 워크플로우 Capgo Native Builds Capgo Native Builds에서 제품 워크플로우 Capgo Integrations Capgo Integrations에서 제품 워크플로우 CI/CD 통합 CI/CD 통합 구현 세부 사항 GitHub Actions Integration Capgo GitHub Actions Integration.