Native + OTA 채널 워크플로우

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

일반적인 Capgo 설정은 dev 채널과 프로덕션 채널을 사용합니다. CI는 모든 OTA 번들을 dev로 업로드한 뒤, 준비가 되면 production 로 프로모션합니다. 팀에서는 보통 --fail-on-incompatible 를 추가하여 CI가 새로운 native code이 필요한 live update를 실수로 배포하지 않도록 합니다.

이 페이지에서는 다음 질문에 답합니다: 다음과 같은 상황에서는 어떻게 해야 할까요? 의도적으로 현재 채널의 native packages와 호환되지 않는 bundle이 필요한 경우입니다.

Capgo가 native packages를 비교하는 이유가 궁금하다면, Native 호환성부터 시작하세요. OTA와 Capgo Build를 자동으로 선택하는 전체 CI 브랜치 구성은 자동 OTA 또는 Native.

권장 채널 레이아웃을

이 가이드는 dev 및 production 채널이 이미 존재한다고 가정합니다. 필요한 경우 먼저 생성하세요:

npx @capgo/cli@latest channel add production com.example.app
npx @capgo/cli@latest channel add dev com.example.app

채널	대상 사용자	일반적인 업로드
`dev`	내부 / QA 빌드	JS CI 푸시 시 (및 의도적인 native baseline)
`production`	스토어 사용자	릴리스 준비가 완료된 경우에만 프로모션 또는 업로드

--fail-on-incompatible 두 채널 모두에서 다음을 위한 기본 설정으로 적합합니다: 일상적인 OTA 업로드. 업로드 중인 번들의 native 패키지를 다음 번들과 비교합니다: 현재 해당 채널에 배포된 상태. 두 값이 다르면 upload가 실패하며 아무것도 배포되지 않습니다.

매일 OTA (플래그 유지)

변경 사항이 JavaScript 전용이고 native packages가 채널과 일치할 때:

npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --fail-on-incompatible \
  --auto-min-update-version

--fail-on-incompatible 실수로 인한 native drift를 방지합니다. --auto-min-update-version is required on every upload once the channel uses the metadata 전략(아래 권장 사항 참고)을 사용하세요. 채널이 활성화되어 있지 않으면 metadata 하지만 생략할 수 있습니다 --auto-min-update-version 전환하기 전까지는 생략 가능합니다.

upload 전 선택적 CI 게이트:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to upload with --fail-on-incompatible
# → native   stop; ship a native binary first (see below)

의도적인 Native Bump (플래그 1회 해제)

귀하 할 수 없습니다 새로운 Native code가 필요한 번들을 업로드하면서 --fail-on-incompatible를 유지할 수 없습니다. 해당 플래그는 바로 그 케이스를 차단하기 위해 존재합니다. 플러그인, Capacitor 버전 또는 기타 Native 의존성이 의도적으로 변경된 경우:

일치하는 버전을 배포하세요 네이티브 바이너리 (App Store / Play Store, 또는 Capgo 빌드).
일치하는 JS bundle 업로드 없이 --fail-on-incompatible.
권장: --auto-min-update-version 채널 설정을 통해 metadata 전략을 구성하면, 이전 바이너리를 사용하는 기기가 새 앱을 설치하기 전까지 새 bundle을 받지 않도록 할 수 있습니다.
해당 baseline 업로드 후에는 --fail-on-incompatible 다시 일반적인 OTA CI로 전환하세요 (그리고) --auto-min-update-version 채널이 유지되는 동안 metadata).

채널당 1회: metadata gating 활성화
터미널 창
```
npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata
```
다음 단계 반복: dev 해당 채널이 의도적인 Native Build 베이스라인도 수신하는 경우입니다. 이 전환 이후, 해당 채널로의 모든 upload에는 반드시 다음이 포함되어야 합니다: --auto-min-update-version 또는 --min-update-version.
Native Binary 배포

새로운 플러그인이나 Native 변경 사항이 포함된 iOS/Android 앱을 빌드하고 제출하세요. 사용자가 해당 binary를 설치하기 전까지는, 해당 Native 패키지에 의존하는 bundle을 안전하게 실행할 수 없습니다.
일치하는 OTA 베이스라인 upload (아니면 --fail-on-incompatible)
터미널 창
```
npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --auto-min-update-version
```
이 과정을 통해 채널에 새로운 Native 패키지가 기록됩니다. 이후 bundle releaseType / --fail-on-incompatible 에서 해당 베이스라인을 사용합니다.

보호된 OTA upload 재개

이후의 JS 전용 릴리스는 다시 두 플래그를 모두 사용합니다:

npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --fail-on-incompatible \
  --auto-min-update-version

자주 묻는 질문

계속 유지할 수 있나요? `--fail-on-incompatible` 그래도 네이티브와 호환되지 않는 번들을 푸시할 수 있나요?

아니요. 업로드하려는 네이티브 패키지가 채널의 Live Update 번들과 다를 경우, 해당 플래그는 의도적으로 명령을 실패 처리합니다. 의도적으로 네이티브 버전을 올리려는 경우, 해당 업로드 시에만 플래그를 제외하세요(그리고 가능한 경우 --auto-min-update-version 사용하세요).

플래그 없이 한 번만 업로드하는 것이 올바른 방법인가요?

네. 새로운 바이너리를 배포한 후 채널의 네이티브 베이스라인을 업데이트하는 공식적인 방법입니다. 그 외의 모든 OTA 업로드 시에는 플래그를 유지하여, 실수로 네이티브 버전이 어긋나는 경우 CI에서 실패하도록 설정하세요.

어디로 upload 하나요? `dev` 먼저, 그다음은 `production`?

네, 기존 워크플로우와 일치한다면 그렇게 하셔도 됩니다. 동일한 규칙을 적용하세요. 채널별로: 호환성 검사는 대상 채널에 현재 라이브된 버전을 기준으로 합니다. promote하거나 다시 upload하려면 production 한 후에만 dev 괜찮아 보이면 native-baseline upload를 사용하세요 (no --fail-on-incompatible) 새 native 패키지를 기록해야 하는 각 채널에 적용하세요.

플래그가 켜진 채로 새 native bundle을 upload하면 어떻게 되나요?

CI가 실패하고 Capgo는 해당 upload를 배포하지 않습니다. 이는 예상된 결과입니다. 변경이 실수였다면 native 패키지를 수정하고 OTA로 재시도하고, 의도한 것이라면 위의 native 경로를 사용하세요.

어느 job에 어떤 플래그를 붙이나요?

경로	시기	Upload 플래그
OTA가	JS 전용; 네이티브 패키지는 채널과 일치함	`--fail-on-incompatible` + `--auto-min-update-version` (채널이 활성화된 경우 필수) `metadata`)
네이티브 베이스라인	새 네이티브 바이너리 + 일치하는 JS 번들	아니요 `--fail-on-incompatible`; 유지 `--auto-min-update-version`

Native 호환성

Capgo가 네이티브 패키지 드리프트를 감지하는 방식과 호환되지 않음이 디바이스에 미치는 영향.

자동 OTA 또는 Native

연결 bundle releaseType GitHub Actions 또는 GitLab에 연결하여 CI가 올바른 경로를 선택하도록 합니다.

버전 타겟팅

채널, semver 규칙 및 배포 환경을 위한 메타데이터 전략.

CLI: 번들

upload, compatibility, releaseType 및 관련 플래그에 대한 참조.

Native + OTA Channel Workflow 다음 단계

사용 중이라면 Native + OTA 채널 워크플로우 네이티브 릴리스 간에 Live Update를 안전하게 유지하려면, 다음을 연결하세요: Native 호환성 패키지 비교 규칙의 경우, 자동 OTA 또는 Native CI 브랜칭의 경우, 버전 타겟팅 메타데이터 floor 및 Capgo CLI 번들 레퍼런스를 이해하려면, upload 플래그의 경우.