자격 증명 관리

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

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

개요

Capgo CLI은 컴퓨터의 폴더에 빌드 자격 증명을 로컬로 저장할 수 있는 Capgo의 빌드 서버로 자동으로 사용하고 보안적으로 전송하는 것을 허용합니다. .capgo-credentials Capgo __CAPGO_KEEP_1__

명령어

인증서버

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

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

인증서버 업데이트

터미널 창

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

The update 명령어는 합산 병합 을 사용하여 프로비저닝 프로파일을 구성합니다 — 새로운 프로파일은 기존 프로파일과 병합됩니다. 프로비저닝 맵 전체를 대체하려면 --overwrite-ios-provisioning-map.

예시 — 기존 인증서에 확장 프로파일을 추가하는 경우

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

업데이트 명령어는 save 의 동일한 옵션을 받을 수 있지만 모든 옵션은 선택 사항입니다 — 제공한 필드만 업데이트됩니다.

인증서 목록

현재 저장된 자격 증명 (암호는 가려져 있습니다):

npx @capgo/cli build credentials list

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

자격 증명 삭제

로컬 머신에서 저장된 자격 증명 삭제:

# Clear all credentials
npx @capgo/cli build credentials clear

# Clear credentials for a specific app + platform
npx @capgo/cli build credentials clear --appId com.example.app --platform ios

자격 증명 이동

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

npx @capgo/cli build credentials migrate --platform ios

이전 버전의 BUILD_PROVISION_PROFILE_BASE64 인증 정보를 감지하고 CAPGO_IOS_PROVISIONING_MAP, 그것을 변환하고 그것을 제거합니다.

See

완전한 예제

npx @capgo/cli 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 인증서 파일의 경로	Yes (release)
`--p12-password <password>`	__CAPGO_KEEP_0__ 인증서 (.p12) 비밀번호	Yes (release)
`--ios-provisioning-profile <mapping>`	__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__ App Store Connect 발급자 ID (UUID)
`--apple-issuer-id <id>`	App Store Connect API Issuer ID (UUID)	See note¹
`--apple-team-id <id>`	앱 스토어 연결 팀 ID	예
`--ios-distribution <mode>`	배포 모드: `app_store` (기본값) 또는 `ad_hoc`	아니오
`--output-upload`	Capgo 다운로드 링크를 시간 제한된 빌드 아티팩트에 활성화합니다.	아니오 (기본값: `false`)
`--output-retention <seconds>`	빌드 출력을 얼마나 유지할 것인지 (예: `3600s`)	빌드 번호 자동 증가를 생략합니다. `3600s`)
`--skip-build-number-bump`	아니오	¹ 앱 스토어 연결 __CAPGO_KEEP_0__ 키 요구 사항

저장되는 항목

iOS 인증서를 저장할 때 CLI:

인증서와 배포 프로파일 파일을 읽습니다.
base64 인코딩으로 변환합니다.
인증서를 저장합니다. .capgo-credentials 폴더
비밀번호와 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 인증서를 저장하는 중입니다.

완전한 예제

npx @capgo/cli 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 Options

옵션	설명	필수
`--keystore <path>`	.keystore 또는 .jks 파일의 경로	예 (릴리즈)
`--keystore-alias <alias>`	키스토어의 키 별칭	예 (릴리즈)
`--keystore-key-password <password>`	키 별칭의 비밀번호	예 (릴리즈)
`--keystore-store-password <password>`	키스토어의 비밀번호	예 (릴리즈)
`--play-config <path>`	Play Store 서비스 계정 JSON의 경로	네 (제출)

저장되는 내용은?

Android 인증서를 저장할 때 CLI:

keystore 및 서비스 계정 JSON 파일을 읽습니다.
그것들을 base64 인코딩으로 변환합니다.
인증서를 저장할 폴더 .capgo-credentials 폴더
비밀번호 및 alias를 평문으로 저장합니다 (로컬 파일만)

저장된 파일 구조:

{
  "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 folder
npx @capgo/cli build com.example.app --platform ios

또는 환경 변수를 사용하여 저장된 인증 정보를 오버라이드할 수도 있습니다.

# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
npx @capgo/cli build com.example.app --platform ios

우선 순위 순서:

환경 변수 (가장 높은 우선 순위)
저장된 인증 정보는 .capgo-credentials 폴더
인증 정보가 없습니다 (가장 낮은 우선 순위)

저장된 인증 정보 보기

저장된 인증 정보 목록:

npx @capgo/cli 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/

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

보안 최적화 방법

로컬 스토리지 보안

__CAPGO_KEEP_0__

# Ensure credentials folder is not readable by others
chmod 700 .capgo-credentials
chmod 600 .capgo-credentials/*

__CAPGO_KEEP_3__

# Add to .gitignore
echo ".capgo-credentials/" >> .gitignore

__CAPGO_KEEP_4__
- __CAPGO_KEEP_5__
- __CAPGO_KEEP_6__
- __CAPGO_KEEP_7__

__CAPGO_KEEP_8__

CI/CD 환경에서 사용하는 경우, 보관된 자격 증명을 사용하는 것보다 환경 변수를 선호합니다. 자격 증명 환경 변수 참조

자격 증명 환경 변수 참조

CLI는 다음 환경 변수를 읽어 자격 증명을 읽습니다.:

iOS 자격 증명:

변수	설명	형식	필수
`BUILD_CERTIFICATE_BASE64`	P12/PKCS12 certificate for code signing	Base64	Yes (release)
`CAPGO_IOS_PROVISIONING_MAP`	__CAPGO_KEEP_0__	JSON string	Yes (release)
`P12_PASSWORD`	__CAPGO_KEEP_0__	Plain text	Optional
`APPLE_KEY_ID`	App Store Connect API Key ID	__CAPGO_KEEP_0__ (예: 'ABC1234567')	참고 ¹
`APPLE_ISSUER_ID`	App Store Connect API Issuer 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`	키스토어 내의 키 별칭	문자열	예 (릴리즈)
`KEYSTORE_KEY_PASSWORD`	키 별칭의 비밀번호	평문	예
`KEYSTORE_STORE_PASSWORD`	__CAPGO_KEEP_0__ 키 스토어 파일의 암호	평문	예
`PLAY_CONFIG_JSON`	Google Play 서비스 계정 JSON	Base64	예 (제출)

*만 암호 하나가 제공되면, 두 암호 모두에 사용됩니다. KEYSTORE_KEY_PASSWORD 및 KEYSTORE_STORE_PASSWORD.

GitHub 액션 예시

name: Cloud Build

on:
  push:
    branches: [main]

jobs:
  build-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npx @capgo/cli build 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: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npx @capgo/cli build 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 비밀을 위해 자격 증명 파일을 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:
npx @capgo/cli build credentials save --platform ios \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  # ... other options
# Then copy CAPGO_IOS_PROVISIONING_MAP from .capgo-credentials 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 비밀을 저장하기 위해 한 줄의 Base64 문자열로 변환합니다.

이 접근 방식은 더 안전합니다:

CI/CD 플랫폼에서 비밀을 관리합니다
실행자에 credential 파일이 없습니다
비밀의 rotation 및 접근 제어
비밀 사용 기록

Credential Rotation

정기적으로 credential을 rotation하세요:

iOS: 연간 새로운 certificate 및 API 키를 생성하세요
Android: 연간 키 스토어 비밀번호 변경
팀 구성원 변경 후: 팀 구성원이 떠날 때 회전

저장된 자격 증명 업데이트:

# Re-run save command with new credentials
npx @capgo/cli build credentials save --platform ios --certificate ./new-cert.p12 ...

문제 해결

’인증 정보가 없습니다’

빌드가 인증 정보가 없다고 말할 때:

인증 정보가 저장되어 있는지 확인하세요:
터미널 창
```
npx @capgo/cli build credentials list
```

인증 정보가 없으면 저장:

npx @capgo/cli build credentials save --platform ios ...

인증 정보 폴더가 존재하는지 확인:
터미널 창
```
ls -la .capgo-credentials/
```

인증 정보 읽기 시 “권한이 거부됨” 오류

파일 권한 설정:

chmod 700 .capgo-credentials
chmod 600 .capgo-credentials/*

사용되지 않는 자격 증명

정확한 플랫폼이 지정되었는지 확인하십시오:

# Make sure --platform matches saved credentials
npx @capgo/cli build com.example.app --platform ios  # Uses ios credentials
npx @capgo/cli build com.example.app --platform android  # Uses android credentials

자격 증명이 깨끗하고 다시 저장하십시오

자격 증명이 손상된 것처럼 보인다면:

# Clear all credentials
npx @capgo/cli build credentials clear

# Save again
npx @capgo/cli 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

Save using the CLI

npx @capgo/cli 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터미널 창

npx @capgo/cli build credentials migrate --platform ios

과 CAPGO_IOS_PROVISIONING_MAP 키를 제거합니다. BUILD_PROVISION_PROFILE_BASE64 빌드 테스트 APPLE_PROFILE_NAME 터미널 창

클립보드에 복사

npx @capgo/cli build com.example.app --platform ios

__CAPGO_KEEP_0__ (선택사항)

unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

파일 위치

인증 정보는 .capgo-credentials 폴더:

macOS/Linux: .capgo-credentials/ (프로젝트 루트 또는 홈 디렉토리)
Windows: .capgo-credentials\ (프로젝트 루트 또는 홈 디렉토리)

인증 정보를 저장할 때 처음으로 저장하면 자동으로 폴더가 생성됩니다.

다음 단계

시작하기 - 첫 번째 빌드 생성
iOS 빌드 - iOS 전용 빌드 설정
Android 빌드 - Android 전용 빌드 설정
문제 해결 - 일반적인 문제와 해결책

자격 증명 관리

개요

명령어

인증서버

인증서버 업데이트

인증서 목록

자격 증명 삭제

자격 증명 이동

See

완전한 예제

iOS 옵션

저장되는 항목

Android 인증서를 저장하는 중입니다.

완전한 예제

Android Options

저장되는 내용은?

저장된 인증 정보 사용

저장된 인증 정보 보기

보안 최적화 방법

로컬 스토리지 보안

__CAPGO_KEEP_8__

자격 증명 환경 변수 참조

GitHub 액션 예시

Base64 값 준비

CI/CD 비밀을 저장하기 위해 한 줄의 Base64 문자열로 변환합니다.

Credential Rotation

문제 해결

’인증 정보가 없습니다’

인증 정보 읽기 시 “권한이 거부됨” 오류

사용되지 않는 자격 증명

자격 증명이 깨끗하고 다시 저장하십시오

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

파일 위치

다음 단계

도움이 필요합니다