단계적 배포

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

Progressive rollout을 사용하면 채널의 stable fallback을 제공합니다. 상태를 유지하면서 별도의 rollout 대상 을 제어된 일부 디바이스에만 전달합니다. 대부분의 운영 환경 사용자는 stable 버전을 유지하며, rollout 코호트 사용자만 다음 단계로 넘어가기 전까지 candidate 버전을 받게 됩니다. 롤아웃 완료 또는 롤아웃 롤백.

Capgo 채널의 점진적 롤아웃 제어 — 이 **점진적 롤아웃** 채널의 Information 탭에 있는 섹션은 **롤아웃 대상** 및 **Stable 폴백**퍼센트 제어 및 롤아웃 작업을 표시합니다.

점진적 롤아웃의 전체 동작 흐름

각 채널은 동시에 두 개의 bundle 링크를 가질 수 있습니다:

콘솔 레이블	API / CLI	적용 대상
Stable 폴백	Stable 번들 (`version` 켜짐 Channels POST)	해당 채널의 모든 기기 중 하지 마세요 rollout 코호트에 포함된 기기.
롤아웃 대상	Rollout 대상 (`rolloutVersion` / `rollout_version`)	롤아웃 진행 중 Capgo가 롤아웃 코호트로 무작위 선택한 기기만 일시 중지되지 않은 동안 대상이며, 일시 중지되지 않은 상태여야 합니다.

업데이트 확인 때마다 발생하는 일

기기는 자신의 채널에서 업데이트를 받기 위해 Capgo에 요청합니다.
롤아웃이 비활성화되어있거나 대상이 없는 경우, Capgo는 stable fallback을 제공합니다..
롤아웃이 일시 중지되지 않은 동안 및 일시 중지됨, 이미 코호트에 포함된 기기는 기존 롤아웃 대상; 그 외 모든 기기는 stable fallback을 제공합니다..
롤아웃이 일시 중지되지 않은 동안 그리고 일시 중지되지 않은 경우, Capgo이(가) 해당 기기가 롤아웃 코호트에 포함되어 있는지 확인합니다:
- 코호트에 포함됨 → 롤아웃 대상.
- 코호트에 포함되지 않음 → 안정적인 fallback.

Capgo는 대상 기기마다 무작위로 결정한 뒤, 기기 ID와 rollout ID의 해시를 사용해 캐시합니다. 그러면 코호트가 고정(sticky) 되어, 매 업데이트 확인마다 다시 추첨하지 않고 설정된 캐시 기간 동안 유지됩니다.

Rollout 활성화

Rollout에는 먼저 안정적인 fallback이 필요합니다. 대시보드에서 rollout target을 선택하기 전에 stable bundle을 할당하세요. 이때 공개 채널 API, 기존 채널이 제공할 수 있습니다. version 및 rolloutVersion 같은 POST 요청에서.

배포를 시작하려면:

다음을 설정하세요: 롤아웃 대상 (또는 번들 업로드/할당 — 참고 번들 업로드 및 할당).
다음을 선택하세요: 비율 그리고 클릭하세요: 비율 적용.
클릭 rollout 활성화.

rollout을 활성화하기 전까지는 타겟과 퍼센티지를 설정해도 기기에 전달되는 내용은 변경되지 않습니다.

퍼센트 변경

콘솔에서 퍼센티지를 수정한 뒤 비율 적용 를 클릭해 저장하세요. Capgo은 가능한 경우 기존 결정을 유지합니다:

퍼센티지 증가 — 이미 선택된 기기는 선택된 상태로 유지되며, 이전에 선택되지 않은 기기 중 일부만 무작위로 추가됩니다.
퍼센티지 감소 — 선택된 코호트 중 일부가 무작위로 안정적인 폴백 상태로 돌아갑니다.
퍼센티지를 0%로 설정 — 선택된 새 기기가 없습니다. 이미 활성화된 rollout 대상이 적용된 기기는 대상 설정을 비활성화, 롤백 또는 변경하기 전까지 해당 대상을 계속 유지합니다.
Rollout 일시 중지 — 새로운 기기가 진입하는 것을 차단하지만, 이미 활성화된 대상을 실행 중인 기기는 그대로 유지합니다.
Rollout 비활성화 — rollout 대상 확인을 중단하며, 업데이트 체크 시 안정적인 fallback 버전을 사용합니다.

번들 업로드 및 할당

채널에서 포함 progressive rollout이 설정되면, 새로운 업로드 및 bundle 링크는 다음으로 전송됩니다: 롤아웃 대상 기본값으로. Stable 폴백 직접 교체하기로 선택하지 않는 한 변경되지 않습니다.

rollout이 설정된 채널에 bundle을 upload하거나 링크하면, 콘솔에 제목과 이 채널은 점진적 배포(progressive rollout)를 사용합니다. 배너가 표시됩니다:

이 채널의 새로운 upload 및 bundle 링크는 기본적으로 rollout 대상에 적용됩니다. Stable은 직접 교체하기로 선택하지 않는 한 변경되지 않습니다.

bundle이 배포될 위치를 선택하세요:

콘솔 선택 사항	사용 시점
자동 (권장)	기본값. 다음 항목과 동일: 롤아웃 대상 점진적 배포(progressive rollout)가 설정된 경우와 동일하며, stable 교체 설정되지 않은 경우와 동일합니다. API와 일치하며 `target: "auto"` 또한 CLI는 후보(candidate)를 `--stable` 또는 `--rollout`.
롤아웃 대상	업로드하지 않습니다. 안정적인 폴백(fallback)은 그대로 유지됩니다.
stable 교체	운영 중인 안정 버전을 의도적으로 교체합니다 (비상 탈출구).

힌트 progressive 설정 시 Auto가 rollout을 사용합니다 API에 적용됨 target: "auto" 및 통과하지 못한 CLI 업로드에 적용됨 --stable 또는 --rollout.

기본 업로드 라우팅

채널 상태	기본 업로드 / 할당	Stable 폴백	롤아웃 대상
아니요 progressive rollout 설정됨	채널에 도달함	업로드 설정	해당 없음
점진적 배포(Progressive rollout) 설정됨	채널에 도달함	변경 없음	업로드 설정

CLI 및 API 경로

번들 배포 방식	Stable 폴백	롤아웃 대상	참고 사항
`bundle upload --channel <name>` (추가 플래그 없음)	롤아웃 채널에서는 변경 없음; 설정 롤아웃이 없을 때	설정 롤아웃 채널에 적용	콘솔 기본값과 동일합니다.
`bundle upload --channel <name> --rollout <percent>`	변경 없음	설정; 롤아웃 일시 중지되지 않은 동안 해당 퍼센트에서	한 번의 업로드와 활성화로 끝.
`bundle upload --channel <name> --stable`	교체됨	변경 없음	탈출구 — 의도적인 안정 버전 교체.
`bundle upload` 포함 아니요 `--channel`	변경 없음	변경 없음	등록만 하기; 연결하기 `channel set` 또는 API.
콘솔 링크 다이얼로그 → 자동 (권장)	롤아웃 채널에서 변경 없음	설정 롤아웃 채널에 적용	기본 설정입니다.
콘솔 링크 다이얼로그 → 롤아웃 대상	변경 없음	설정	롤아웃 대상을 명시적으로 지정합니다.
콘솔 링크 다이얼로그 → stable 교체	교체됨	변경 없음	비상 탈출구.
PUT `/bundle/` 포함 `target: "auto"`	롤아웃 채널에서 변경 없음	설정 롤아웃 채널에 적용	API 기본값.
PUT `/bundle/` 포함 `target: "rollout"`	변경 없음	설정	롤아웃 대상을 명시적으로 지정합니다.
PUT `/bundle/` 포함 `target: "stable"`	교체됨	변경 없음	비상 탈출구.
`channel set --bundle <version>`	교체됨	변경 없음	명시적 stable 오버라이드.
`channel set --rollout-bundle <version>` (+ `--rollout-percentage`, `--rollout-enable`)	변경 없음	설정 또는 변경됨	업로드 없이 타겟 설정.
Channels POST `version`	교체됨 설정 시	변경 없음	명시적 stable 오버라이드.
Channels POST `rolloutVersion`	변경 없음	설정 또는 변경됨 설정 시	프로그래밍 방식의 타겟 할당.

CLI 예시

rollout이 설정된 채널의 기본 upload (rollout 대상; stable은 변경 없음):

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production

Upload하고 rollout 대상을 설정한 뒤 5%로 활성화:

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --rollout 5

stable을 명시적으로 교체:

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --stable

연결하지 않고 upload한 뒤 rollout을 설정:

bunx @capgo/cli@latest bundle upload com.example.app --path ./dist -b 1.3.0

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-bundle 1.3.0 \
  --rollout-percentage 5 \
  --rollout-enable

명시적 타겟을 지정하여 API 할당 (auto | stable | rollout):

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "version_id": 456,
    "channel_id": 789,
    "target": "rollout"
  }' \
  https://api.capgo.app/bundle/

이미 선택된 기기를 재설정하지 않고 노출 비중 늘리기:

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-percentage 25

사용 --rollout-percentage-bps 정수 퍼센트 단위보다 더 세밀한 단계가 필요한 경우 (예: 50 = 0.5%).

참고하세요: 예제 앱의 채널 CLI 참조 및 bundle CLI 참조 모든 롤아웃 옵션에 대해. Console UX는 다음에서 제공됩니다 capgo.app#3313..

점진적 롤아웃 섹션 (dashboard)

앱 열기 → 채널 → 채널 선택 → 정보 → 점진적 롤아웃.

섹션에는 다음이 표시됩니다 롤아웃 대상 및 Stable 폴백 두 개의 bundle 링크에 대해 사용하세요. 배포 대상 변경 다른 후보 bundle을 선택하려면 사용하세요. 퍼센트를 수정한 후에는 비율 적용 를 클릭하여 저장합니다.

제어	역할	이미 코호트에 포함된 디바이스	새로운 대상 디바이스
배포 대상 변경	설정합니다 `rolloutVersion`. 이를 변경하면 새로운 rollout ID와 코호트가 생성됩니다. 번들을 채널(기본값)에 업로드하거나 할당할 때도 rollout 대상이 설정됩니다.	사용자가 다시 체크인하여 새로운 결정 규칙과 일치할 때까지 이전 대상을 유지합니다.	새 대상 기준으로 백분율에 따라 선택됩니다.
비율 적용	입력한 백분율을 저장합니다.	비율을 높일 때는 유지되지만, 낮출 때는 무작위로 일부가 제외될 수 있습니다.	위의 백분율 규칙에 따라 추가되거나 제외됩니다.
rollout 활성화	설정된 대상과 백분율에 대해 rollout 배포를 활성화합니다.	다음 업데이트 확인 전까지는 즉시 변경되지 않습니다.	다음 확인 시 선택될 수 있습니다.
Rollout 일시 중지	새 기기 유입을 중단합니다.	Rollout 대상 버전을 유지합니다.	안정적인 Fallback 버전을 받습니다. 다음 체크 시점에 적용됩니다.
Rollout 재개	일시 중지 상태를 해제합니다.	변경 없음	다음 체크 시점에 다시 선택될 수 있습니다.
Rollout 비활성화	Rollout 대상 조회를 중단하며, Capgo는 모든 사용자에게 안정적인 Fallback을 사용합니다.	안정적인 Fallback으로 이동 다음 체크 시점에 적용됩니다.	안정적인 폴백(fallback)을 받습니다.
롤아웃 완료 (API: `promoteToStable`; CLI: `--rollout-promote`)	롤아웃 대상을 새로운 안정적 폴백으로 설정한 후 롤아웃 상태를 초기화합니다. 다음 작업으로 확인됩니다: 점진적 롤아웃을 완료하시겠습니까? — 대상이 모든 사용자에게 안정화되며, 이전의 안정적 폴백이 교체되고 퍼센트가 초기화됩니다.	안정적 폴백으로 설정 모든 사용자에게 적용됩니다.	완료된 번들을 받습니다 안정 버전으로.
롤아웃 롤백 (API: `rollback`; CLI: `--rollout-rollback`)	대상 설정을 해제하고, 롤아웃을 중단하며, 퍼센트를 0%로 초기화하여 디바이스를 안정적인 fallback 상태로 되돌립니다.	안정적인 fallback으로 복구 다음 체크 시점에 적용됩니다.	안정적인 fallback을 수신합니다.

한 번에 하나의 터미널 작업만 사용하세요 (롤아웃 완료 및 롤아웃 롤백 단일 API 호출로 조합할 수 없습니다):

# Stop adding devices while you investigate
bunx @capgo/cli@latest channel set production com.example.app --rollout-pause

# Allow new devices to enter again
bunx @capgo/cli@latest channel set production com.example.app --rollout-resume

# Complete rollout — candidate becomes stable for everyone
bunx @capgo/cli@latest channel set production com.example.app --rollout-promote

# Rollback rollout — discard candidate and return to stable
bunx @capgo/cli@latest channel set production com.example.app --rollout-rollback

다음 단계를 완료할 때까지 롤아웃 대상 번들을 유지하세요. 롤아웃 완료 또는 롤아웃 롤백. 안정적인 폴백 또는 롤아웃 대상으로 연결된 번들은 삭제로부터 보호됩니다.

안전한 워크플로우

점진적 롤아웃은 채널 전체를 한 번에 전환하지 않고도 프로덕션에서 검증할 수 있도록 설계되었습니다. 실용적인 순서는 다음과 같습니다:

안정적인 폴백이 정상인지 확인합니다. 대부분의 사용자에게 계속 제공해도 괜찮은 버전이어야 합니다.
후보 번들을 업로드하세요 롤아웃이 설정된 채널로 (bundle upload --channel <name> 도달 및 롤아웃 대상 이탈 ( Stable 폴백 자동 처리) 또는 --rollout <small-percent> 를 사용하여 동일한 단계에서 노출을 활성화하세요.
작게 시작하세요 — 초기 신호를 확인하기에는 1–5%면 충분합니다. 클릭 비율 적용, 그 다음 rollout 활성화실패율이 급증할 때 Capgo가 노출을 중단하도록 하려면 auto-pause를 켜세요.
범위를 넓히기 전에 모니터링하세요. 사용 Observe 버전 상태와 로그 인사이트 에러 패턴을 확인하고, 채널의 History 탭에서 설정 변경 사항을 확인하세요. 롤아웃 대상과 안정적인 fallback 버전을 비교하고, 코호트 상태가 양호할 때까지 퍼센트를 높이지 마세요.
단계적으로 증가 — 퍼센트를 수정하고, 클릭하세요 비율 적용, 단계적으로 확대할 수 있습니다 (예: 5% → 25% → 50% → 100%). Capgo 비율을 높여도 이미 해당 코호트에 포함된 기기는 유지됩니다.
확신이 들면 롤아웃 완료 — 확인 점진적 롤아웃을 완료하시겠습니까? 해당 후보 빌드가 모든 사용자의 안정적인 폴백(fallback)이 됩니다.
문제가 발생하면 먼저 롤아웃 일시 중지 — 조사를 진행하는 동안 새로운 기기 노출을 차단합니다. 문제가 있는 빌드를 사용 중인 기기는 다음 조치 전까지 해당 빌드를 유지합니다. 롤아웃 롤백 또는 Rollout 비활성화.

자동 일시 중지 정책

Capgo는 활성화된 rollout을 5분마다 평가하며, 실패 신호가 설정한 임계값을 넘으면 조치를 취합니다. 선택한 채널과 시간 범위 내에서 rollout 대상의 설치 및 실패 횟수를 측정하며, 단순 실패율이 아닌 Wilson confidence lower bound를 사용하여 판단합니다.

Auto-pause는 기본적으로 비활성화되어 있습니다. 채널의 다음 필드들을 설정하세요. 정보 또는 channel set:

실패율 임계값 bp (500 = 5%). 정책을 실행하려면 임계값이 필요합니다.
기간 분 단위 (기본값: 60).
신뢰도 사이 0 및 1 (기본값: 0.95).
표본 부족으로 인한 오작동을 방지하기 위한 최소 시도 및 실패 횟수(선택 사항).
Cooldown 분(기본값: 60) 동안 유지되며, 반복 작업을 방지합니다.
작업: pause, rollback, 또는 notify.

pause 새로운 롤아웃 노출을 중단하고, rollback 대상을 해제하여 안정적인 폴백 상태로 복구하며, notify 롤아웃 배포는 유지한 채 알림만 전송합니다.

bunx @capgo/cli@latest channel set production com.example.app \
  --auto-pause-enabled \
  --auto-pause-failure-rate-bps 500 \
  --auto-pause-window-minutes 60 \
  --auto-pause-confidence 0.95 \
  --auto-pause-min-attempts 100 \
  --auto-pause-min-failures 5 \
  --auto-pause-action pause \
  --auto-pause-cooldown-minutes 120

API 및 대시보드 진입점

대시보드: 앱 → 채널 → 채널 → 정보 → 점진적 롤아웃
채널 API: 공개 채널 API 롤아웃 필드, 승격, 롤백용
번들 할당 API: PUT /bundle/ 포함 target: auto, stable, 또는 rollout

일반적인 채널 라우팅 및 디바이스 우선순위는 다음을 참조하세요: 채널. 점진적 배포(progressive rollout) 외에 긴급하게 번들을 복구하려면 다음을 참조하세요: live update 롤백하기.