이전 목록으로
#Flutter#Shorebird

Flutter Shorebird 2편: Flavor·Track·QA 운영

Flavor는 앱과 환경을 나누고 Track은 같은 앱의 패치 수신 그룹을 나눈다. 서버 Role과 Feature Flag로 QA 사용자에게 먼저 패치를 전달하는 흐름을 정리한다.

Shorebird 실전 시리즈 2/3 · 1편: Release와 Patch · 3편: 트러블슈팅과 CI

이 글은 2026년 10월 25일 Shorebird 공식 문서를 기준으로 명령과 정책을 확인했다. CLI 옵션은 변경될 수 있으므로 실제 배포 전 공식 문서를 함께 확인하자.

Stage·Prod Flavor를 나눠놓고 Shorebird 문서에서 staging Track을 보니 같은 기능처럼 느껴졌다.

결론부터 말하면 둘은 나누는 대상이 다르다.

구분 Flavor Track
나누는 대상 앱 바이너리와 실행 환경 같은 앱의 패치 수신 그룹
대표 용도 Stage·Prod API와 Bundle ID 분리 QA·Beta·일반 사용자 분리
Shorebird 앱 서로 다른 app_id 사용 가능 같은 app_id와 Release 사용
적용 명령 Release와 Patch 모두 shorebird patch --track

Stage와 Prod가 서로 다른 Flavor와 Shorebird app_id로 완전히 분리되어 있다면 Stage 앱 자체가 QA 채널 역할을 한다. 이 구조에서는 별도의 staging Track이 필수는 아니다.

Track은 동일한 Prod 바이너리 안에서 QA 사용자와 일반 사용자를 나눠야 할 때 필요하다.

Flavor별 Release와 Patch

프로젝트가 다음 진입점을 사용한다고 가정한다.

lib/
├── main.dart
└── main_stage.dart

Android Release

# Stage
shorebird release android \
  --flavor stage \
  --target lib/main_stage.dart \
  --artifact apk

# Production
shorebird release android \
  --flavor prod \
  --target lib/main.dart

Android Patch

# Stage
shorebird patch android \
  --flavor stage \
  --target lib/main_stage.dart \
  --release-version 1.0.0+1

# Production
shorebird patch android \
  --flavor prod \
  --target lib/main.dart \
  --release-version 1.0.0+1

Release 때 사용한 Flavor와 Target은 Patch에서도 그대로 사용한다. Stage Release를 main_stage.dart로 만들고 Patch만 main.dart로 보내면 같은 기준의 수정이라고 보기 어렵다.

Flutter 인자 전달

Shorebird 옵션과 Flutter 옵션은 --로 구분한다.

shorebird release android \
  --flavor prod \
  --target lib/main.dart \
  -- \
  --dart-define=API_ENV=prod

Track은 같은 앱 안에서 사용자를 나눈다

운영 앱을 설치한 사용자 중 사내 QA 계정만 staging Track을 조회하게 만들 수 있다.

QA가 실제 운영 바이너리에서 먼저 패치를 확인하고 문제가 없으면 같은 패치를 stable로 승격한다. Stage 앱에서만 테스트하는 것과는 다른 흐름이다.

flowchart TD
    A[운영 앱 로그인] --> B[서버 계정 Role 조회]
    B --> C{QA 사용자?}
    C -- 예 --> D[staging Track]
    C -- 아니오 --> E[stable Track]
    D --> F[QA 패치 검증]
    F --> G{검증 완료?}
    G -- 예 --> H[stable로 승격]
    H --> E

Shorebird는 QA 기기를 알아서 구분하지 않는다

Shorebird가 “이 기기는 QA용이구나” 하고 판단해주지는 않는다. 사용자 계정도 기기 소유자도 모른다.

앱이 서버 로그인 응답 같은 신뢰할 수 있는 정보로 QA 여부를 결정하고 조회할 Track을 직접 골라야 한다.

final class AppUser {
  const AppUser({required this.roles});

  final Set<String> roles;

  bool get isQaTester => roles.contains('QA_TESTER');
}

QA 이메일이나 전화번호를 앱에 하드코딩하면 회수가 어렵다. 서버가 관리하는 Role이나 Feature Flag를 쓰는 쪽이 운영하면서 바꾸기 쉽다.

자동 업데이트 끄기

기본 자동 업데이트는 stable Track을 조회한다. 사용자 계정에 따라 Track을 선택하려면 자동 업데이트를 끄고 앱에서 수동으로 확인한다.

app_id: your-app-id
auto_update: false

자동 업데이트를 끄면 자유도는 높아지지만 호출 책임도 앱으로 넘어온다. 수동 업데이트 코드를 만들어놓고 실행 시점을 빼먹으면 패치는 내려오지 않는다.

계정에 따라 Track 선택하기

import 'package:shorebird_code_push/shorebird_code_push.dart';

final class AccountPatchService {
  AccountPatchService({ShorebirdUpdater? updater})
      : _updater = updater ?? ShorebirdUpdater();

  final ShorebirdUpdater _updater;

  UpdateTrack _trackFor(AppUser user) {
    return user.isQaTester
        ? UpdateTrack.custom('staging')
        : UpdateTrack.stable;
  }

  Future<bool> downloadIfAvailable(AppUser user) async {
    final track = _trackFor(user);
    final status = await _updater.checkForUpdate(track: track);

    if (status != UpdateStatus.outdated) {
      return false;
    }

    await _updater.update(track: track);
    return true;
  }
}

로그인 완료 후 업데이트를 확인하되, 업데이트 요청 때문에 첫 화면을 막지는 않는다.

void onLoginSucceeded(AppUser user) {
  patchService.downloadIfAvailable(user).then((downloaded) {
    if (!mounted || !downloaded) return;

    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(
        content: Text('업데이트가 준비되었습니다. 앱을 다시 실행해 주세요.'),
      ),
    );
  }).catchError((Object error, StackTrace stackTrace) {
    logger.warning('Shorebird update failed', error, stackTrace);
  });
}

staging Track에 패치 게시하기

shorebird patch android \
  --release-version 1.0.0+1 \
  --track staging

--track을 생략하면 기본값은 stable이다.

로컬에서 특정 Track의 패치를 확인하려면 shorebird preview를 사용할 수 있다.

shorebird preview \
  --app-id your-app-id \
  --release-version 1.0.0+1 \
  --track staging

검증한 패치를 stable로 승격하기

shorebird patches promote \
  --release-version 1.0.0+1 \
  --patch-number 1

다른 Track으로 이동하려면 set-track을 사용한다.

shorebird patches set-track \
  --release-version 1.0.0+1 \
  --patch-number 1 \
  --track beta

승격은 패치를 다시 빌드하는 과정이 아니다. staging에서 검증한 같은 패치를 stable Track으로 옮긴다.

QA 계정에서 일반 계정으로 바꾸면 어떻게 될까

한 번의 업데이트 확인에서는 Track 하나만 본다. staging에 패치가 없다고 stable까지 자동으로 확인하지 않는다.

QA 계정으로 staging 패치를 받은 뒤 일반 계정으로 로그인해도 이미 설치된 패치가 예전 stable로 자동 롤백되지는 않는다.

그리고 앱이 계속 staging만 조회한다면 이후의 stable 전용 패치도 받지 못한다. QA 모드가 끝났다면 다음 확인부터 stable을 명시적으로 선택해야 한다.

Feature Flag를 같이 사용하면 운영하기 편하다.

UpdateTrack selectTrack(AppUser user, bool qaPatchTestingEnabled) {
  if (user.isQaTester && qaPatchTestingEnabled) {
    return UpdateTrack.custom('staging');
  }

  return UpdateTrack.stable;
}

검증이 끝난 뒤 Flag를 끄면 QA 계정도 다시 stable을 조회한다.

QA 구분 방식 비교

조건 적합한 상황 주의점
서버 계정 Role 로그인 기반 업무 앱 명확하고 원격 회수 가능
서버 Feature Flag 사용자·조직별 점진 배포 장애 시 기본값을 stable로 설정
숨겨진 QA 설정 로그인 없는 앱 일반 사용자 노출 방지 필요
설치 경로 감지 내부 배포·TestFlight 플랫폼별 판별이 불안정할 수 있음
Stage Flavor Stage·Prod 앱 완전 분리 같은 Prod 바이너리 검증은 아님

로그인 기반 업무 앱에서는 서버 계정 Role + Feature Flag + 수동 Track 선택 조합이 제일 단순했다.

마무리

Flavor와 Track은 둘 중 하나를 골라야 하는 기능이 아니다.

  • 환경과 바이너리를 나눈다면 Flavor
  • 같은 바이너리의 사용자 그룹을 나눈다면 Track

Stage 앱에서 충분히 검증할 수 있다면 staging Track을 억지로 추가할 필요는 없다. 실제 Prod 바이너리에서 일부 사용자만 먼저 검증해야 할 때 Track의 의미가 생긴다.

다음 편에서는 패치가 안 내려올 때 로그에서 무엇을 확인해야 하는지, Native Changes와 AGP 오류를 어떻게 좁혀야 하는지 정리한다.

관련 문서

목록으로 돌아가기

다른 게시글

#Android#Flutter

현장 Flutter 앱 디버깅에 자주 쓴 ADB 명령어

기기 지정, Logcat, APK 설치, 파일 복사, 포트 reverse를 실기기 점검 흐름으로 정리한다.

#Android#Kotlin

Android 입력 장치 목록 조회하기: 키보드·마우스·HID 스캐너 구분

Android `InputManager`와 `InputDevice` API로 연결된 입력 장치를 조회하고, 키보드·포인터·외부 장치 여부를 판별하는 방법을 정리한다. USB·Bluetooth HID 바코드 스캐너를 일반 키보드와 구분할 때의 한계와 연결 변경 감지 방법도 함께 살펴본다.

#Android#Kotlin

Android 위치 권한과 FusedLocationProvider 실전 정리: 현재 위치·지속 추적·GPS 설정

Jetpack Compose 앱에서 Android 위치 권한을 요청하고, Fused Location Provider로 캐시 위치·일회성 현재 위치·지속 위치 업데이트를 처리하는 흐름을 정리한다. Android 12의 대략적·정확한 위치 선택, 백그라운드 위치 정책, GPS 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.