Pull request preview 삭제는 한 줄 명령어처럼 보입니다. 하지만 Capgo한 가지 주의할 점이 있습니다. 활성 preview에서 벗어나야 삭제할 수 있으며, 이후 ID별로 bundle을 제거해야 합니다. 제한된 API 키, preview 조회, reset 처리, bundle 삭제, CI 자동화를 활용한 안전한 cleanup 플로우를 구성해 보겠습니다.
목차
- 1단계: Preview Cleanup용 제한된 Capgo API 키 생성
- 2단계: Pull Request Preview와 해당 Bundle ID 확인
- 3단계: Cleanup 전에 활성 Preview에서 벗어나기
- 4단계: API 키로 ID별 Preview Bundle 삭제
- 5단계: Pull Request 종료 시 Cleanup 자동화
- 6단계: Cleanup 확인 및 실수로 인한 Rollout 삭제 방지
- 자주 묻는 질문
- 마치며
1단계: Preview Cleanup용 제한된 Capgo API 키 생성
Capgo pull request preview cleanup 플로우의 첫 단계는 CI 작업이 필요한 작업만 수행할 수 있는 키를 만드는 것입니다.
pull request 워크플로에 범위가 넓은 조직 키를 넣지 마세요. pull request는 아직 신뢰를 얻지 못한 브랜치에서 올 수 있습니다. 워크플로가 실패한 실행 중에 명령어나 환경 변수 값을 출력할 수도 있습니다. 범위가 좁은 키는 이런 일이 발생했을 때 피해를 제한합니다.
Capgo에서는 미리보기 작업을 위해 App Preview 키로 시작하세요. 키는 해당 작업이 관리하는 앱 또는 미리보기 범위에 연결되어야 합니다. 팀이 역할 기반 접근 제어(RBAC)를 사용한다면, 조직 전체에 접근 권한을 부여하는 대신 선택된 앱으로만 키 범위를 제한하세요. Capgo은 이러한 미리보기 키 선택 사항을 문서화합니다. 웹 앱 워크플로우용 API 키 설정.
시크릿을 CI 제공자의 암호화 시크릿 저장소에 저장하세요. 용도를 명확히 알 수 있는 이름을 지정하세요. 예를 들어CAPGO_PREVIEW_CLEANUP_KEY와 같이. 워크플로우 파일, 셸 스크립트, 풀 리퀘스트 댓글, 생성된 로그에 시크릿을 포함하지 마세요.
환경 변수를 통해 클리업 프로세스에 키를 전달하세요. 변수가 누락된 경우 스크립트가 실패하도록 설정해야 합니다. 조용한 폴백은 인증 없이 요청을 보내거나 개발자가 커맨드 라인에 키를 붙여넣게 만드는 위험한 상황이 될 수 있습니다.
if [ -z "$CAPGO_PREVIEW_CLEANUP_KEY" ]; then echo "Missing preview cleanup key" exit 1
fi이 키는 프로덕션 번들을 게시하는 데 사용되는 키와 분리하세요. 게시 작업은 릴리스 업로드가 필요할 수 있습니다. 클리업 작업은 미리보기 리소스 제거에만 필요합니다. 키를 분리하면 리뷰가 쉬워지고 삭제 작업이 프로덕션 채널에 도달할 가능성을 줄일 수 있습니다.
가능하다면 보호된 환경에서 동일한 시크릿을 사용하세요. 작업이 공유 채널에 접근하려면 승인 절차를 요구하세요. 일반적인 풀 리퀘스트 미리보기의 경우, 작업은 임시 채널에서만 작동해야 하며 다른 채널에는 접근하지 않아야 합니다.
핵심 요약: 전용 App Preview 키를 사용하고, 앱 범위를 제한하며, 암호화된 CI 시크릿에 보관하세요.
진행하기 전에, 무해한 읽기 작업으로 키를 테스트하세요. 해당 작업이 의도된 앱은 볼 수 있지만, 관련 없는 앱이나 프로덕션 워크플로우에는 접근할 수 없는지 확인하세요. 정리 작업의 정확한 요청 세부사항은 완전히 공개되어 있지 않으므로, 삭제 호출을 추가하기 전에 첫 테스트는 작게 유지하고 SDK 또는 Capgo 지원 가이드를 검토하세요.
2단계: Pull Request Preview와 해당 Bundle ID 확인
Capgo pull request preview cleanup API 키는 작업이 자신이 소유한 preview와 bundle ID를 정확히 알고 있을 때만 유용합니다.
preview 채널에 대해 안정적인 네이밍 규칙을 사용하세요. 일반적인 패턴은 저장소 이름에 pull request 번호를 더하는 것입니다. 핵심은 일관성입니다. pull request가 닫힌 후에도 cleanup 작업이 동일한 식별자를 재구성할 수 있어야 합니다.
preview가 생성될 때 preview 채널 이름을 저장하세요. 워크플로우 출력, pull request 체크, 또는 작은 작업 메타데이터 조각에 저장할 수 있습니다. 대시보드에서 사람이 변경할 수 있는 표시 이름에 의존하지 마세요.
다음으로, 해당 preview에 연결된 bundle 목록을 가져오세요. Capgo의 Delete Bundle 액션은 bundle ID가 필요합니다. 소스 문서에는 삭제 전에 사용 가능한 모든 bundle ID를 가져오기 위한 list 호출을 가리키고 있습니다. 그 list를 진실의 원천(source of truth)으로 취급하세요. 파일 이름, 커밋 해시, 또는 브랜치 이름에서 ID를 추측하지 마세요.
반환된 레코드를 preview 채널 또는 워크플로우에서 제어하는 다른 값으로 필터링하세요. 그런 다음 일치하는 각 항목의 정확한 bundle ID를 유지하세요. 목록이 비어 있으면 cleanup을 완료로 표시하세요. 워크플로우에서 preview가 존재해야 하는 경우가 아니라면 빈 결과는 실패가 아닙니다.
또한 각 preview를 생성한 commit SHA를 기록하세요. 이는 삭제 전 두 번째 확인이 됩니다. 채널 이름은 일치하지만 commit이 일치하지 않으면, 중단하고 검토를 요청하세요. 이 짧은 멈춤이 이전 cleanup 작업이 실행되는 동안 새 preview가 빌드되는 race condition을 막을 수 있습니다.
Publish job이 아직 실행 중일 때는 삭제하지 마세요. Preview build와 cleanup workflow 사이에 의존성을 추가하거나, pull request 번호를 키로 하는 lock을 사용하세요. Cleanup job은 close event가 발생하고 대기 중인 preview upload가 모두 끝난 뒤에만 시작되어야 합니다.
Capgo의 공개 API은 인증된 HTTP 요청으로 channel, bundle 같은 리소스를 다루지만, 프로젝트의 cleanup 작업은 여전히 꼼꼼히 검증해야 합니다. Capgo 공개 API 개요 wrapper를 작성하기 전에 현재 리소스 모델을 확인하기에 가장 적합한 곳입니다.
이제 preview identifier, 정확한 bundle ID 목록, 각 레코드에 연결된 commit SHA를 가지고 있어야 합니다. 이 값 중 하나라도 빠져 있다면 여기서 멈추세요. 소유권 확인 없이 하는 cleanup은 추측일 뿐입니다.
3단계: Cleanup 전에 활성 Preview에서 벗어나기
앱이 활성 preview에서 벗어나거나 호출하기 전까지는 활성 preview를 삭제할 수 없습니다.resetPreview이것이 Capgo pull request preview cleanup 흐름의 핵심 포인트입니다.
활성 preview는 앱이 현재 선택한 버전이라고 생각하세요. 서버 측 레코드를 먼저 삭제하면 앱이 더 이상 존재하지 않는 대상을 가리키게 됩니다. Capgo은 그 상태 변경을 차단하므로, cleanup job은 preview를 제거하기 전에 앱의 preview 상태를 리셋해야 합니다.
먼저 프리뷰가 여전히 활성 상태인지 확인하세요. 활성 상태라면 앱을 안전한 채널로 이동하거나 updater reset 작업을 사용하세요. 올바른 선택은 테스트 앱 구성 방식에 따라 달라집니다. 일회용 테스트 앱은 기본 채널로 되돌릴 수 있습니다. 공유 테스트 앱은 전용 스테이징 채널이 필요할 수 있습니다.
사용resetPreview프리뷰 상태를 직접 해제해야 할 때입니다. 이 호출은 프리뷰를 생성한 동일한 pull request와 앱에 연결해야 합니다. 채널 이름이 우연히 일치한다는 이유만으로 프로덕션 기기나 공유 릴리스 채널을 리셋하는 것은 절대 금지됩니다.
여기 유용한 순서 규칙이 있습니다:
- pull request가 닫혔는지 확인하세요.
- 프리뷰 업로드가 실행 중이지 않은지 확인하세요.
- 활성 프리뷰에서 벗어나거나 호출하세요
resetPreview. - 해당 상태 변경이 완료될 때까지 기다리세요.
- 그 후에만 Delete Preview를 호출하세요.
리셋 요청의 HTTP 응답이 성공했다고 해서 모든 기기에서 앱 상태가 이미 바뀌었다고 단정하지 마세요. 기기는 나중에 업데이트를 확인할 수 있습니다. API 응답에 따라 미리보기 할당이 해제되면 서버 측 정리 작업은 계속 진행할 수 있지만, 기기 동작과 리소스 삭제는 분리해 두세요.
Capgo는 채널 기반 롤아웃 제어를 지원하므로 이런 분리를 더 쉽게 이해할 수 있습니다. 채널은 앱이 따라야 할 업데이트 스트림을 알려주는 이름이 붙은 경로입니다. 미리보기 채널은 프로덕션 기기에서 사용하는 채널과 같아서는 안 됩니다.
더 엄격한 경계가 필요한 팀은 문서화된 Capgo 채널 워크플로우를 미리보기 자동화에 사용하세요. 이 문서는 임시 채널 패턴을 설명하고, 정리 작업을 공유 기본 채널과 분리하는 데 도움이 됩니다.
오픈소스 업데이터 문서에도 삭제 제한이 기록되어 있습니다: 활성 미리보기는 먼저 다른 채널로 전환하거나 리셋해야 합니다. Capgo Capacitor 업데이터 저장소에서 소스를 검토할 수 있습니다. 대시보드 문구가 CI 결정을 내리기에 너무 간략할 때 이 소스가 유용합니다.
유용한 팁: 리셋을 로그가 남는 별도 단계로 만드세요. Delete Preview가 실패하면 로그에 미리보기가 여전히 활성 상태였는지, 아니면 삭제 요청에 다른 문제가 있었는지 표시되어야 합니다.
활성 상태가 사라지면 미리보기 레코드를 삭제할 준비가 된 것입니다. 리셋과 삭제를 하나의 불투명한 셸 명령으로 합치지 마세요. 명확한 명령 두 개는 재시도하기 쉽고 감사하기도 훨씬 쉽습니다.
4단계: API 키로 ID별 Preview Bundle 삭제
활성 미리보기가 리셋된 후, 각 미리보기 번들을 정확한 ID로 삭제합니다. 이 단계에서 Capgo 정리 키가 풀 리퀘스트가 남긴 스토리지 객체를 제거합니다.
2단계의 번들 목록부터 시작합니다. 일치하는 각 ID에 대해 Capgo SDK 또는 계정에서 사용할 수 있는 현재 공개 API 메서드로 Delete Bundle 작업을 호출합니다.
SDK 메서드 시그니처를 확인하거나 Capgo 지원팀에 현재 요청 형식을 문의하세요. 확인한 뒤에는 메서드와 응답 형식을 팀 내부 런북에 기록하세요. 런북에는 API 버전, 필수 식별자, 재시도 로직이 처리할 수 있는 오류 코드를 포함해야 합니다.
스크립트에서 dry-run 모드를 사용하세요. 삭제 요청을 보내지 않고 삭제할 미리보기 채널과 번들 ID만 출력해야 합니다. 이 모드를 닫힌 풀 리퀘스트 여러 개에 대해 실행해 보세요. 프로덕션 채널이 제외되는지, 빈 목록이 와일드카드로 처리되지 않는지 확인하세요.
안전한 삭제 루프에는 세 가지 게이트가 있습니다:
- 누락되거나 형식이 잘못된 번들 ID를 거부합니다.
- 풀 리퀘스트 미리보기와 채널이 일치하지 않는 번들을 거부합니다.
- 소유권 확인이 통과된 후에만 삭제합니다.
이후 응답 유형별로 처리하세요. 삭제 성공은 완료로 기록할 수 있습니다. 리소스가 이전 재시도에서 이미 삭제된 것으로 확인된 경우, not-found 응답은 이미 정리된 것으로 간주할 수 있습니다. 권한 오류는 작업을 실패 처리하고 소유자에게 알림을 보내야 합니다. Rate limit은 지연 시간을 상한으로 설정하고 일시 정지 후 재시도해야 합니다.
모든 오류를 재시도하지 마세요. 잘못된 ID는 세 번 시도해도 유효해지지 않습니다. 인증 오류는 보통 키 스코프가 잘못되었음을 의미합니다. 일시적인 실패만 재시도하고, 막힌 cleanup 작업이 CI 큐를 점유하지 않도록 최대 실행 시간을 설정하세요.
Bundle 삭제는 preview 삭제와 별개입니다. Preview 채널을 제거한다고 해서 모든 bundle이 삭제된 것이 보장되지 않습니다. 작업은 각 ID에 대한 결과를 유지해야 하며, API이 이를 지원한다면 최종 목록 요청을 수행해야 합니다. 남아 있는 bundle이 있으면 ID를 보고하고 중단해야 하며, 성공을 조용히 주장해서는 안 됩니다.
삭제 로그에는 시크릿이 포함되지 않도록 하세요. Pull request 번호, preview 이름, bundle ID, 요청 결과, 타임스탬프를 기록하는 것은 괜찮습니다. API 키, 인증 헤더, 또는 이러한 정보가 포함될 수 있는 전체 요청 객체를 절대 기록하지 마세요.
이 접근 방식은 자격 증명이 누출될 수 있는 또 다른 장소로 로그를 만들지 않으면서도 유용한 감사 추적을 제공합니다. 또한 다음 실행에서 이미 부재로 확인된 기록을 건너뛸 수 있으므로 실패한 cleanup을 쉽게 재개할 수 있습니다.
5단계: Pull Request 종료 시 Cleanup 자동화
pull request close 이벤트에서 cleanup job을 실행하되, 지연된 빌드가 새 preview를 삭제하지 않도록 검증 로직을 추가합니다.
workflow는 이벤트 payload에서 repository와 pull request 번호를 받아야 합니다. 이 값들로 preview channel 이름을 다시 구성하세요. pull request 댓글이나 신뢰할 수 없는 브랜치 변수에서 제공하는 channel 이름은 받아들이지 마세요.
유용한 job 순서는 다음과 같습니다:
- 암호화된 secrets에서 제한된 cleanup key를 로드합니다.
- 이벤트가 closed pull request인지 확인합니다.
- preview가 예상한 repository와 app에 속하는지 확인합니다.
- 진행 중인 preview deployment가 완료될 때까지 대기합니다.
- preview에서 다른 채널로 전환하거나 호출합니다.
resetPreview. - 해당 preview의 bundle ID를 나열합니다.
- 검증된 bundle을 각각 삭제합니다.
- preview 레코드를 삭제합니다.
- workflow summary에 간단한 결과를 기록합니다.
순서가 중요합니다. 먼저 삭제하면 활성 preview 규칙이 요청을 차단할 수 있습니다. list 호출을 건너뛰면 어떤 bundle ID가 여전히 존재하는지 알 수 없습니다. 추측한 이름으로 삭제하면 잘못된 리소스를 건드릴 위험이 있습니다.
pull request 번호를 키로 사용하는 concurrency 규칙을 사용하세요. close 이벤트와 rebuild 이벤트가 거의 동시에 도착하면, 오래된 cleanup job이 새로운 deployment와 경쟁(race)하지 않도록 해야 합니다. 더 이상 유효하지 않은 cleanup 실행을 취소하거나, deployment lock이 해제될 때까지 job이 대기하도록 설정하세요.
Capgo의 원커맨드 CLI 워크플로는 build 및 release 작업 주변의 커스텀 shell 호출 횟수를 줄일 수 있습니다. 커맨드 이름과 지원되는 작업에 대해서는 Capgo CLI 커맨드 문서를 확인하세요. 검증된 커맨드를 제공하는 경우 CLI를 사용하세요. cleanup 작업에 직접 요청이 필요한 경우 SDK 또는 공개 API를 사용하세요.
모든 push마다 실행되는 워크플로에 cleanup을 넣지 마세요. push job이 아직 테스트 중인 preview를 삭제할 수 있습니다. 일반적인 cleanup에는 close 이벤트가 올바른 트리거입니다. job 실패 시 복구용 수동 workflow dispatch를 추가하세요.
retention 폴백도 설정하세요. close 이벤트를 놓쳤을 경우, 예약된 job이 팀의 허용 테스트 기간을 초과한 preview를 찾을 수 있습니다. 이 job은 일반적인 close hook보다 더 엄격한 안전 장치가 필요합니다. 명확한 소유자와 만료된 timestamp를 가진 preview만 선택해야 합니다.
GitHub Actions의 경우 권한을 최소한으로 유지하고 cleanup 단계에 필요한 값만 전달하세요. Capgo의 현재 GitHub Actions 통합 문서에서 토큰이 저장되는 위치와 워크플로우가 Capgo에 연결되는 방식을 설명합니다.
이제 close에 반응하고, 경쟁하는 job을 기다리며, 활성 상태를 초기화하고, ID를 나열한 뒤 일치하는 bundle만 삭제하는 자동화 경로가 갖춰져 있어야 합니다. 이 정도면 cleanup이 무작정 쓸어버리는 작업이 되지 않으면서 일상 개발에 충분히 빠릅니다.
6단계: Cleanup 확인 및 실수로 인한 Rollout 삭제 방지
검증은 Capgo pull request preview cleanup 루프를 마무리합니다. 안전한 릴리스 프로세스에는 삭제 응답만으로는 부족합니다.
cleanup 작업이 실행된 후 preview 채널을 다시 확인하세요. 더 이상 활성 preview로 표시되지 않는지 확인합니다. 그런 다음 동일한 앱과 필터로 bundle 목록을 확인하세요. 대상 bundle ID는 사라지고 프로덕션 bundle은 남아 있어야 합니다.
이 값들을 job summary에 저장하세요:
- 레포지토리와 pull request 번호.
- preview 채널 이름.
- 소유권 확인에 사용된 Commit SHA.
- 발견된 Bundle ID.
- 삭제된 Bundle ID.
- 에러를 반환한 ID.
명확한 상태를 사용하세요. “Cleaned”는 모든 검증된 대상이 제거되었음을 의미합니다. “Already clean”은 이번 실행 전에 리소스가 이미 없었음을 의미합니다. “Needs review”는 하나 이상의 체크가 실패했음을 의미합니다. 부분 삭제를 성공으로 표시하지 마세요.
code에 프로덕션 가드를 추가하세요. 기본 채널이나 릴리스 채널과 같은 채널 이름을 거부하세요. 메타데이터가 프리뷰 앱과 일치하지 않는 번들도 거부하세요. 가드는 실패 시 안전하게 차단(fail closed)되어야 합니다. 스크립트가 대상을 확신할 수 없으면 중단해야 합니다.
롤백과 클리너업을 분리하세요. 롤백은 디바이스가 받는 번들을 변경합니다. 클리너업은 오래된 프리뷰 리소스를 제거합니다. 풀 리퀘트가 닫힌 후 테스트에서 버그가 발견되면 조사에 번들이 필요할 수 있습니다. 팀이 머지 후 디버깅을 자주 한다면 이벤트가 도착하자마자 삭제하는 대신 짧은 보존 기간을 설정하세요.
세 가지 일반적인 실패 패턴을 주의하세요:
- 활성 프리뷰 오류: Delete Preview를 재시도하기 전에 리셋하거나 다른 곳으로 전환하세요.
- 번들 ID 누락: 추측하지 말고 list 작업을 다시 실행하세요.
- 권한 오류: 키 범위를 검토한 후 필요하면 새 키를 발급하세요.
보안 정책에서 설정한 일정대로 클리너업 키를 순환하고, 로그나 커밋에 노출된 경우 즉시 순환하세요. 노출로 인한 즉각적인 폐기가 필요한 경우를 제외하고, 기존 키를 폐기하기 전에 새 키를 테스트해야 합니다.
cleanup 관련 문서 공백은 보안 검토에서 메모해 둘 만합니다. 구현 기준은 SDK와 검증된 Capgo 가이드로 삼고, 자체 요청 컨트랙트는 버전 관리하에 두세요.
핵심 요약: 삭제 후 프리뷰와 번들 목록을 확인하고, code에서 프로덕션 타깃을 차단하며, 부분 cleanup은 실패로 보고하세요.
명령 하나가 유용하려면 가드레일이 명확해야 합니다. 프리뷰를 추적하세요. 예측 가능한 채널 이름을 사용하세요. 릴리스 변경은 별도로 롤백하세요. 그런 다음 cleanup job이 라이브 트래픽을 건드리지 않고 제 역할만 하도록 두세요.
자주 묻는 질문
활성 Capgo Pull Request Preview를 삭제할 수 있나요?
아니요. 활성 프리뷰에서 먼저 다른 채널로 전환하거나, 다음을 호출해야 합니다.resetPreview. 활성 상태가 해제된 후 Delete Preview를 실행하세요. 이 규칙은 CI에서 Capgo pull request preview cleanup API 키를 설정할 때 꼭 기억해야 할 핵심입니다.
Capgo Preview를 정리하려면 Bundle ID가 필요한가요?
네. Capgo의 Delete Bundle 액션은 번들 ID가 필요하므로, 삭제 전에 사용 가능한 번들 목록을 조회하세요. 각 ID를 프리뷰 채널 및 커밋과 매칭한 뒤 삭제 요청을 보내세요. 브랜치 이름으로 ID를 만들거나, 프리뷰를 삭제하면 모든 번들도 삭제된다고 가정하지 마세요.
Preview Cleanup에 CI가 사용해야 하는 API 키는 어떤 종류인가요?
preview cleanup에는 CI 제공업체의 암호화된 secret store에 저장한 권한이 제한된 App Preview key를 사용하세요. key는 필요한 앱이나 scope로만 제한하세요. 프로덕션 업데이트 게시에 쓰는 key와는 분리하세요. 이렇게 하면 Capgo cleanup 작업을 검토하기 쉽고 key를 rotate하기도 더 안전합니다.
Pull Request가 닫힐 때 Cleanup을 자동화할 수 있나요?
네. closed pull request 이벤트에서 cleanup을 트리거한 다음, preview를 리셋하기 전에 활성 deployment job이 끝날 때까지 기다리세요. bundle ID를 나열하고 검증된 일치 항목을 삭제한 뒤 결과를 확인하세요. 늦게 실행된 build가 cleanup job과 경쟁하지 않도록 concurrency controls를 추가하세요.
왜 Capgo Cleanup 요청이 실패하나요?
주요 원인은 활성 preview, bundle ID 누락, 또는 필요한 scope가 없는 key입니다. 먼저 preview를 리셋하고 list 호출을 반복한 뒤 key 권한을 확인하세요. 요청 세부 사항은 API 또는 SDK 버전에 따라 다를 수 있으므로, 스크립트를 수정하기 전에 현재 method와 parameter를 확인하세요.
마치며
전용 preview key와 엄격한 cleanup 순서로 Capgo를 사용하세요. 순서는 활성 preview 리셋, bundle ID 목록 조회, 검증된 bundle 삭제, 마지막으로 preview 제거입니다. 하나의 closed pull request를 대상으로 dry run을 실행해 현재 SDK에서 요청 형식을 확인하고, 자동 cleanup을 켜기 전에 production-channel 가드를 추가하세요.
