이전 목록으로
#Flutter#Shorebird

Flutter Shorebird 3편: 패치 미적용과 CI 트러블슈팅

패치가 적용되지 않거나 Native Changes 경고가 나타날 때 app_id, Release 버전, pubspec.lock, 빌드 환경과 GitHub Actions 인증을 점검하는 순서를 정리한다.

Shorebird 실전 시리즈 3/3 · 1편: Release와 Patch · 2편: Flavor·Track·QA 계정 구분

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

Shorebird 명령어 자체는 몇 개 안 된다. 어려웠던 건 Release와 Patch 사이의 환경을 똑같이 유지하는 일이었다.

패치가 안 내려오면 이것저것 다시 빌드하기 전에 범위를 하나씩 줄여야 한다. 먼저 설치된 앱을 확인하고, 그다음 Shorebird 식별값, 변경사항, 빌드 환경 순서로 본다.

1. Shorebird Release로 만든 앱인가

일반 flutter build로 만든 앱은 Shorebird 패치를 받을 수 없다.

shorebird release android

일반 Release 앱과 Shorebird Release 앱은 기기에서 둘 다 잘 실행되기 때문에 헷갈린다.

기기 로그에서 [shorebird] 접두어가 하나도 보이지 않는다면 현재 앱이 Shorebird Release로 만들어졌는지 확인한다.

실제 패치 검증은 Shorebird Release 기반의 Release Mode 앱에서 수행한다. IDE에서 실행한 Debug 앱을 보고 패치가 안 온다고 하면 답이 안 나온다.

2. 앱을 완전히 두 번 실행했는가

기본 자동 업데이트는 첫 실행에서 패치를 다운로드하고 두 번째 실행부터 적용한다.

  1. 앱 실행
  2. 패치 다운로드 확인
  3. 프로세스 완전 종료
  4. 앱 다시 실행

백그라운드로 보냈다가 다시 여는 것만으로는 새 패치로 부팅되지 않을 수 있다.

3. 로그의 식별값 확인

[shorebird] Sending patch check request
app_id: "..."
channel: "stable"
release_version: "1.0.0+1"
platform: "android"
arch: "aarch64"

로그에서 다음 값을 확인한다.

  • app_id가 현재 Flavor의 Shorebird 앱 ID와 같은가?
  • release_version이 패치를 올린 Release와 같은가?
  • Track이 stable, staging, beta 중 의도한 값인가?
  • 현재 CPU Architecture용 Release Artifact가 있는가?

앱 화면에는 Stage라고 적혀 있는데 Shorebird 로그는 Prod app_id를 보내는 경우도 있다. 화면 표시보다 실제 요청 로그를 믿는 편이 낫다.

shorebird releases list
shorebird releases info --release-version 1.0.0+1

4. Native Changes 경고

Dart만 수정했다고 생각했는데 다음 경고가 나타날 수 있다.

Your app contains native changes, which cannot be applied with a patch.
Changed files:
  base/dex/classes.dex

주요 원인은 다음과 같다.

  1. pubspec.lock의 네이티브 플러그인 버전이 달라졌다.
  2. Release 이후 pubspec.yaml 의존성이 변경됐다.
  3. 플러그인이 빌드할 때마다 다른 결과를 생성한다.
  4. Release와 Patch의 Flutter·JDK·Gradle·Xcode 환경이 다르다.
  5. Release와 Patch의 버전 또는 빌드 번호가 다르다.

확인 명령어

git diff -- pubspec.yaml pubspec.lock
flutter pub deps --style=compact
shorebird doctor
flutter --version
java -version
./gradlew -version

lock 파일 그대로 설치하기

flutter pub get --enforce-lockfile

애플리케이션 프로젝트에서는 pubspec.lock을 형상관리하는 편이 좋다. Release 당시의 실제 의존성 버전을 남겨야 Patch에서도 같은 결과를 재현할 수 있다.

원인을 모르는 상태에서 --allow-native-diffs부터 붙이지 않는다. 왜 안전한지 설명할 수 없다면 새 Release를 만드는 편이 낫다.

5. Android 의존성·AGP 오류

Shorebird 명령을 실행하다가 아래 오류가 나오면 Shorebird 자체 문제처럼 보인다.

Dependency 'androidx.activity:activity-ktx:...' requires
Android Gradle plugin X or higher.

This build currently uses Android Gradle plugin Y.

실제로는 의존성이 요구하는 AGP보다 프로젝트 AGP가 낮다는 뜻이다.

점검할 파일

  • android/settings.gradle.kts: AGP·Kotlin 플러그인 버전
  • android/gradle/wrapper/gradle-wrapper.properties: Gradle 버전
  • android/app/build.gradle.kts: compileSdk·targetSdk·NDK
  • pubspec.lock: 실제 설치된 Flutter 패키지 버전
flowchart LR
    A[JDK] --> B[Gradle]
    B --> C[Android Gradle Plugin]
    C --> D[Kotlin Plugin]
    C --> E[Android SDK]
    C --> F[Native Dependencies]

오류에 Gradle이 보인다고 Gradle만 올리면 다음 도구가 연달아 불평할 수 있다. 공식 호환 범위를 확인하면서 JDK → Gradle → AGP → Kotlin → Android SDK 순서로 조합을 확인한다.

6. iOS 서명과 Xcode 환경

Runner.app requires a provisioning profile 오류가 발생하면 다음 항목을 확인한다.

  • Bundle ID와 App ID가 같은가?
  • 기기 UDID가 Profile에 포함되어 있는가?
  • Distribution 인증서와 Private Key가 현재 Mac에 있는가?
  • ExportOptions.plist의 Team ID와 Profile 이름이 맞는가?
  • Release와 Patch가 같은 Xcode 버전으로 만들어졌는가?

서명 정보가 모두 맞는데 Native Changes가 나온다면 Xcode 버전도 비교한다. Release와 Patch를 서로 다른 Xcode 버전으로 빌드한 것만으로 결과가 달라질 수 있다.

7. CI에서 고정해야 할 항목

로컬에서는 되는데 CI에서만 실패하면 억울하다. 그치만 대부분은 환경 차이였다.

  • Shorebird CLI 버전
  • Flutter 버전
  • Java·Gradle·AGP·Kotlin 버전
  • Xcode 버전
  • pubspec.lock
  • Flavor와 Target
  • --dart-define 값
  • Android Keystore와 iOS Signing 설정

GitHub Actions 예제

name: Shorebird Patch

on:
  workflow_dispatch:
    inputs:
      release_version:
        description: Release version to patch
        required: true

jobs:
  patch-android:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        with:
          cache: true

      - name: Check environment
        run: |
          shorebird --version
          shorebird doctor

      - name: Create Android patch
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
        run: |
          shorebird patch android \
            --flavor prod \
            --target lib/main.dart \
            --release-version "${{ inputs.release_version }}"

2026년 10월 1일부터 예전 shorebird login:ci 토큰은 사용할 수 없다. Shorebird Console의 Account > API Keys에서 API Key를 만들고 CI Secret의 SHOREBIRD_TOKEN 값을 교체한다.

토큰 이름은 그대로지만 들어가는 값의 발급 방식이 바뀌었다.

Patch 체크리스트

  • Shorebird Release로 설치한 앱이다.
  • 대상 Release 버전을 명시했다.
  • Release와 같은 Flavor·Target을 사용했다.
  • Native 또는 Asset 변경이 없다.
  • Flutter 버전이 변경되지 않았다.
  • pubspec.lock이 의도치 않게 변경되지 않았다.
  • staging 또는 QA 앱에서 먼저 확인했다.
  • 앱을 완전히 종료하고 두 번 실행했다.
  • 로그에서 app ID, Release 버전, Track을 확인했다.
  • 실패 시 Rollback 기준과 담당자가 정해져 있다.

마무리

패치가 실패했을 때는 다음 순서로 보면 범위를 빨리 줄일 수 있다.

  1. Shorebird Release로 설치한 앱인지 확인한다.
  2. 앱 ID, Release 버전, Flavor, Target을 비교한다.
  3. Native·Asset 변경 여부를 확인한다.
  4. Flutter와 Android·iOS 빌드 환경을 비교한다.
  5. staging Track에서 실제 기기로 검증한다.

Code Push는 현장 대응 속도를 확실히 줄여준다. 그치만 빠르게 보낼 수 있다는 이유로 네이티브 변경까지 억지로 Patch에 태울 필요는 없다.

패치 가능한 Dart 변경은 빠르게, 플랫폼 변경은 정식 Release로 안전하게. 이 기준만 팀에서 맞춰두면 급한 날에도 덜 흔들린다.

관련 문서

목록으로 돌아가기

다른 게시글

#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 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.