최초 1회 설정 체크리스트

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

완료하셨습니다 onboarding. 이제 Capgo를 설정하세요 한 번만. 그 이후의 일상적인 작업은 upload → test → deploy.

규칙: 채널은 릴리스 경로이지 (development, production), 티켓, 기능 또는 개발자 이름이 아닙니다.

최초 1회 설정 체크리스트

채널 생성: 아래 내용을 참고하여 가장 적합한 세트를 선택하세요.
기본 upload 채널 설정 에서 앱 설정:
- Solo 앱 → production
- Team → development
Production 채널: public on, device self-set off, native on 시 업데이트 차단, auto-update guard on major.
Test 채널 (development / staging): public off, QA를 위해 device self-set on.
CI에서 Upload 포함 --delta (checksum 및 native dependencies는 자동으로 처리됩니다):
터미널 창
```
npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
  --delta
```
이 --bundle 값 해야 합니다 유효해야 함 시맨틱 버저닝. 다음에서 검증하세요: SemVer 테스터 업로드하기 전에.
프로덕션에 배포 테스트를 마친 후, 다음을 통해 dashboard 또는 CLI에서 진행하세요.
팀 및 보안: 한 번만 초대하고, 최소 권한만 부여하며, 2FA 조직 전체에 적용하고, CI에는 하나의 API 키를 사용하세요.

암호화, min_update_version메타데이터 및 미리보기를 비활성화하세요 명확한 이유가 없는 한.

규모 선택

간단: 앱 1개, 채널 1개: production

팀: development + production. dev에 업로드하고 prod에 배포하세요.

네이티브 버전: 필요할 때만 채널을 추가하세요. 예: production-9.0 + test-9.0. 스토어 사용자는 메인 프로덕션 채널에 유지하세요.

여러 앱: 앱마다 동일한 단순 모델 (보통 하나 production 씩). 조직이 크다고 해서 추가 채널을 만들지 마세요.

릴리스 트레인 (선택 사항): staging → rc → production. 필요한 모든 앱에 동일한 템플릿을 적용하세요.

Bundle name vs comment

Bundle 이름은 필수 사항입니다. 다음 규칙을 시맨틱 버저닝 준수해야 합니다. Capgo는 호환성 체크, 채널 자동 업데이트 규칙 및 롤백을 위해 semver를 사용합니다. 다음의 모든 이름을 검증하세요: SemVer 테스터 upload 하기 전에.

이름 = CI의 semver, 예: 1.8.0, 1.8.0-beta.1, 또는 1.8.0-20260629.42
Comment = 사람이 읽는 자유 형식 텍스트 → commit abc1234 run 28059070270

semver 사용 pre-release labels ( -) 동일한 버전으로 여러 build를 배포할 때 MAJOR.MINOR.PATCH. 예를 들어, 1.8.0 pre-release에 날짜나 빌드 카운터를 추가하세요: 1.8.0-20260629.1, 1.8.0-beta.2. 다음과 같은 커스텀 형식을 만들지 마세요: fix-login-bug 또는 2.5.2026062306. 이는 유효한 semver가 아니므로 업로드가 실패하거나 예기치 않은 동작이 발생할 수 있습니다.

릴리스 노트는 bundle 이름이 아닌 --comment에 작성해야 합니다.

참고 항목 버전 타겟팅 및 bundle 버전 관리.

Delta 업로드

--delta 업로드 delta 파일 기기에서 매번 전체 번들을 받는 대신 변경된 파일만 다운로드할 수 있습니다. Checksum은 항상 자동으로 계산되므로 별도의 checksum 플래그를 전달할 필요가 없습니다.

기본값: `--delta` (delta 파일 + zip 백업)

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --delta

대부분의 앱에 권장되는 기본 설정입니다. Capgo는 delta 파일을 저장하고 및 전체 zip 파일을 백업으로 유지합니다. Delta를 지원하지 않는 이전 플러그인 버전의 기기는 zip 파일을 사용합니다. 저장 비용이 크게 중요하지 않을 때 유용합니다.

저장 공간 절약: `--delta-only`

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \
  --delta-only

사용 --delta-only 다음과 같은 경우에 Capgo 저장 공간을줄이고 싶을 때 사용하세요. 전체 zip 파일 대신 delta 파일만 저장됩니다. 앱 용량이 크거나 업로드 양이 많아 저장 공간 부담이 클 때 유용합니다.

주의사항: 서버에 zip 백업이 없으므로 delta 파일에만 의존하게 되며, Delta를 지원하지 않는 구버전 플러그인을 사용하는 기기는 업데이트할 수 없습니다. 실제 저장 공간 절약이 필요한 경우가 아니라면 --delta-only 이 옵션은 건너뛰셔도 됩니다.

기기에서 별도의 플러그인 설정은 필요하지 않습니다. updater가 delta 파일 목록을 읽어 변경된 파일만 가져옵니다.

데일리 워크플로우

Upload to development (--delta)
  → test
  → deploy to production
  → don't touch channel settings again

자주 하는 실수

실수	해결 방법
스토어 새 버전 출시 전 OTA 기대	플러그인 추가 후 Native Build 다시 빌드 및 배포
번들을 업로드했지만 채널에 배포하지 않음	번들을 채널에 할당 (예: `production`)
기능, 티켓 또는 개발자별 채널 운영	고정된 릴리스 레인만 사용
동적 CI 채널 이름 사용	고정 이름: `development`, `production`
단순한 앱에 너무 많은 채널 생성	1~2개의 채널로 시작
프로덕션 환경의 디바이스 자체 설정	프로덕션은 Off, 테스트 채널은 On
건너뛰기 `--delta`	추가 `--delta` 업로드 시; 사용하세요 `--delta-only` 스토리지 용량을 아껴야 할 때만
Semver 형식이 아닌 번들 이름	팔로우 시맨틱 버저닝 및 다음에서 검증하세요 SemVer 테스터
시간이 지남에 따라 버전 관리 체계 변경	Semver를 유지하세요; 추가 빌드에는 pre-release 레이블을 사용하세요 (`1.8.0-20260629.1`)
불필요한 Metadata / preview 활성화	기본적으로 비활성화

더 알아보기

채널 기본값, 우선순위 및 라우팅

델타 업데이트 --delta 사용 이유와 방법

CI/CD upload 및 배포 자동화

번들 Checksum, 의존성 및 메타데이터

최초 1회 설정 체크리스트