모든 Pull Request를 설치 가능한 프리뷰로 전환하세요

모든 모바일 개발 팀이 겪는 고충이 있습니다. 기능 개발은 끝났는데, 이해관계자들에게 보여주려면 TestFlight나 Google Play 베타 리뷰라는 미로를 통과해야 하죠. 단 몇 분이면 될 일이 베타 빌드를 기다리고, 설치하고, 관리하는 데 몇 시간씩 걸리곤 합니다.

만약 앱을 재설치하거나 앱 스토어의 승인을 기다릴 필요 없이, 프로덕션 앱에서 모든 Pull Request의 최신 변경 사항을 기기에 직접 가져올 수 있다면 어떨까요?

그것이 바로 PR 프리뷰입니다 활성화하세요. 개발자가 pull request를 생성하면 GitHub Action이 전용 update channel을 만들고 변경 사항을 게시합니다. 앱이 설치된 사용자라면 누구나 해당 channel로 전환하여 기능을 테스트하고 다시 원래대로 돌아올 수 있습니다. 이 모든 과정은 기존 앱을 벗어나지 않고도 가능합니다.

TestFlight의 문제점

모바일 기능을 테스트하는 기존 워크플로우는 다음과 같습니다:

개발자가 PR 생성 - Code 리뷰 준비 완료
TestFlight 대기 - 15~30분 정도의 처리 시간 소요
빌드 찾기 및 설치 - 테스터가 적절한 빌드를 검색
테스트 및 반복 - 변경할 때마다 다시 대기

이는 병목 현상을 초래합니다. QA는 빌드를 기다리느라 업무가 중단되고, PM은 기능을 빠르게 검증할 수 없습니다. 개발자는 피드백을 기다리는 동안 작업 맥락을 놓치게 됩니다. 업계에서는 이로 인한 생산성 손실이 PR당 약 $340에 달하는 것으로 추정합니다.

PR Preview 작동 방식

PR preview는 Capgo의 channel 시스템을 사용하여 PR별 업데이트 스트림을 생성합니다. 전체 흐름은 다음과 같습니다:

PR 생성 또는 업데이트 - GitHub Action 실행
Bundle upload 완료 - JS/CSS 변경 사항이 PR 전용 channel로 전송됨
댓글 게시 - PR 내에 테스터용 가이드 제공
즉시 테스트 가능 - channel 전환 후 테스트, 다시 복구

새 앱 설치나 TestFlight 대기 시간이 필요 없습니다. 동일한 production 앱에서 서로 다른 update channel을 불러올 수 있습니다.

PR Preview 설정하기

PR preview를 구현하기 전에 프로젝트에 Capgo Live Updates 설정이 완료되어 있어야 합니다. 아직 설정 전이라면 다음 단계를 Capgo 퀵스타트 가이드 따라 진행해 주세요.

GitHub Actions 워크플로우

생성 .github/workflows/pr-preview.yml:

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install Dependencies
        run: bun install

      - name: Build
        run: bun run build

      # Create a channel named after your PR (may already exist on synchronize)
      - name: Create PR Channel
        id: create_channel
        continue-on-error: true
        run: bunx @capgo/cli@latest channel add pr-${{ github.event.pull_request.number }} --self-assign
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

      # Upload the build to that channel
      - name: Upload to Capgo
        run: bunx @capgo/cli@latest bundle upload --channel pr-${{ github.event.pull_request.number }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

      # Post a comment with testing instructions (only on PR open)
      - name: Comment on PR
        if: github.event.action == 'opened'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: ${{ github.event.pull_request.number }},
              body: '📱 **Test this PR on device:**\n\nOpen your app and switch to channel: `pr-${{ github.event.pull_request.number }}`\n\nUse the shake menu or call `setChannel()` from your app.'
            })

핵심은 채널 생성 시 --self-assign flag when creating the channel. This enables testers to switch to the channel from within the app using the setChannel() API.

Capgo Token 설정하기

다음으로 이동하세요: Capgo 대시보드
Settings > API Keys로 이동하세요
다음 명령으로 새 키 생성: all 권한
다음 이름으로 추가: CAPGO_TOKEN GitHub 저장소 secrets에

테스터의 채널 전환 방법

테스터가 PR 채널로 전환하는 방법은 두 가지가 있습니다:

Capacitor 설정에서 채널 선택 기능이 포함된 shake menu를 활성화하세요:

// capacitor.config.ts
const config: CapacitorConfig = {
  // ... your other config
  plugins: {
    CapacitorUpdater: {
      shakeMenu: true,
      allowShakeChannelSelector: true
    }
  }
};

테스터가 기기를 흔들면 디버그 메뉴가 열리며, 검색 바와 함께 사용 가능한 채널 목록이 표시됩니다. 해당 PR 채널(예: pr-123)을 찾아 탭하면 앱이 자동으로 업데이트를 다운로드하고 적용합니다. 테스트가 끝나면 다시 기기를 흔들어 production 채널로 전환하면 됩니다.

shake menu가 전체 흐름을 자동으로 처리합니다:

다음을 통해 모든 self-assignable 채널을 가져옵니다: listChannels()
검색으로 특정 PR을 찾을 수 있는 채널 목록을 표시합니다
선택 후 업데이트를 다운로드합니다
“지금 다시 로드” / “나중에” 옵션과 함께 재로드 prompt를 띄웁니다

옵션 2: 커스텀 채널 선택 UI

사용 가능한 PR 채널을 나열하고 테스터가 하나를 고를 수 있는 채널 스위처를 앱에 구축하세요. 두 가지 핵심 API를 사용합니다:

listChannels() - self-assignment가 활성화된 모든 채널을 가져옵니다
setChannel() - 기기를 선택한 채널로 전환합니다

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Get all available channels (including PR channels)
async function getAvailableChannels() {
  const { channels } = await CapacitorUpdater.listChannels();

  // Filter to show only PR channels
  const prChannels = channels.filter(c => c.name.startsWith('pr-'));

  return prChannels;
}

// Switch to a specific PR channel
async function switchToChannel(channelName: string) {
  await CapacitorUpdater.setChannel({
    channel: channelName,
    triggerAutoUpdate: true  // Immediately check for updates
  });
}

// Return to production
async function switchBackToProduction() {
  await CapacitorUpdater.unsetChannel({});
}

// Get current channel
async function getCurrentChannel() {
  const { channel } = await CapacitorUpdater.getChannel();
  return channel;
}

이 구성 요소들을 활용하면 간단한 UI를 만들 수 있습니다:

// Example: List PR channels and let user select
const channels = await getAvailableChannels();
const current = await getCurrentChannel();

// Display channels in your UI
channels.forEach(channel => {
  console.log(`${channel.name} ${channel.name === current ? '(current)' : ''}`);
});

// When user selects a channel
await switchToChannel('pr-123');

전체 React 컴포넌트 예시는 다음을 참고하세요: 채널 서핑 아티클.

PR 채널 정리하기

PR이 머지되거나 닫히면 해당 채널을 정리해야 합니다. 워크플로우를 하나 더 추가하세요:

name: Cleanup PR Preview
on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Delete PR Channel
        run: bunx @capgo/cli@latest channel delete pr-${{ github.event.pull_request.number }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

PR이 종료되면 채널이 자동으로 삭제되어 채널 목록을 깔끔하게 유지할 수 있습니다.

버전 호환성

PR 프리뷰는 JavaScript bundle이 설치된 native 버전과 호환될 때만 작동합니다. PR에 native code 변경 사항(새로운 Capacitor 플러그인, iOS/Android 수정 등)이 포함된 경우, 테스터는 새로운 Native Build가 필요합니다.

Capgo가 버전 호환성을 자동으로 확인합니다. PR의 bundle이 설치된 native 버전과 다를 경우 업데이트가 적용되지 않습니다. 이를 통해 호환되지 않는 code로 인한 크래시를 방지합니다.

native 변경이 필요한 PR의 경우, 새로운 TestFlight/Play Store build를 배포해야 합니다. PR 프리뷰는 native code를 건드리지 않는 JavaScript, CSS, asset 변경 사항에 가장 적합합니다.

PR 프리뷰의 장점

QA 엔지니어

PR 생성 즉시 기능 테스트 가능
재설치 없이 여러 PR 간 전환 가능
실제 기기에서 수정 사항 및 회귀 테스트 검증
TestFlight 처리 대기 시간 불필요

프로덕트 매니저

머지 전 미리 기능 검토
PR에서 직접 피드백 전달
구현 사항이 요구사항과 일치하는지 확인
리뷰 사이클 시간 단축

개발자

변경 사항에 대한 빠른 피드백 확보
스테이크홀더에게 즉시 기능 데모
특정 사용자의 이슈 디버깅
베타 빌드 관리 시간 절약

기존 방식 vs PR Preview 비교

항목	TestFlight/Beta 버전	Capgo PR 프리뷰
빌드 타임	15-30분	<1분
PR 전환	5분 이상 재설치	10초
설정 복잡도	App Store 인증 정보	워크플로 파일 1개
정리	수동	자동
Native code 변경 사항	필수	선택 사항 (JS 전용)

모범 사례

채널 이름 명확히 지정하기: pr-{number} 식별이 쉬운 명명 규칙 사용
자동 정리: PR 종료 시 항상 채널 삭제
액세스 제한: debug/staging 빌드에서만 shake menu 활성화
프로세스 문서화: PR 템플릿에 테스트 방법 추가
실패를 우아하게 처리하기: 댓글을 달기 전 채널 생성이 성공했는지 확인

PR Preview를 사용하지 말아야 할 때

PR preview는 JavaScript/CSS 변경 사항을 위한 것입니다. 만약 PR에 다음 내용이 포함된다면:

새로운 Capacitor 플러그인
iOS 네이티브 code 변경 사항
Android 네이티브 code 변경 사항
Native Build에 영향을 주는 의존성 업데이트

해당 변경 사항은 TestFlight 또는 Play Store를 통한 기존 배포 방식이 필요합니다.

Channel Surfing과 함께 활용하기

PR 프리뷰는 다음 기능과 함께 사용할 때 가장 효과적입니다 채널 서핑. 앱에서 다음을 지원할 수 있습니다:

production - 모든 사용자를 위한 안정적인 릴리스
beta - 옵트인 사용자를 위한 얼리 액세스
pr-123 - 특정 PR용 기능 프리뷰

프로덕션 빌드가 설치된 테스터는 동일한 앱에서 원하는 PR 채널로 전환해 기능을 테스트하고 다시 원래 채널로 돌아올 수 있습니다.

리소스

마치며

PR 프리뷰는 팀의 모바일 기능 리뷰 및 테스트 방식을 혁신합니다. TestFlight 처리 과정을 기다리거나 여러 베타 빌드를 관리할 필요 없이, 테스터는 이미 설치된 앱을 사용하여 단 몇 초 만에 원하는 PR 채널로 전환할 수 있습니다.

설정은 매우 간단합니다. 단 하나의 GitHub Actions 워크플로우 파일만 있으면 되며, 그 효과는 팀 전체로 확산됩니다. QA는 중단 없이 업무를 진행하고, PM은 더 빠르게 리뷰하며, 개발자는 즉각적인 피드백을 받을 수 있습니다.

먼저 하나의 레포지토리에 워크플로우를 추가하여 리뷰 프로세스가 어떻게 변화하는지 직접 경험해 보세요.

‘모든 Pull Request를 설치 가능한 Preview로 만들기’에서 이어서 보기

사용 중이라면 모든 Pull Request를 설치 가능한 프리뷰로 전환하세요 채널 라우팅과 단계적 배포를 계획하려면, 다음을 연결하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: Beta Testing 솔루션 Beta Testing 솔루션의 제품 워크플로우를 위한, 그리고 버전 타겟팅 솔루션 Version Targeting Solution의 제품 워크플로우용.