인증 관리

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

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 전달 프로젝트 당 에서 .capgo-credentials.json 대신. 빌드를 실행할 때 저장된 인증 정보가 자동으로 사용되고 Capgo으로 안전하게 전송되고 빌드가 완료되면 삭제됩니다.

명령어

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

저장된 인증서를 관리하는 가장 빠른 방법은 인터랙티브 매니저입니다. 이 매니저는 TUI(터미널 사용자 인터페이스)를 열어 저장된 항목을浏览하고 앱 및 플랫폼별로 구성된 항목을 확인하고 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

인증 정보 이전

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

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

이전 명령어는 오래된 BUILD_PROVISION_PROFILE_BASE64 인증 정보를 감지하고 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>`	__CAPGO_KEEP_0__ 파일 경로	예 (릴리즈)
`--p12-password <password>`	__CAPGO_KEEP_0__ 파일의 암호	예 (릴리즈)
`--ios-provisioning-profile <mapping>`	프로비전 프로파일 매핑 (`bundleId=path`). Repeatable for multi-target apps. If only one profile and no bundleId prefix, CLI auto-infers from the profile.	예 (릴리즈)
`--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>`	Distribution mode: `app_store` (기본값) 또는 `ad_hoc`	No
`--output-upload`	빌드 아티팩트에 대한 시간 제한 Capgo 다운로드 링크를 활성화합니다.	No (기본값: `false`)
`--output-retention <seconds>`	빌드 출력을 유지하는 기간 (예: `3600s`)	No (기본값: `3600s`)
`--skip-build-number-bump`	자동 빌드 번호 증가를 생략합니다.	No

이 방법은 금지되어 있으며 조언받지 않는다. 이것은 오직 Ionic Appflow에서 이주하는 팀을 위해 호환성 경로로 존재한다. App Store Connect API 키 (.p8), 이가 CI/CD에 권장되는, 더 강력하고 더 안전한 옵션으로 사용되어야 한다. 만약 사용해야 한다면, 세 가지 옵션 (--apple-id, --apple-app-specific-password, --apple-app-id)이 모두 필요하다. 숫자 (App Store Connect → 앱 → 앱 정보 → Apple ID)가 업로드를 진행할 수 있도록 2FA interactvie 프롬프트 없이 진행되며, 이 방법을 사용하면 빌드 번호가 타임스탬프로 되돌아간다. App Store Connect가 쿼리되지 않기 때문이다. --apple-app-id 저장되는 내용

저장되는 내용 섹션

When you save iOS credentials, the CLI:

base64 인코딩으로 변환한다
Converts them to base64 encoding
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 파일의 경로	네 (릴리즈)
`--keystore-alias <alias>`	키 별칭(Keystore)	네 (릴리즈)
`--keystore-key-password <password>`	키 별칭의 암호	네 (릴리즈)
`--keystore-store-password <password>`	Keystore의 암호	네 (릴리즈)
`--play-config <path>`	Play Store 서비스 계정 JSON의 경로	네 (제출)

저장되는 내용

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 환경에서 환경 변수를 선호하는 것이 좋습니다. 저장된 인증 정보보다 환경 변수를 선호하는 것이 좋습니다. 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 App Store Connect 키 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 파일이 없습니다.
비밀을 쉽게轮换하고 접근 제어를 적용할 수 있습니다.
비밀 사용 기록

비밀轮换

정기적으로 비밀을轮환하세요:

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

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

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

문제 해결

”No credentials found”

빌드가 인증 정보가 없다고 말하는 경우:

인증 정보가 저장되어 있는지 확인하세요:
터미널 창
```
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): .capgo-credentials.json 프로젝트 루트에 있는 — 해당 프로젝트에 대한 전역 파일을 덮어씁니다.

파일은 처음으로 자격 증명을 저장할 때 자동으로 생성됩니다. 자격 증명을 추가하세요. .capgo-credentials.json 프로젝트에 .gitignore 그런 다음

프로젝트 자격 증명을 절대 커밋하지 않도록 하세요.

다음 단계 시작하기
- 첫 번째 빌드 생성 - 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 액션 통합.

인증 관리

설명

명령어

인증 정보 저장

인증 정보 업데이트

인증서 목록

인증서 삭제

인증 정보 이전

iOS 인증 정보를 저장

완전한 예제

iOS 옵션

저장되는 내용 섹션

Android 인증서 저장

완전한 예제

안드로이드 옵션

저장되는 내용

저장된 자격 증명을 사용합니다.

저장된 자격 증명 보기

보안 최선의 방법

로컬 스토리지 보안

CI/CD 사용

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

절대 커밋하지 마십시오.

GitHub Actions Example

Base64 값 준비

환경 변수가 더 안전한 이유

비밀轮换

문제 해결

”No credentials found”

인증 정보를 읽을 때 "권한이 거부됨" 오류가 발생합니다

인증서가 사용되지 않는다

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

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

파일 위치

프로젝트 자격 증명을 절대 커밋하지 않도록 하세요.

도움이 필요하세요?

관리 인증서에서 계속

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