본문 바로가기

최초 1회 설정 체크리스트

완료하셨습니다 온보딩. 이제 Capgo를 설정하세요 한 번만. 그 이후에는 매일 하는 일은 단지 업로드 → 테스트 → 배포.

규칙: 채널은 릴리스 레인입니다(development, production) 티켓, 기능, 개발자 이름이 아닙니다.


최초 1회 설정 체크리스트

“원회 설정 체크리스트” 섹션
  1. 채널 생성: 아래를 참고하여 필요한 최소 세트를 선택하세요.

  2. 기본 업로드 채널 설정 에서 앱 설정:

    • 솔로 앱 → production
    • 팀 → development
  3. 프로덕션 채널: 공개 켜기, 디바이스 자체 설정 끄기, 네이티브보다 낮은 업데이트 차단, 자동 업데이트 가드 켜기 major.

  4. 테스트 채널 (development / staging: 공개는 꺼짐, QA용으로 디바이스에서 직접 설정하면 켜짐.

  5. CI에서 업로드하기 포함 --delta (체크섬과 네이티브 의존성은 자동 처리):

    터미널 창
    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 테스터 에서 검증하세요.

  6. 프로덕션 배포 테스트 후에만, 대시보드 또는 CLI에서.

  7. 팀 및 보안: 한 번만 초대, 최소 권한, 2FA 조직용으로 CI에 API 키 하나.

암호화는 그대로 두고, min_update_version, 메타데이터, 미리보기 끔 명확한 이유가 없다면.


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

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

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

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

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


Bundle 이름과 코멘트

“Bundle 이름과 코멘트” 섹션

Bundle 이름은 필수 따라하기 시맨틱 버저닝. Capgo는 호환성 검사, 채널 자동 업데이트 규칙, 롤백에 semver를 사용합니다. …의 모든 이름을 검증하세요 SemVer 테스터 업로드 전에.

  • 이름 = CI에서 가져온 semver, 예: 1.8.0, 1.8.0-beta.1, 또는 1.8.0-20260629.42
  • 코멘트 = 사람이 읽는 자유 텍스트 → commit abc1234 run 28059070270

semver 사용 프리릴리스 라벨(그 뒤의 부분 -) 동일한 버전으로 여러 빌드를 배포할 때 MAJOR.MINOR.PATCH. 예를 들어, 그대로 두고 1.8.0 프리릴리스에 날짜나 빌드 카운터를 추가하세요: 1.8.0-20260629.1, 1.8.0-beta.2. 다음과 같은 사용자 지정 형식을 만들지 마세요: fix-login-bug 또는 2.5.2026062306. 이런 형식은 유효한 semver가 아니므로 업로드가 실패하거나 예측 불가능하게 동작할 수 있습니다.

릴리스 노트는 --comment에 넣고, 번들 이름에는 넣지 마세요.

참고: 버전 타겟팅 및 번들 버전 관리.


--delta 업로드 delta 파일 이렇게 하면 기기가 매번 전체 bundle 대신 변경된 파일만 다운로드합니다. Checksum은 항상 자동으로 계산됩니다. checksum 플래그를 전달할 필요가 없습니다.

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

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

“Storage saving: --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 파일만 저장됩니다. 저장소 용량이 누적되는 대형 앱이나 업로드량이 많은 환경에서 선택하세요.

Trade-off: 서버에 zip 백업이 없으므로 delta 파일에만 의존하게 되며, Delta를 지원하지 않는 구버전 플러그인을 사용하는 기기는 업데이트할 수 없습니다. --delta-only 실제로 저장소 절약을 필요로 하는 경우에만 선택하세요.

기기에 추가 플러그인 설정이 필요하지 않습니다. 업데이트 프로그램이 델타 파일 목록을 읽고 변경된 파일만 가져옵니다.


데일리 워크플로우

“일일 워크플로” 섹션
Upload to development (--delta)
→ test
→ deploy to production
→ don't touch channel settings again

실수해결 방법
새 스토어 출시 전 OTA를 예상하시나요?플러그인 추가 후 네이티브 앱 다시 빌드 및 배포
번들을 업로드했지만 채널에 배포하지 않은 경우번들을 채널에 할당 (예: production)
기능, 티켓, 개발자별 채널영구 릴리스 레인만 사용
동적 CI 채널 이름고정된 이름: development, production
간단한 앱에 채널이 너무 많음1~2개의 채널로 시작
프로덕션에서 디바이스 자체 설정프로덕션은 Off, 테스트 채널은 On
건너뛰기 --delta추가 --delta 업로드에 사용; 사용 --delta-only 저장 공간을 절약해야 할 때만
Semver가 아닌 번들 이름팔로우 시맨틱 버저닝 에서 검증 SemVer 테스터
시간에 따른 버전 관리 방식 변경semver 유지; 추가 빌드에는 pre-release 라벨 사용 (1.8.0-20260629.1)
이유 없이 Metadata / preview 활성화기본값으로 비활성화
신규 설치 시 “새 버전 사용 가능” 메시지다음과 같은 경우 건너뛰기 current() 반환합니다 bundle.id === "builtin" (아래 참조)

App Store 심사: 신규 설치 시 업데이트 메시지 없음

“App Store 심사: 신규 설치 시 업데이트 메시지 없음” 섹션

Apple은 Capgo를 사용하는 앱을 허용합니다. 그러나 심사원은 첫 실행 시 표시되는 “새 버전 사용 가능” 또는 “업데이트 중” 메시지와 같은 UI를 거부합니다.

이것은 주로 자체 호스팅 및 수동 설정에 영향을 미치며, 이 경우 앱이 자체 버전 확인을 실행하고 자체 프롬프트를 표시합니다.

리뷰어가 스토어 바이너리를 설치합니다. 이 바이너리는 최신 번들보다 오래되어 첫 확인에서 바로 번들을 찾습니다. 자체 서버 호출이 번들을 반환하거나, 업데이터가 번들을 찾아 이벤트를 발생시킵니다. updateAvailable. 그때 앱이 메시지를 표시하면 리뷰어가 그것을 보게 됩니다.

신규 설치 또는 네이티브 스토어 업데이트 직후에는 앱이 함께 배포된 번들을 실행하고 current() 반환합니다 bundle.id === "builtin". 이 경우 메시지를 건너뛰세요:

import { CapacitorUpdater } from '@capgo/capacitor-updater'
const { bundle } = await CapacitorUpdater.current()
if (bundle.id !== 'builtin') {
showNewVersionMessage()
}

사용자에게 보이는 모든 UI에서는 “업데이트”, “live update”, “OTA”, “다운로드 중”, “설치 중”이라는 단어를 피하세요. 참고 컴플라이언스.