지난 글에서 스토어에 올리기 전 체크리스트를 만들었다. 분석 에러는 없는지, 테스트는 통과하는지, 서버 설정은 운영용인지, 빌드 번호는 올렸는지. 이걸 사람이 매번 기억해서 한다면 언젠가는 빠뜨린다. 예를 들어 이런 일이 생긴다.

• 급하게 고쳐서 올리느라 flutter test를 안 돌렸는데, 다른 화면이 깨진 채로 배포됐다
• 내 컴퓨터에서는 빌드가 되는데, 팀원 컴퓨터에서는 Flutter 버전이 달라서 안 된다
• 서명 키가 한 사람의 노트북에만 있어서, 그 사람이 없으면 배포를 못 한다

사람이 하는 일을 코드로 적어서 서버가 대신 하게 하는 것이 CI/CD다.

• CI(지속적 통합): 코드를 올릴 때마다 자동으로 분석, 테스트, 빌드를 돌려서 깨졌는지 알려준다
• CD(지속적 배포): 빌드된 파일을 자동으로 테스트 트랙이나 스토어에 올린다

1단계: GitHub Actions로 CI 만들기

GitHub 저장소를 쓰고 있다면 가장 쉽게 시작할 수 있다. 저장소의 .github/workflows/ 폴더에 ci.yml 파일을 만들면 된다.

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          channel: stable
          cache: true
      - run: flutter pub get
      - run: flutter analyze
      - run: flutter test

구조를 위에서부터 읽어보자.

• on: 언제 실행할지다. main에 코드가 올라올 때(push)와 main으로 합치려는 요청(pull_request)이 올라올 때 실행된다
• jobs: 할 일의 묶음이다. 여기서는 test 하나다
• runs-on: ubuntu-latest: 일을 시킬 가상 컴퓨터다. GitHub이 빌려주는 리눅스다
• steps: 순서대로 실행할 단계다. uses는 남이 만들어 둔 액션을 가져다 쓰는 것이고, run은 터미널 명령을 그대로 실행하는 것이다
• actions/checkout: 저장소 코드를 가상 컴퓨터로 내려받는다
• subosito/flutter-action: 가상 컴퓨터에 Flutter를 설치한다. cache: true는 다음 실행 때 다시 내려받지 않게 해서 빠르다
• flutter analyze, flutter test: 로컬에서 하던 그 명령이다

이 파일을 커밋해서 올리면 GitHub 저장소의 Actions 탭에서 실행이 보이고, 실패하면 빨간 표시가 뜬다. 풀 리퀘스트에는 통과 여부가 붙어서, 테스트가 깨진 코드가 합쳐지는 걸 막을 수 있다. 저장소 설정의 브랜치 보호 규칙에서 "이 검사를 통과해야 합칠 수 있다"를 켜면 강제된다.

액션의 버전(@v4, @v2)은 시간이 지나면 새 버전이 나오니, 적을 때 공식 저장소에서 최신을 확인한다.

삽질 포인트 1: 내 컴퓨터에서는 되는데 CI에서만 실패한다

CI는 깨끗한 새 컴퓨터에서 처음부터 시작해서, 내 컴퓨터에 쌓여 있던 것들이 없다. 흔한 원인은 이렇다.

• Flutter 버전이 다르다: 설정에 channel: stable만 두면 항상 최신이 설치된다. 팀의 로컬 버전과 맞추려면 flutter-version: '버전'으로 고정한다
• 생성된 코드가 없다: JSON 글의 *.g.dart, *.freezed.dart나 다국어 글의 AppLocalizations를 저장소에서 제외(.gitignore)했다면, CI에서는 파일이 없어서 "생성되지 않았다"는 취지의 에러가 난다. 분석 전에 생성 명령을 넣는다

      - run: flutter pub get
      - run: dart run build_runner build --delete-conflicting-outputs
      - run: flutter gen-l10n
      - run: flutter analyze
      - run: flutter test

• 파일 이름의 대소문자: macOS는 User.dart와 user.dart를 같은 파일로 보지만, 리눅스는 다른 파일로 본다. import의 대소문자가 어긋나 있으면 로컬에서는 되고 CI에서만 실패한다

2단계: 서명한 앱 번들까지 빌드하기

CI가 통과하면 배포용 파일도 만들 수 있다. 문제는 서명 키다. 지난 글에서 키스토어와 key.properties는 저장소에 올리면 안 된다고 했다. 그럼 CI는 서명을 어떻게 할까? GitHub Secrets를 쓴다. 저장소 설정의 Settings → Secrets and variables → Actions에 값을 저장해 두고, 실행할 때만 꺼내 쓴다.

파일은 Secrets에 직접 못 넣으니 base64 문자열로 바꿔서 저장한다.

# 리눅스
base64 -w 0 upload-keystore.jks > keystore.txt
# macOS
base64 -b 0 -i upload-keystore.jks > keystore.txt

keystore.txt의 내용을 KEYSTORE_BASE64라는 Secret으로 저장하고, 비밀번호와 별칭도 각각 KEYSTORE_PASSWORD, KEY_PASSWORD, KEY_ALIAS로 저장한다. 그다음 워크플로에서 복원한다.

  build-android:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
      - uses: subosito/flutter-action@v2
        with:
          channel: stable
      - run: flutter pub get

      - name: 키스토어와 key.properties 복원
        run: |
          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode > android/app/upload-keystore.jks
          echo "storePassword=${{ secrets.KEYSTORE_PASSWORD }}" > android/key.properties
          echo "keyPassword=${{ secrets.KEY_PASSWORD }}" >> android/key.properties
          echo "keyAlias=${{ secrets.KEY_ALIAS }}" >> android/key.properties
          echo "storeFile=upload-keystore.jks" >> android/key.properties

      - run: >
          flutter build appbundle --release
          --build-number=${{ github.run_number }}
          --dart-define=FLAVOR=prod

      - uses: actions/upload-artifact@v4
        with:
          name: release-aab
          path: build/app/outputs/bundle/release/*.aab

• needs: test: test 작업이 성공해야 이 작업을 시작한다. 테스트가 깨지면 배포용 빌드는 아예 만들지 않는다
• actions/setup-java: 안드로이드 빌드에 필요한 자바를 설치한다. 버전은 프로젝트의 Gradle이 요구하는 것에 맞춘다
• 복원 단계: Secrets에서 꺼낸 값으로 키스토어 파일과 key.properties를 그 자리에서만 만든다. 가상 컴퓨터는 실행이 끝나면 사라지므로 키가 남지 않는다
• --build-number=${{ github.run_number }}: 실행할 때마다 올라가는 번호를 빌드 번호로 쓴다. 지난 글의 "같은 번호를 두 번 올릴 수 없다"를 사람이 아니라 CI가 해결해 준다
• --dart-define=FLAVOR=prod: flavor 글의 값을 넘긴다. flavor를 쓴다면 --flavor prod도 붙인다
• actions/upload-artifact: 만들어진 .aab를 실행 결과에 첨부 파일로 남겨서, Actions 탭에서 내려받을 수 있다

삽질 포인트 2: 빌드 번호가 이미 올린 것보다 작다

github.run_number는 1부터 시작한다. 이미 Play Console에 1.0.0+20까지 올려 둔 앱이라면, CI가 만든 번호 5는 이미 쓴 번호보다 작아서 업로드가 거부된다. 현재 번호보다 큰 값부터 시작하도록 더해준다.

--build-number=$(( ${{ github.run_number }} + 200 ))

삽질 포인트 3: 비밀 값이 새지 않게 한다

• .jks, keystore.txt, key.properties는 저장소에 올리지 않는다. .gitignore에 넣어서 실수로 커밋되지 않게 한다
• Secrets는 실행 로그에서 ***로 가려지지만, 일부러 echo로 찍거나 변환해서 출력하지 않는다
• 외부 사람이 올린 포크의 풀 리퀘스트에는 Secrets가 전달되지 않는다. 서명이 필요한 빌드 작업은 main 브랜치나 태그에서만 돌리도록 if로 막아둔다

3단계: 태그를 달면 배포되게 하기

main에 올릴 때마다 스토어에 올리는 건 위험하다. 배포는 내가 정한 순간에 하게 하려면 태그를 트리거로 쓴다.

on:
  push:
    tags: ['v*']   # v1.0.0, v1.0.1 같은 태그를 올리면 실행

git tag v1.0.1
git push origin v1.0.1

태그를 올리는 순간만 배포 작업이 돌고, 평소 main에 올리는 코드는 CI(분석, 테스트)만 돈다.

4단계: Google Play 내부 테스트에 자동으로 올리기

빌드된 .aab를 Play Console에 올리는 단계도 자동으로 할 수 있다. Google Play API를 쓰는 서비스 계정의 JSON 키를 Secret으로 저장하고, 업로드용 액션을 쓴다.

      - uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.GOOGLE_SERVICE_JSON }}
          packageName: com.example.myapp
          releaseFiles: build/app/outputs/bundle/release/app-release.aab
          track: internal

track: internal은 지난 글에서 권한 내부 테스트부터 올리라고 한 그 트랙이다. 액션의 입력 이름(releaseFiles 등)은 액션 버전에 따라 다르니 사용하는 액션의 설명서를 확인한다. 또 Play Console은 앱의 첫 번째 출시는 직접 올려야 하는 경우가 있어서, 자동화는 첫 업로드를 마친 뒤부터 쓴다. 서비스 계정을 만들고 Play Console에 권한을 주는 과정은 Google의 안내를 따라 한 번 설정해 둔다.

iOS는 더 까다롭다

iOS 빌드는 Mac에서만 가능해서 runs-on: macos-latest를 써야 하고, 리눅스보다 실행 비용이 더 든다. 서명도 복잡하다. 인증서(.p12)와 프로비저닝 프로파일, App Store Connect API 키를 모두 Secrets에 base64로 넣고, 실행 중에 임시 키체인을 만들어 등록하는 단계가 필요하다.

  build-ios:
    runs-on: macos-latest
    steps:
      # ... checkout, flutter 설치, pub get
      # 인증서, 프로파일 복원, 키체인 설정 (단계가 많다)
      - run: flutter build ipa --release --build-number=${{ github.run_number }}

이 과정을 직접 만들기보다 Fastlane 같은 도구를 쓰거나, 아래의 Codemagic처럼 서명을 대신 처리해 주는 서비스를 쓰는 사람이 많다.

Codemagic: Flutter에 맞춘 CI/CD 서비스

Codemagic은 Flutter 앱을 위한 CI/CD 서비스다. Mac 빌드 머신이 기본으로 있고, iOS 서명과 스토어 업로드를 설정 몇 줄로 처리해 준다. 설정은 웹 화면의 워크플로 편집기로도 할 수 있고, 저장소 맨 위에 codemagic.yaml 파일을 두는 방식도 있다. 파일로 두면 설정이 코드와 함께 버전 관리되어서 이 글에서는 YAML을 쓴다.

workflows:
  android-workflow:
    name: Android Workflow
    instance_type: linux_x2
    max_build_duration: 60
    environment:
      groups:
        - google_play        # GCLOUD_SERVICE_ACCOUNT_CREDENTIALS가 들어 있는 변수 그룹
      android_signing:
        - upload_key         # Codemagic에 올려둔 키스토어 참조 이름
      flutter: stable
    scripts:
      - name: Get Flutter packages
        script: flutter packages pub get
      - name: Flutter analyze
        script: flutter analyze
      - name: Flutter unit tests
        script: flutter test
      - name: Build AAB
        script: flutter build appbundle --release --build-number=$PROJECT_BUILD_NUMBER
    artifacts:
      - build/**/outputs/**/*.aab
    publishing:
      google_play:
        credentials: $GCLOUD_SERVICE_ACCOUNT_CREDENTIALS
        track: internal

  ios-workflow:
    name: iOS Workflow
    instance_type: mac_mini_m2
    integrations:
      app_store_connect: codemagic
    environment:
      ios_signing:
        distribution_type: app_store
        bundle_identifier: com.example.myapp
      flutter: stable
    scripts:
      - name: Set up code signing
        script: xcode-project use-profiles
      - name: Get Flutter packages
        script: flutter packages pub get
      - name: Build IPA
        script: |
          flutter build ipa --release \
            --build-number=$PROJECT_BUILD_NUMBER \
            --export-options-plist=/Users/builder/export_options.plist
    artifacts:
      - build/ios/ipa/*.ipa
    publishing:
      app_store_connect:
        auth: integration
        submit_to_testflight: true

GitHub Actions와 읽는 법이 같다. scripts는 run과 같고, artifacts는 결과 파일이다. 달라진 점은 이렇다.

• workflows 아래에 플랫폼별 워크플로를 이름 붙여 둔다. 안드로이드는 리눅스 머신, iOS는 Mac 머신(mac_mini_m2)에서 돌린다
• android_signing, ios_signing: 서명 키를 Codemagic에 올려 두고 이름으로 참조한다. 키스토어를 base64로 풀어서 key.properties를 쓰는 단계가 없어진다. iOS는 xcode-project use-profiles 한 줄로 서명 설정이 끝난다
• $PROJECT_BUILD_NUMBER: Codemagic이 빌드마다 올려주는 번호다
• publishing: 빌드가 끝나면 Google Play와 App Store Connect(TestFlight)로 바로 업로드한다

instance_type의 이름, auth, submit_to_testflight 같은 게시 옵션과 무료 사용량 정책은 Codemagic 쪽에서 바뀔 수 있으니, 설정하기 전에 Codemagic 문서의 현재 예시를 확인한다.

GitHub Actions와 Codemagic, 뭘 쓰나

• GitHub Actions: 저장소가 GitHub에 있다면 따로 가입 없이 시작한다. 분석과 테스트(CI)가 주목적이고 안드로이드 위주라면 충분하다. iOS 서명과 배포는 직접 구성해야 한다
• Codemagic: iOS와 안드로이드를 같이 배포하는 Flutter 앱에 알맞다. 서명과 스토어 업로드가 쉽다. 외부 서비스에 키를 맡기는 점과 사용량 한도는 감안한다

둘을 섞는 방법도 흔하다. 분석과 테스트는 풀 리퀘스트마다 GitHub Actions가, 스토어 배포는 태그를 달 때 Codemagic이 맡는다.

처음부터 다 만들지 않는다

CI/CD는 한 번에 완성하려고 하면 지치기 쉽다. 이 순서로 한 단계씩 올린다.

• 1단계: flutter analyze와 flutter test만 자동으로 (이 글의 1단계)
• 2단계: 서명한 .aab를 만들어서 파일로 남기기
• 3단계: 태그를 달면 내부 테스트 트랙에 올리기
• 4단계: iOS도 TestFlight까지 자동으로

Android, iOS와 비교하면

• 안드로이드 네이티브의 CI는 ./gradlew test, ./gradlew bundleRelease를 실행한다. Flutter에서는 그 자리에 flutter test, flutter build appbundle이 들어간다
• iOS 네이티브의 CI는 xcodebuild나 Fastlane을 쓴다. Flutter는 flutter build ipa가 그 역할을 하고, 서명과 업로드에서는 Fastlane도 그대로 쓸 수 있다
• GitHub Actions, Jenkins 같은 CI 서비스 자체는 네이티브 앱과 똑같이 쓰는 도구다

이미 네이티브 앱의 CI를 구성해 본 경험이 있다면 구조는 그대로다. Flutter에서는 빌드 명령이 flutter ...로 바뀌고, 실행기에 Flutter를 설치하는 단계가 하나 늘어난다는 정도가 차이다.

정리

• 체크리스트를 사람이 기억해서 하면 언젠가 빠뜨리므로, 코드를 올릴 때마다 분석, 테스트, 빌드를 자동으로 돌리는 CI와 결과를 스토어로 보내는 CD를 구성한다
• GitHub Actions는 .github/workflows/*.yml에 on(언제), jobs와 steps(무엇을)를 적고, subosito/flutter-action으로 Flutter를 설치해 flutter analyze, flutter test를 실행한다
• 로컬에서는 되고 CI에서만 실패하면 Flutter 버전 고정, 생성 코드(build_runner, gen-l10n) 실행, 파일 이름의 대소문자를 확인한다
• 서명 키는 저장소에 올리지 않고 base64로 바꿔 GitHub Secrets에 저장한 뒤 빌드 중에만 복원하며, 빌드 번호는 github.run_number로 올리되 이미 올린 번호보다 큰 값부터 시작하게 한다
• 배포는 태그(v*)를 트리거로 두고 내부 테스트 트랙(track: internal)부터 올리며, Play 업로드는 앱의 첫 출시를 직접 올린 뒤부터 자동화한다
• iOS는 Mac 실행기와 복잡한 서명 때문에 Fastlane이나 Codemagic(codemagic.yaml의 ios_signing, publishing)을 많이 쓴다
• 분석과 테스트부터 시작해서 빌드, 배포 순으로 한 단계씩 자동화를 늘린다

이 글로 Flutter 시리즈 37편이 끝났다. Dart의 final과 late에서 시작해서, 위젯과 상태 관리, 데이터와 구조, 테스트와 배포 자동화까지 한 바퀴를 돌았다. 다음에는 이 흐름을 한 앱에 처음부터 끝까지 적용해 보는 실습 글로 이어가겠다.