자격 증명 관리

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

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

개요

Capgo CLI는 빌드 인증 정보를 로컬 머신에 저장합니다 — Capgo 서버에는 절대 저장되지 않습니다. 기본적으로 인증 정보는 하나의 글로벌 파일에 ~/.capgo-credentials/credentials.json저장되어 모든 프로젝트에서 공유됩니다. 대신 --local 를 사용하여 프로젝트별로 에서 .capgo-credentials.json 관리할 수 있습니다. 빌드를 실행하면 저장된 인증 정보가 자동으로 사용되어 Capgo로 안전하게 전송되며, 빌드가 완료되면 즉시 삭제됩니다.

명령어

대화형으로 자격 증명 관리

저장된 자격 증명을 관리하는 가장 빠른 방법은 인터랙티브 매니저를 사용하는 것입니다. 이 매니저는 기존과 동일한 TUI를 실행하여, build init 저장된 항목을 탐색하고, 앱 및 플랫폼별 설정 상태를 확인하거나, CI/CD용 파일을 내보내고, .env 특정 플랫폼의 자격 증명을 삭제할 수 있습니다:

bunx @capgo/cli@latest build credentials manage

옵션	설명
`--appId <appId>`	관리할 App (생략 시 선택 프롬프트 표시)
`--platform <ios\|android>`	관리할 Platform (생략 시 프롬프트 표시)
`--local`	프로젝트별 설정을 사용하려면 `.capgo-credentials.json` 글로벌 파일 대신

한 번에 실행 가능한 스크립트 방식의 명령어를 선호하시나요? 아래 개별 명령어를 사용하세요.

자격 증명 저장

자동 사용을 위해 빌드 credentials를 로컬에 저장하세요:

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

인증 정보 업데이트

모든 정보를 다시 입력할 필요 없이 기존 credentials를 부분적으로 업데이트하세요:

bunx @capgo/cli@latest build credentials update --platform <ios|android> [options]

이 update command 사용법 추가적 병합(additive merge) provisioning profile의 경우 — 새 프로필이 기존 프로필과 병합됩니다. 전체 provisioning map을 교체하려면 다음을 추가하세요: --overwrite-ios-provisioning-map.

예시 — 기존 credentials에 extension profile 추가:

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"

update command는 다음 명령과 동일한 옵션을 지원합니다: save 단, 모든 옵션은 선택 사항입니다 — 제공한 필드만 업데이트됩니다.

인증 정보 목록

현재 저장된 credentials 확인 (비밀번호는 마스킹 처리됨):

bunx @capgo/cli@latest build credentials list

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

인증 정보 지우기

로컬 머신에 저장된 credentials를 삭제하려면:

# 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

인증 정보 마이그레이션

기존의 단일 프로필 형식을 새로운 멀티 타겟 형식으로 변환하려면:

bunx @capgo/cli@latest build credentials migrate --platform ios

migrate 명령어가 기존 BUILD_PROVISION_PROFILE_BASE64 credentials를 감지해 변환하고, 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 옵션

옵션	설명	필수
`--certificate <path>`	.p12 인증서 파일 경로	예 (release)
`--p12-password <password>`	.p12 인증서 비밀번호	예 (release)
`--ios-provisioning-profile <mapping>`	Provisioning profile 매핑 (`bundleId=path`). 멀티 타겟 앱의 경우 반복 사용 가능합니다. 프로필이 하나뿐이고 bundleId 접두사가 없다면, CLI가 프로필에서 자동으로 추론합니다.	예 (release)
`--apple-key <path>`	App Store Connect API .p8 키 경로	참고¹ 참조
`--apple-key-id <id>`	App Store Connect API Key ID	참고¹ 참조
`--apple-issuer-id <id>`	App Store Connect API Issuer ID (UUID)	참고¹ 참조
`--apple-team-id <id>`	App Store Connect Team ID	지원
`--apple-id <email>`	앱 전용 암호 업로드를 위한 Apple ID 이메일 (API 키 대체용)	참고² 확인
`--apple-app-specific-password <password>`	앱 전용 암호 (`xxxx-xxxx-xxxx-xxxx`)	참고² 확인
`--apple-app-id <id>`	App Store Connect 앱 ID 숫자 (예: `1234567890`)	참고² 확인
`--ios-distribution <mode>`	배포 모드: `app_store` (기본값) 또는 `ad_hoc`	아니요
`--output-upload`	빌드 아티팩트용 기간 한정 Capgo 다운로드 링크 활성화	아니요 (기본값: `false`)
`--output-retention <seconds>`	빌드 결과물 보관 기간 (예: `3600s`)	아니요 (기본값: `3600s`)
`--skip-build-number-bump`	빌드 번호 자동 증가 건너뛰기	아니요

저장되는 항목

iOS credentials를 저장할 때 CLI는 다음과 같이 동작합니다:

인증서 및 provisioning profile 파일을 읽어
base64 형식으로 인코딩한 후
다음 위치에 저장합니다: ~/.capgo-credentials/credentials.json (또는 .capgo-credentials.json 포함 --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"
  }
}

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

Android 옵션

옵션	설명	필수
`--keystore <path>`	.keystore 또는 .jks 파일 경로	예 (release)
`--keystore-alias <alias>`	keystore 내 Key alias	예 (release)
`--keystore-key-password <password>`	Key alias 비밀번호	예 (release)
`--keystore-store-password <password>`	Keystore 비밀번호	예 (release)
`--play-config <path>`	Play Store 서비스 계정 JSON 경로	예 (제출용)

저장되는 항목

Android 인증 정보를 저장하면 CLI가 다음 작업을 수행합니다:

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.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

우선순위:

환경 변수 (최우선 순위)
저장된 인증 정보 (~/.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 + file
chmod 700 ~/.capgo-credentials
chmod 600 ~/.capgo-credentials/credentials.json
# Local (per-project) credentials, if you use --local
chmod 600 .capgo-credentials.json

자격 증명 커밋 금지
터미널 창
```
# Ignore the per-project credentials file (used with --local)
echo ".capgo-credentials.json" >> .gitignore
```
글로벌 파일은 레포지토리 외부의 홈 디렉토리에 저장됩니다.
자격 증명 분리
- 로컬 개발과 CI/CD 환경에는 서로 다른 자격 증명을 사용하세요
- 정기적으로 자격 증명을 교체하세요
- 팀원끼리 자격 증명을 공유하지 마세요

CI/CD 활용

CI/CD 환경에서는, 저장된 자격 증명보다 환경 변수를 권장합니다.

내보내기: 즉시 사용 가능한 `.env` (권장)

각 자격 증명 파일을 직접 base64로 인코딩하는 대신 (아래 참조)), build credentials manage 파일을 대신 생성하게 하세요:

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

이 명령은 .env.capgo.<appId>.<platform> 파일(권한 0600)을 생성합니다. 이 파일에는 저장된 모든 자격 증명이 환경 변수로 들어갑니다. 각 줄은 CI/CD 제공업체에 추가할 secret 하나입니다. 기본적으로 두 플랫폼이 모두 포함되며, 특정 플랫폼만 지정하려면 --platform ios 또는 --platform android 를 추가하세요.

환경 변수 전체 레퍼런스

CLI는 인증을 위해 다음 환경 변수를 읽습니다:

iOS 인증 정보:

변수	설명	형식	필수
`BUILD_CERTIFICATE_BASE64`	code 서명용 P12/PKCS12 인증서	Base64	예 (release)
`CAPGO_IOS_PROVISIONING_MAP`	bundle ID를 provisioning profile 데이터에 매핑한 JSON map	JSON 문자열	예 (release)
`P12_PASSWORD`	P12 인증서 비밀번호	일반 텍스트	선택 사항
`APPLE_KEY_ID`	App Store Connect API Key ID	문자열 (예: “ABC1234567”)	참고¹ 참조
`APPLE_ISSUER_ID`	App Store Connect API Issuer ID	UUID 문자열	참고¹ 참조
`APPLE_KEY_CONTENT`	App Store Connect API 키 (.p8 파일 내용)	Base64	참고¹ 참조
`APP_STORE_CONNECT_TEAM_ID`	Apple Developer Team ID	문자열 (예: “XXXXXXXXXX”)	지원
`CAPGO_IOS_DISTRIBUTION`	배포 모드: `app_store` (기본값) 또는 `ad_hoc`	문자열	아니요

Android 인증 정보:

변수	설명	형식	필수
`ANDROID_KEYSTORE_FILE`	APK/AAB 서명용 Keystore 파일	Base64	예 (release)
`KEYSTORE_KEY_ALIAS`	Keystore 내 Key alias	문자열	예 (release)
`KEYSTORE_KEY_PASSWORD`	Key alias 비밀번호	일반 텍스트	예*
`KEYSTORE_STORE_PASSWORD`	keystore 파일 비밀번호	일반 텍스트	예*
`PLAY_CONFIG_JSON`	Google Play 서비스 계정 JSON	Base64	예 (제출용)

*비밀번호를 하나만 입력하면 양쪽 모두에 사용됩니다 KEYSTORE_KEY_PASSWORD 및 KEYSTORE_STORE_PASSWORD.

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 값 준비하기

CI/CD secret으로 사용할 인증 파일들을 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 JSON
base64 -i play-store-service-account.json | tr -d '\n' > play_config_base64.txt

환경 변수가 더 안전한 이유

이 방식이 더 안전한 이유는 다음과 같습니다:

Secret은 CI/CD 플랫폼에서 관리됩니다
Runner에 자격 증명 파일 없음
간편한 교체 및 액세스 제어
Secret 사용에 대한 감사 추적

자격 증명 로테이션

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

iOS: 매년 새 인증서와 API 키를 생성하세요
Android: 매년 keystore 비밀번호를 변경하세요
팀 구성원 변경 후: 팀원이 퇴사하면 교체하세요

저장된 인증 정보 업데이트:

# Re-run save command with new credentials
bunx @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   # global
ls -la .capgo-credentials.json                 # local (--local)

자격 증명 읽기 시 “Permission denied” 발생

파일 권한 수정:

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

자격 증명 지우고 다시 저장

Credentials가 손상된 것 같다면:

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

# Save again
bunx @capgo/cli@latest build credentials save --platform ios ...

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

현재 환경 변수를 사용 중이라면, 저장된 Credentials로 마이그레이션할 수 있습니다:

현재 환경 변수 추출하기

echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

base64 파일을 원본 파일로 디코딩하기 (필요한 경우)

echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
echo "$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), run:

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

파일 위치

Credentials는 하나의 JSON 파일에 저장됩니다:

Global (기본값): ~/.capgo-credentials/credentials.json — 모든 프로젝트에서 공유됨
Local ( --local): .capgo-credentials.json 프로젝트 루트에 위치 — 해당 프로젝트에 대해 global 파일을 덮어씀

Credentials를 처음 저장할 때 파일이 자동으로 생성됩니다. 추가하려면 .capgo-credentials.json …에 .gitignore 따라서 프로젝트별 인증 정보가 커밋되는 일은 없습니다.

다음 단계

시작하기 - 첫 번째 빌드 생성하기
iOS 빌드 - iOS 전용 빌드 설정
Android 빌드 - Android 전용 빌드 설정
문제 해결 - 주요 문제 및 해결 방법

도움이 필요하신가요?

인증 관리에서 이어서 진행하기

사용 중이라면 자격 증명 관리 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.

자격 증명 관리

개요

명령어

대화형으로 자격 증명 관리

자격 증명 저장

인증 정보 업데이트

인증 정보 목록

인증 정보 지우기

인증 정보 마이그레이션

iOS 인증 정보 저장 중

전체 예제

iOS 옵션

저장되는 항목

Android 자격 증명 저장

전체 예제

Android 옵션

저장되는 항목

저장된 자격 증명 사용

저장된 자격 증명 확인

보안 모범 사례

로컬 스토리지 보안

CI/CD 활용

내보내기: 즉시 사용 가능한 .env (권장)

환경 변수 전체 레퍼런스

GitHub Actions 예시

Base64 값 준비하기

환경 변수가 더 안전한 이유

자격 증명 로테이션

문제 해결

“등록된 자격 증명이 없습니다”

자격 증명 읽기 시 “Permission denied” 발생

자격 증명이 사용되지 않는 경우

자격 증명 지우고 다시 저장

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

파일 위치

다음 단계

도움이 필요하신가요?

인증 관리에서 이어서 진행하기

내보내기: 즉시 사용 가능한 `.env` (권장)