인증 관리

복사할 수 있는 AI 설정 지시

Ready to paste

Overview

Capgo CLI에서 빌드 인증서를 저장합니다. 컴퓨터에 저장 — Capgo 서버에 저장하지 않습니다. 기본적으로 모든 프로젝트에 공유되는 하나의 파일에 저장됩니다. 전역 file, ~/.capgo-credentials/credentials.json파일 --local 그것을 유지하기 위해 프로젝트별 내 .capgo-credentials.json 대신. 빌드를 실행할 때 저장된 인증 정보가 자동으로 사용되고 Capgo으로 안전하게 전송되고 빌드가 완료되면 삭제됩니다.

명령어

인증 정보를 상호 작용적으로 관리

저장된 인증 정보와 작업하는 가장 빠른 방법은 상호 작용 매니저입니다. 이 매니저는 TUI(터미널 UI)를 열어 저장된 항목을浏览하고 앱 및 플랫폼별로 구성된 항목을 확인하고 CI/CD-준비된 파일을 내보내거나 플랫폼의 인증 정보를 삭제할 수 있습니다. build init 터미널 창 .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]

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 그러나 모든 옵션은 선택 사항이며, 제공한 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

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

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

이전 BUILD_PROVISION_PROFILE_BASE64 인증서를 변환하고 legacy 키를 제거합니다. CAPGO_IOS_PROVISIONING_MAP자세한 내용은 Single Profile에서 마이그레이션 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"

제목이 "iOS 옵션"인 섹션

설정	설명	필수
`--certificate <path>`	__CAPGO_KEEP_0__ 인증서 파일 경로	예 (릴리즈)
`--p12-password <password>`	__CAPGO_KEEP_0__ 인증서 비밀번호	예 (릴리즈)
`--ios-provisioning-profile <mapping>`	프로비전 프로파일 매핑 (`bundleId=path` ) 반복 가능합니다. 멀티 타겟 앱에 대해 여러 프로파일을 매핑할 수 있습니다. 단일 프로파일과 CLI bundleId prefix가 없으면 프로파일에서 자동으로 추론됩니다.	예 (릴리즈)
`--apple-key <path>`	API App Store Connect .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>`	배포 모드: `app_store` (기본값) 또는 `ad_hoc`	없음
`--output-upload`	Capgo 다운로드 링크를 Capgo 빌드 아티팩트에 대해 임시로 활성화합니다.	없음 (기본값: `false`)
`--output-retention <seconds>`	빌드 아티팩트를 유지하는 기간 (예: `3600s`)	없음 (기본값: `3600s`)
`--skip-build-number-bump`	자동 빌드 번호 증가를 생략합니다.	없음

저장되는 항목

iOS 인증서 정보를 저장할 때 CLI:

인증서와 배포 프로파일 파일을 읽습니다.
base64 인코딩으로 변환합니다.
Android 인증서를 저장합니다. ~/.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

안드로이드 옵션

옵션	설명	필수
`--keystore <path>`	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)

저장되는 내용

When you save Android credentials, the CLI:

키 스토어 및 서비스 계정 JSON 파일을 읽습니다.
그들을 base64 인코딩으로 변환합니다.
그들을 저장합니다. ~/.capgo-credentials/credentials.json (또는 .capgo-credentials.json with --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

__CAPGO_KEEP_0__

분리된 인증 정보
- CI/CD 환경에서 로컬 개발과 다른 인증 정보를 사용
- 인증 정보를 정기적으로轮전
- 팀원들 사이에 인증 정보를 공유하지 않기

CI/CD 사용

CI/CD 환경에서 환경 변수를 저장된 인증 정보보다 선호 환경 변수를 저장된 인증 정보보다 선호

사용 가능한 .env 파일을 내보세요 `.env` (권장)

각 자격 증명 파일을 수동으로 base64로 인코딩하는 대신 (아래 참조) 아래파일을 생성해 주세요: build credentials manage 터미널 창

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

)에 모든 저장된 자격 증명을 환경 변수로 포함합니다. 각 라인은 CI/CD 제공자에 추가할 비밀입니다. 두 플랫폼은 기본적으로 결합됩니다. .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 또는 --platform android 한 가지로 제한

절대 커밋하지 마세요.

The CLI reads the following environment variables for credentials:

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

iOS 인증 정보:	변수명	형식	필수
`BUILD_CERTIFICATE_BASE64`	code 서명에 사용되는 P12/PKCS12 인증서	Base64	Yes (release)
`CAPGO_IOS_PROVISIONING_MAP`	__CAPGO_KEEP_0__ 버전의 앱 번들 ID를 프로비저닝 프로파일 데이터로 매핑한 JSON 객체	JSON 문자열	Yes (release)
`P12_PASSWORD`	P12 인증서의 비밀번호	평문	선택
`APPLE_KEY_ID`	API 키 ID	문자열 (예: "ABC1234567")	참고 1을 참조하십시오
`APPLE_ISSUER_ID`	App Store Connect API 발급자 ID	UUID 문자열	참고 1을 참조하십시오
`APPLE_KEY_CONTENT`	App Store Connect API 키 (.p8 파일 내용)	Base64	참고 1을 참조하십시오
`APP_STORE_CONNECT_TEAM_ID`	애플 개발자 팀 ID	문자열 (예: "XXXXXXXXXX")	예
`CAPGO_IOS_DISTRIBUTION`	배포 모드: `app_store` (기본값) 또는 `ad_hoc`	문자열	아니요

Android 인증서:

변수	설명	형식	필수
`ANDROID_KEYSTORE_FILE`	APK/AAB을 위한 키스토어 파일	Base64	예 (릴리즈)
`KEYSTORE_KEY_ALIAS`	키스토어 내의 키 별칭	문자열	Yes (release)
`KEYSTORE_KEY_PASSWORD`	키 별칭의 암호	평문	Yes*
`KEYSTORE_STORE_PASSWORD`	keystore 파일의 암호	평문	Yes*
`PLAY_CONFIG_JSON`	Google Play 서비스 계정 JSON	Base64	Yes (submission)

*만 암호 한 개만 제공하면 두 개 모두 사용됩니다. KEYSTORE_KEY_PASSWORD 및 KEYSTORE_STORE_PASSWORD.

GitHub Actions Example

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

터미널 창

# 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

환경 변수가 더 안전한 이유

이 방법은 더 안전합니다.

CI/CD 플랫폼에서 비밀을 관리합니다.
실행자에 credential 파일이 없습니다.
비밀을 쉽게轮换하고 접근 제어를 수행합니다.
비밀 사용 기록

비밀轮换

Regularly rotate your credentials:

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

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

# 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)

인증 파일을 읽을 때 “권한이 거부됨” 오류가 발생합니다

파일 권한 수정:

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

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

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

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

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) 다음 명령어를 실행하시기 바랍니다.

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 모든 프로젝트에 걸쳐 공유됩니다
Local (with --local): .capgo-credentials.json 프로젝트 루트 내에 — 해당 프로젝트에 대한 전역 파일을 덮어씁니다

The file is created automatically the first time you save credentials. Add .capgo-credentials.json 프로젝트에 .gitignore so per-project credentials are never committed.

다음 단계

Getting Started - 첫 번째 빌드를 생성하세요
iOS 빌드 - iOS 전용 빌드 설정
안드로이드 빌드 - 안드로이드 전용 빌드 설정
문제 해결 - 일반적인 문제와 해결 방법

도움이 필요하세요?

관리 인증서에서 계속

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.