__CAPGO_KEEP_1__

인증서 관리

iOS 및 Android 빌드 인증서를 관리하여 편리한 클라우드 빌드를 위해 로컬에서 빌드합니다.

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

인증서 관리

인증서 관리 섹션

저장된 인증서와 작업하기 가장 빠른 방법은 인터랙티브 매니저입니다. 인터랙티브 매니저는 TUI(터미널 사용자 인터페이스)를 열어 저장된 인증서를浏览하고 앱 및 플랫폼에 대한 설정을 확인할 수 있습니다. 또한 CI/CD-준비된 파일을 내보내거나 플랫폼의 인증서를 삭제할 수 있습니다. build init 터미널 창 .env 복사

선택
bunx @capgo/cli@latest build credentials manage
Option설명
--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 모든 항목은 선택적이지만, 제공한 필드만 업데이트됩니다.

인증서 목록

인증서 목록 제목

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

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

페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).

인증서 삭제

인증서 삭제 제목

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

컨텍스트: Capgo 마케팅 웹사이트. 역할: UI 레이블. 위치: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label). BUILD_PROVISION_PROFILE_BASE64 이전 CAPGO_IOS_PROVISIONING_MAP인증 정보를 변환하고 , 그리고 레거시 키를 제거합니다. 자세한 내용은 Single Profile에서 다중 대상으로 마이그레이션

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

iOS 옵션
Option설명필수
--certificate <path>.p12 인증서 파일 경로예 (릴리즈)
--p12-password <password>.p12 인증서 암호예 (릴리즈)
--ios-provisioning-profile <mapping>프로비전 프로파일 매핑 (bundleId=path) 다중 타겟 앱에 대해 반복 가능합니다. 단일 프로파일 및 Bundle ID 접두사가 없는 경우 CLI 프로파일에서 자동으로 추론됩니다.예 (릴리즈)
--apple-key <path>애플 스토어 연결 API .p8 키 경로참고 ¹
--apple-key-id <id>애플 스토어 연결 API 키 ID참고사항 ¹
--apple-issuer-id <id>애플 스토어 연결 API 발급자 ID (UUID)참고사항 ¹
--apple-team-id <id>애플 스토어 연결 팀 ID네
--apple-id <email>애플 ID 이메일 (앱별 암호 업로드 대안, API 키 대신)참고사항 ²
--apple-app-specific-password <password>애플 스토어 연결 앱별 암호xxxx-xxxx-xxxx-xxxx)참고사항 ²
--apple-app-id <id>숫자형 애플 스토어 연결 앱 ID (예: 1234567890)참고사항 ²
--ios-distribution <mode>배포 모드: app_store (기본) 또는 ad_hoc아니오
--output-upload빌드 아티팩트에 대한 시간 제한 Capgo 다운로드 링크를 활성화합니다.아니오 (기본:) false)
--output-retention <seconds>빌드 출력을 얼마나 유지할 것인지 (예:) 3600s)아니오 (기본:) 3600s)
--skip-build-number-bump자동 빌드 번호 증가를 생략합니다.아니오

저장되는 항목에 대한 설명

iOS 인증서를 저장할 때 __CAPGO_KEEP_0__:

iOS 인증 정보를 저장할 때, CLI

  1. base64 인코딩으로 변환합니다.
  2. 저장합니다.
  3. Saves them to ~/.capgo-credentials/credentials.json (또는 .capgo-credentials.json with --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"
}
}

안드로이드 인증서 저장

안드로이드 인증서 저장
터미널 창
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

페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).

Android 옵션
Option옵션설명
--keystore <path>필수keystore 또는 jks 파일의 경로
--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 (제출)

저장되는 내용

저장되는 내용

Android 인증서를 저장할 때 CLI:

  1. Keystore와 서비스 계정 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 환경에서 환경 변수를 선호하세요. 저장된 자격증명보다 환경 변수를 사용하세요. 준비된 자격증명을 내보내세요.

각 자격 증명 파일을 base64로 인코딩하는 것을 수동으로 처리하는 대신 (아래 참조) below파일을 생성해 줍니다: build credentials manage 터미널 창

클립보드에 복사
bunx @capgo/cli@latest build credentials manage
# pick your app → choose "Export to .env"

또는 .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 or --platform android scope을 한 가지로 제한하세요.

환경 변수 전체 참조

제목 "환경 변수 전체 참조"

CLI는 다음 환경 변수를 읽어 인증 정보로 사용합니다:

iOS 인증 정보:

변수설명형식필수
BUILD_CERTIFICATE_BASE64code 인증서에 대한 P12/PKCS12 인증서Base64예 (릴리즈)
CAPGO_IOS_PROVISIONING_MAP앱 스토어 연결 __CAPGO_KEEP_0__ 프로파일 데이터를 위한 번들 ID 맵JSON 문자열예 (릴리즈)
P12_PASSWORD__CAPGO_KEEP_0__ 인증서의 암호평문선택
APPLE_KEY_IDAPI 키 ID (앱 스토어 연결)문자열 (예: "ABC1234567")참고 사항¹
APPLE_ISSUER_ID애플리케이션 스토어 연결 API 발급자 IDUUID 문자열참고 사항¹
APPLE_KEY_CONTENT애플리케이션 스토어 연결 API 키 (.p8 파일 내용)Base64참고 사항¹
APP_STORE_CONNECT_TEAM_ID애플리케이션 개발자 팀 ID문자열 (예: "XXXXXXXXXX")네
CAPGO_IOS_DISTRIBUTION배포 모드: app_store (기본값) 또는 ad_hoc문자열없음

안드로이드 인증서:

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

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

GitHub 액션 예시

GitHub Actions 예시
github/워크플로우/빌드.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 }}

기본 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:
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

환경 변수가 왜 더 안전한가요?

환경 변수가 왜 더 안전한가요?라는 섹션

This approach는 더 안전합니다.

  • 비밀은 CI/CD 플랫폼에 의해 관리됩니다.
  • 실행자에 credential 파일이 없습니다.
  • 비밀을 쉽게轮换하고 접근 제어를 할 수 있습니다.
  • 비밀 사용 기록을 남깁니다.

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

  1. iOS: 연간 새로운 인증서 및 API 키를 생성하세요.
  2. 안드로이드: 연간 키 스토어 비밀번호를 변경하세요.
  3. 팀 구성 변경 후: 팀 구성원 이탈 시 회전하세요.

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

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

Troubleshooting

문제 해결

페이지/영역: 지원 / 프리미엄 지원 페이지 또는 푸터 지원 섹션. 역할: 섹션 또는 페이지 제목. 표시되는 곳: page support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (Support Policy Troubleshooting Title).

문제 해결 섹션입니다.

만들기에서 인증 정보가 발견되지 않았다고 말한다면:

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

    터미널 창
    bunx @capgo/cli@latest build credentials list
  2. 페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).:

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

  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 — 모든 프로젝트에 걸쳐 공유됩니다
  • 로컬 (with) --local): .capgo-credentials.json 프로젝트 루트 폴더 — 프로젝트별로 전역 파일을 덮어씁니다.

파일은 처음으로 인증 정보를 저장할 때 자동으로 생성됩니다. 인증 정보를 추가하세요. .capgo-credentials.json 프로젝트에 .gitignore 이러한 프로젝트별 인증 정보는 절대 커밋되지 않습니다.

다음 단계

다음 단계
  • 시작하기 - 첫 번째 빌드를 생성하세요.
  • iOS 빌드 - iOS 전용 빌드 설정
  • Android 빌드 - 안드로이드 전용 빌드 설정
  • 문제 해결 페이지/영역: 지원 / 프리미엄 지원 페이지 또는 footer 지원 섹션. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (지원 정책 문제 해결 제목)

- 일반적인 문제와 해결책

도움이 필요하세요?

support@__CAPGO_KEEP_0__.app

관리 인증서에서 계속 진행

관리 인증서에서 계속 진행 관리 인증서 CI/CD 자동화 계획을 위해 연결하세요. Capgo CI/CD 제품 워크플로우에서 Capgo CI/CD를 사용하세요. Capgo 네이티브 빌드 제품 워크플로우에서 Capgo 네이티브 빌드를 사용하세요. Capgo 통합 제품 워크플로우에서 Capgo 통합을 사용하세요. CI/CD 통합 CI/CD 통합 GitHub 액션 통합 GitHub 액션 통합