Flutter 튜토리얼 65편: CI/CD 설정 - 자동화된 빌드와 배포 파이프라인 구축

요약#

핵심 요지#

문제 정의: 수동 빌드와 배포는 시간이 많이 걸리고 휴먼 에러가 발생하기 쉽다.
핵심 주장: CI/CD 파이프라인을 구축하면 빌드, 테스트, 배포 과정을 자동화하여 개발 효율성과 안정성을 높일 수 있다.
주요 근거: Flutter 공식 문서에서 소개하는 fastlane, Codemagic, GitHub Actions 등의 도구를 활용한다.
한계: 초기 설정에 시간이 필요하며, 각 플랫폼별 인증서와 프로비저닝 관리가 복잡할 수 있다.

문서가 설명하는 범위#

CI/CD의 개념과 Flutter 앱에서의 필요성
fastlane을 사용한 로컬 빌드 자동화
주요 CI/CD 서비스 비교 및 설정
GitHub Actions를 활용한 실전 파이프라인 구축

읽는 시간: 30분 | 난이도: 고급

참고 자료#

Continuous delivery with Flutter - Flutter 공식 CI/CD 가이드

문제 상황#

Flutter 앱을 App Store와 Google Play에 배포하려면 여러 단계를 거쳐야 합니다. 수동으로 진행하면 빌드 명령 실행, 인증서 관리, 스토어 업로드 등 반복적인 작업이 발생합니다.

기존 방식의 한계#

1
# 수동 배포 과정 - iOS
2
flutter build ipa --release
3
# Xcode에서 Archive
4
# App Store Connect에 업로드
5
# 메타데이터 수동 입력
6
# 심사 제출
7

8
# 수동 배포 과정 - Android
9
flutter build appbundle --release
10
# Google Play Console 접속
11
# 앱 번들 업로드
12
# 릴리스 노트 작성
13
# 출시

문제는 다음과 같습니다.

매번 동일한 명령을 반복해야 한다
휴먼 에러로 잘못된 빌드가 배포될 수 있다
여러 환경(개발, 스테이징, 프로덕션)별 빌드 관리가 어렵다
팀원 간 빌드 환경 차이로 문제가 발생할 수 있다

해결 방법#

챕터 1: CI/CD 개념 이해#

Why#

NOTE
CI/CD¹는 코드 변경 시 자동으로 빌드, 테스트, 배포가 진행되는 방식입니다. 개발자는 코드 작성에 집중하고, 반복적인 작업은 자동화 시스템이 처리합니다.

What#

NOTE
CI/CD는 두 가지 개념으로 구성됩니다.
flowchart LR subgraph CI["CI - 지속적 통합"] A[코드 Push] B[자동 빌드] C[자동 테스트] end subgraph CD["CD - 지속적 배포"] D[릴리스 빌드] E[스토어 업로드] F[심사 제출] end A --> B --> C --> D --> E --> F

용어 영문 설명
CI Continuous Integration 코드 변경을 자주 통합하고 자동으로 빌드/테스트
CD Continuous Delivery 언제든 배포 가능한 상태 유지
CD Continuous Deployment 자동으로 프로덕션까지 배포

용어	영문	설명
CI	Continuous Integration	코드 변경을 자주 통합하고 자동으로 빌드/테스트
CD	Continuous Delivery	언제든 배포 가능한 상태 유지
CD	Continuous Deployment	자동으로 프로덕션까지 배포

How#

TIP

Flutter 앱의 일반적인 CI/CD 파이프라인 구성입니다.

1
# 파이프라인 단계
2
stages:
3
  - lint # 코드 스타일 검사
4
  - test # 단위/위젯 테스트
5
  - build # 앱 빌드
6
  - deploy # 스토어 배포

1
// 각 단계에서 실행되는 명령
2
// 1. Lint
3
// flutter analyze
4
// dart format --set-exit-if-changed .
5

6
// 2. Test
7
// flutter test
8

9
// 3. Build
10
// flutter build ipa --release
11
// flutter build appbundle --release
12

13
// 4. Deploy
14
// fastlane ios release
15
// fastlane android release

Watch out#

WARNING
CI/CD를 도입한다고 모든 문제가 해결되는 것은 아닙니다. 테스트 커버리지가 낮으면 CI를 통과해도 버그가 배포될 수 있습니다. 자동화와 함께 테스트 품질도 관리해야 합니다.

결론: CI/CD는 빌드, 테스트, 배포 과정을 자동화하여 개발 효율성과 안정성을 높인다.

챕터 2: fastlane 기초 설정#

Why#

NOTE
fastlane²은 iOS와 Android 앱의 빌드와 배포를 자동화하는 도구입니다. 로컬에서도 사용할 수 있고, CI/CD 서비스와 통합하여 사용할 수도 있습니다.

What#

NOTE
fastlane은 Ruby 기반 도구로, lane이라는 단위로 작업을 정의합니다.
flowchart TD subgraph fastlane F[Fastfile] L1[beta lane] L2[release lane] A1[build_app] A2[upload_to_testflight] A3[upload_to_play_store] end F --> L1 F --> L2 L1 --> A1 --> A2 L2 --> A1 --> A3

파일 역할
Fastfile lane 정의 파일
Appfile 앱 ID, 팀 ID 등 설정
Matchfile 코드 서명 인증서 관리 설정

파일	역할
`Fastfile`	lane 정의 파일
`Appfile`	앱 ID, 팀 ID 등 설정
`Matchfile`	코드 서명 인증서 관리 설정

How#

TIP

fastlane 설치 및 초기 설정 방법입니다.

1
# macOS에서 fastlane 설치
2
brew install fastlane
3

4
# 또는 gem으로 설치
5
gem install fastlane
6

7
# iOS 프로젝트 초기화
8
cd ios
9
fastlane init
10

11
# Android 프로젝트 초기화
12
cd android
13
fastlane init

iOS용 기본 Fastfile 예시입니다.

1
# ios/fastlane/Fastfile
2
default_platform(:ios)
3

4
platform :ios do
5
  desc "Push a new beta build to TestFlight"
6
  lane :beta do
7
    # 버전 증가
8
    increment_build_number(
9
      xcodeproj: "Runner.xcodeproj"
10
    )
11

12
    # 앱 빌드
13
    build_app(
14
      workspace: "Runner.xcworkspace",
15
      scheme: "Runner",
16
      export_method: "app-store"
17
    )
18

19
    # TestFlight 업로드
20
    upload_to_testflight(
21
      skip_waiting_for_build_processing: true
22
    )
23
  end
24

25
  desc "Push a new release build to App Store"
26
  lane :release do
27
    build_app(
28
      workspace: "Runner.xcworkspace",
29
      scheme: "Runner",
30
      export_method: "app-store"
31
    )
32

33
    upload_to_app_store(
34
      skip_metadata: true,
35
      skip_screenshots: true
36
    )
37
  end
38
end

Android용 기본 Fastfile 예시입니다.

1
# android/fastlane/Fastfile
2
default_platform(:android)
3

4
platform :android do
5
  desc "Deploy a new beta build to Play Store Internal Track"
6
  lane :beta do
7
    # Flutter 빌드
8
    sh("flutter build appbundle --release")
9

10
    # Play Store 업로드
11
    upload_to_play_store(
12
      track: "internal",
13
      aab: "../build/app/outputs/bundle/release/app-release.aab"
14
    )
15
  end
16

17
  desc "Deploy a new release build to Play Store"
18
  lane :release do
19
    sh("flutter build appbundle --release")
20

21
    upload_to_play_store(
22
      track: "production",
23
      aab: "../build/app/outputs/bundle/release/app-release.aab"
24
    )
25
  end
26
end

Watch out#

WARNING
fastlane은 Ruby 환경이 필요합니다. macOS에는 Ruby가 기본 설치되어 있지만, 버전 문제가 발생할 수 있습니다.
Terminal window
1
# Ruby 버전 관리자 설치 권장
2
brew install rbenv
3
rbenv install 3.2.0
4
rbenv global 3.2.0
5

6
# 환경 변수 설정
7
echo 'eval "$(rbenv init -)"' >> ~/.zshrc

결론: fastlane을 사용하면 복잡한 빌드와 배포 과정을 간단한 명령으로 자동화할 수 있다.

챕터 3: iOS 코드 서명 자동화#

Why#

NOTE
iOS 앱 배포의 가장 어려운 부분은 코드 서명³입니다. 인증서와 프로비저닝 프로파일을 팀원 간에 공유하고 관리하는 것이 복잡합니다.

What#

NOTE
fastlane match는 인증서와 프로비저닝 프로파일을 Git 저장소에서 중앙 관리합니다.
flowchart LR subgraph Team["개발팀"] D1[개발자 1] D2[개발자 2] CI[CI 서버] end subgraph Storage["저장소"] G[Git Repo] C[인증서] P[프로파일] end D1 -->|"match"| G D2 -->|"match"| G CI -->|"match"| G G --> C G --> P

타입 용도 파일
development 개발용 Development 인증서 + 프로파일
adhoc 테스트 배포용 Distribution 인증서 + Ad Hoc 프로파일
appstore 스토어 배포용 Distribution 인증서 + App Store 프로파일

타입	용도	파일
development	개발용	Development 인증서 + 프로파일
adhoc	테스트 배포용	Distribution 인증서 + Ad Hoc 프로파일
appstore	스토어 배포용	Distribution 인증서 + App Store 프로파일

How#

TIP

fastlane match 설정 방법입니다.

1
# 비공개 Git 저장소 생성 후 match 초기화
2
fastlane match init
3

4
# 인증서 생성 및 저장소에 업로드
5
fastlane match development
6
fastlane match adhoc
7
fastlane match appstore

Matchfile 설정입니다.

1
# ios/fastlane/Matchfile
2
git_url("[email protected]:your-org/certificates.git")
3

4
storage_mode("git")
5

6
type("appstore") # 기본 타입
7

8
app_identifier(["com.example.app"])
9
username("[email protected]")
10

11
# CI 환경에서는 readonly 모드 사용
12
readonly(is_ci)

Fastfile에서 match 사용합니다.

1
# ios/fastlane/Fastfile
2
platform :ios do
3
  lane :beta do
4
    # match로 인증서 동기화
5
    match(type: "appstore")
6

7
    build_app(
8
      workspace: "Runner.xcworkspace",
9
      scheme: "Runner",
10
      export_method: "app-store",
11
      export_options: {
12
        provisioningProfiles: {
13
          "com.example.app" => "match AppStore com.example.app"
14
        }
15
      }
16
    )
17

18
    upload_to_testflight
19
  end
20
end

Watch out#

WARNING
match 저장소에는 민감한 정보가 포함됩니다. 반드시 비공개 저장소를 사용하고, 암호화 비밀번호를 안전하게 관리하세요.
Terminal window
1
# 환경 변수로 비밀번호 관리
2
export MATCH_PASSWORD="your-secure-password"
3

4
# CI에서는 시크릿으로 설정
5
# GitHub Actions: secrets.MATCH_PASSWORD
6
# Codemagic: Environment variables

결론: fastlane match를 사용하면 팀 전체가 동일한 인증서를 공유하여 코드 서명 문제를 해결한다.

챕터 4: CI/CD 서비스 비교#

Why#

NOTE
클라우드 기반 CI/CD 서비스⁴를 사용하면 빌드 서버를 직접 관리할 필요가 없습니다. 각 서비스마다 특징이 다르므로 프로젝트에 맞는 서비스를 선택해야 합니다.

What#

NOTE
Flutter 공식 문서에서 소개하는 주요 CI/CD 서비스입니다.
flowchart TD subgraph Apple["Apple 생태계"] XC[Xcode Cloud] end subgraph GitHub["GitHub 생태계"] GA[GitHub Actions] end subgraph Specialized["모바일 특화"] CM[Codemagic] BS[Bitrise] AC[Appcircle] end

서비스 특징 무료 플랜 Flutter 지원
Codemagic Flutter 특화, 쉬운 설정 월 500분 네이티브
Bitrise 모바일 특화, 풍부한 플러그인 월 300분 네이티브
GitHub Actions GitHub 통합, 유연한 설정 월 2000분 YAML 설정
Xcode Cloud Apple 네이티브, Xcode 통합 월 25시간 Swift/Flutter
Appcircle 모바일 특화, 엔터프라이즈 기능 월 300분 네이티브

서비스	특징	무료 플랜	Flutter 지원
Codemagic	Flutter 특화, 쉬운 설정	월 500분	네이티브
Bitrise	모바일 특화, 풍부한 플러그인	월 300분	네이티브
GitHub Actions	GitHub 통합, 유연한 설정	월 2000분	YAML 설정
Xcode Cloud	Apple 네이티브, Xcode 통합	월 25시간	Swift/Flutter
Appcircle	모바일 특화, 엔터프라이즈 기능	월 300분	네이티브

How#

TIP

각 서비스의 선택 기준입니다.

1
// 서비스 선택 가이드
2
if (team.usesGitHub && team.wantsFlexibility) {
3
  return 'GitHub Actions';
4
} else if (team.prefersSimplicity && team.isFlutterOnly) {
5
  return 'Codemagic';
6
} else if (team.needsEnterprise && team.hasComplexWorkflow) {
7
  return 'Bitrise';
8
} else if (team.isAppleCentric && team.mainlyIOS) {
9
  return 'Xcode Cloud';
10
}

각 서비스 시작 방법입니다.

1
# Codemagic
2
# 1. codemagic.io 접속
3
# 2. GitHub/GitLab 연동
4
# 3. Flutter 프로젝트 선택
5
# 4. 자동 설정 완료
6

7
# GitHub Actions
8
# 1. .github/workflows/flutter.yml 생성
9
# 2. 워크플로우 YAML 작성
10
# 3. Secrets 설정
11
# 4. Push하면 자동 실행

Watch out#

WARNING
무료 플랜의 빌드 시간 제한을 확인하세요. Flutter 앱 빌드는 시간이 오래 걸리므로 대규모 프로젝트에서는 유료 플랜이 필요할 수 있습니다.
1
# 빌드 시간 참고
2
iOS 빌드: 10-20분
3
Android 빌드: 5-15분
4
테스트: 5-10분
5
전체 파이프라인: 20-45분

결론: 프로젝트 규모, 팀 환경, 예산을 고려하여 적합한 CI/CD 서비스를 선택한다.

챕터 5: GitHub Actions 기본 설정#

Why#

NOTE
GitHub Actions⁵는 GitHub에 내장된 CI/CD 서비스입니다. 추가 서비스 가입 없이 GitHub 저장소에서 바로 사용할 수 있습니다.

What#

NOTE
GitHub Actions는 워크플로우 파일로 CI/CD를 정의합니다.
flowchart TD subgraph Workflow["Workflow"] T[Trigger] J1[Job 1] J2[Job 2] end subgraph Job["Job"] S1[Step 1] S2[Step 2] S3[Step 3] end T -->|"on: push"| J1 T -->|"on: push"| J2 J1 --> S1 --> S2 --> S3

개념 설명 예시
Workflow 자동화 프로세스 전체 flutter.yml
Job 동일 러너에서 실행되는 단위 build-android, build-ios
Step Job 내의 개별 작업 flutter test, flutter build
Action 재사용 가능한 작업 단위 actions/checkout@v4

개념	설명	예시
Workflow	자동화 프로세스 전체	`flutter.yml`
Job	동일 러너에서 실행되는 단위	`build-android`, `build-ios`
Step	Job 내의 개별 작업	`flutter test`, `flutter build`
Action	재사용 가능한 작업 단위	`actions/checkout@v4`

How#

TIP

기본 Flutter CI 워크플로우입니다.

1
name: Flutter CI
2

3
on:
4
  push:
5
    branches: [main, develop]
6
  pull_request:
7
    branches: [main]
8

9
jobs:
10
  analyze-and-test:
11
    runs-on: ubuntu-latest
12

13
    steps:
14
      - name: Checkout
15
        uses: actions/checkout@v4
16

17
      - name: Setup Flutter
18
        uses: subosito/flutter-action@v2
19
        with:
20
          flutter-version: "3.27.0"
21
          channel: "stable"
22
          cache: true
23

24
      - name: Get dependencies
25
        run: flutter pub get
26

27
      - name: Analyze
28
        run: flutter analyze
29

30
      - name: Format check
31
        run: dart format --set-exit-if-changed .
32

33
      - name: Run tests
34
        run: flutter test --coverage
35

36
      - name: Upload coverage
37
        uses: codecov/codecov-action@v3
38
        with:
39
          file: coverage/lcov.info

Android 빌드 Job입니다.

1
build-android:
2
  needs: analyze-and-test
3
  runs-on: ubuntu-latest
4

5
  steps:
6
    - name: Checkout
7
      uses: actions/checkout@v4
8

9
    - name: Setup Java
10
      uses: actions/setup-java@v4
11
      with:
12
        distribution: "zulu"
13
        java-version: "17"
14

15
    - name: Setup Flutter
16
      uses: subosito/flutter-action@v2
17
      with:
18
        flutter-version: "3.27.0"
19
        channel: "stable"
20
        cache: true
21

22
    - name: Get dependencies
23
      run: flutter pub get
24

25
    - name: Build APK
26
      run: flutter build apk --release
27

28
    - name: Build App Bundle
29
      run: flutter build appbundle --release
30

31
    - name: Upload APK
32
      uses: actions/upload-artifact@v4
33
      with:
34
        name: android-apk
35
        path: build/app/outputs/flutter-apk/app-release.apk
36

37
    - name: Upload AAB
38
      uses: actions/upload-artifact@v4
39
      with:
40
        name: android-aab
41
        path: build/app/outputs/bundle/release/app-release.aab

Watch out#

WARNING
GitHub Actions의 무료 플랜은 Linux 러너만 무료입니다. iOS 빌드에 필요한 macOS 러너는 분당 비용이 10배 더 높습니다.
1
# 러너별 비용 (분당)
2
runs-on: ubuntu-latest   # 무료 2000분 포함
3
runs-on: macos-latest    # 무료 200분 포함 (10배 비용)
4
runs-on: windows-latest  # 무료 1000분 포함 (2배 비용)

결론: GitHub Actions를 사용하면 별도 서비스 없이 GitHub 내에서 CI/CD를 구축할 수 있다.

챕터 6: iOS 빌드 자동화#

Why#

NOTE
iOS 빌드는 macOS에서만 가능하고, 코드 서명이 필요합니다. CI 환경에서 이를 자동화하려면 인증서와 프로파일을 안전하게 관리해야 합니다.

What#

NOTE
iOS 빌드 파이프라인의 구조입니다.
flowchart LR subgraph CI["CI 환경"] C[Checkout] M[match] B[Build] U[Upload] end subgraph Secrets["Secrets"] S1[MATCH_PASSWORD] S2[APP_STORE_CONNECT_API_KEY] S3[DEPLOY_KEY] end Secrets --> M C --> M --> B --> U

시크릿 용도
MATCH_PASSWORD 인증서 저장소 암호화 키
MATCH_GIT_BASIC_AUTHORIZATION 인증서 저장소 접근 토큰
APP_STORE_CONNECT_API_KEY App Store Connect API 인증

시크릿	용도
`MATCH_PASSWORD`	인증서 저장소 암호화 키
`MATCH_GIT_BASIC_AUTHORIZATION`	인증서 저장소 접근 토큰
`APP_STORE_CONNECT_API_KEY`	App Store Connect API 인증

How#

TIP

GitHub Actions에서 iOS 빌드 및 배포 설정입니다.

1
name: iOS Release
2

3
on:
4
  push:
5
    tags:
6
      - "v*"
7

8
jobs:
9
  build-ios:
10
    runs-on: macos-latest
11

12
    steps:
13
      - name: Checkout
14
        uses: actions/checkout@v4
15

16
      - name: Setup Flutter
17
        uses: subosito/flutter-action@v2
18
        with:
19
          flutter-version: "3.27.0"
20
          channel: "stable"
21
          cache: true
22

23
      - name: Setup Ruby
24
        uses: ruby/setup-ruby@v1
25
        with:
26
          ruby-version: "3.2"
27
          bundler-cache: true
28
          working-directory: ios
29

30
      - name: Install fastlane
31
        run: |
32
          cd ios
33
          bundle install
34

35
      - name: Setup SSH for match
36
        uses: webfactory/[email protected]
37
        with:
38
          ssh-private-key: ${{ secrets.MATCH_DEPLOY_KEY }}
39

40
      - name: Get dependencies
41
        run: flutter pub get
42

43
      - name: Build and deploy
44
        env:
45
          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
46
          APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.ASC_KEY_ID }}
47
          APP_STORE_CONNECT_API_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
48
          APP_STORE_CONNECT_API_KEY_CONTENT: ${{ secrets.ASC_KEY_CONTENT }}
49
        run: |
50
          cd ios
51
          bundle exec fastlane beta

App Store Connect API 키를 사용하는 Fastfile입니다.

1
# ios/fastlane/Fastfile
2
default_platform(:ios)
3

4
platform :ios do
5
  before_all do
6
    # App Store Connect API 키 설정
7
    app_store_connect_api_key(
8
      key_id: ENV["APP_STORE_CONNECT_API_KEY_ID"],
9
      issuer_id: ENV["APP_STORE_CONNECT_API_ISSUER_ID"],
10
      key_content: ENV["APP_STORE_CONNECT_API_KEY_CONTENT"],
11
      is_key_content_base64: true
12
    )
13
  end
14

15
  lane :beta do
16
    # 인증서 동기화 (CI에서는 readonly)
17
    match(
18
      type: "appstore",
19
      readonly: true
20
    )
21

22
    # Flutter 빌드
23
    sh("flutter build ipa --release")
24

25
    # TestFlight 업로드
26
    upload_to_testflight(
27
      ipa: "../build/ios/ipa/Runner.ipa",
28
      skip_waiting_for_build_processing: true
29
    )
30
  end
31
end

Watch out#

WARNING
App Store Connect API 키는 Base64로 인코딩하여 저장해야 합니다.
Terminal window
1
# API 키 파일을 Base64로 인코딩
2
base64 -i AuthKey_XXXXXXXXXX.p8 | pbcopy
3

4
# GitHub Secrets에 붙여넣기
5
# ASC_KEY_CONTENT: (Base64 인코딩된 값)

결론: fastlane match와 App Store Connect API를 조합하면 iOS 빌드와 배포를 완전히 자동화할 수 있다.

챕터 7: Android 빌드 자동화#

Why#

NOTE
Android 앱 배포에는 서명 키⁶가 필요합니다. CI 환경에서 서명 키를 안전하게 관리하고 자동으로 서명된 앱을 빌드해야 합니다.

What#

NOTE
Android 빌드 파이프라인의 구조입니다.
flowchart LR subgraph CI["CI 환경"] C[Checkout] K[Keystore 복원] B[Build AAB] S[Sign] U[Upload] end subgraph Secrets["Secrets"] S1[KEYSTORE_BASE64] S2[KEY_ALIAS] S3[KEY_PASSWORD] S4[PLAY_STORE_JSON] end Secrets --> K C --> K --> B --> S --> U

시크릿 용도
KEYSTORE_BASE64 서명 키스토어 (Base64 인코딩)
KEY_ALIAS 키 별칭
KEY_PASSWORD 키 비밀번호
STORE_PASSWORD 키스토어 비밀번호
PLAY_STORE_CREDENTIALS Google Play API 인증 JSON

시크릿	용도
`KEYSTORE_BASE64`	서명 키스토어 (Base64 인코딩)
`KEY_ALIAS`	키 별칭
`KEY_PASSWORD`	키 비밀번호
`STORE_PASSWORD`	키스토어 비밀번호
`PLAY_STORE_CREDENTIALS`	Google Play API 인증 JSON

How#

TIP

GitHub Actions에서 Android 배포 설정입니다.

1
name: Android Release
2

3
on:
4
  push:
5
    tags:
6
      - "v*"
7

8
jobs:
9
  build-android:
10
    runs-on: ubuntu-latest
11

12
    steps:
13
      - name: Checkout
14
        uses: actions/checkout@v4
15

16
      - name: Setup Java
17
        uses: actions/setup-java@v4
18
        with:
19
          distribution: "zulu"
20
          java-version: "17"
21

22
      - name: Setup Flutter
23
        uses: subosito/flutter-action@v2
24
        with:
25
          flutter-version: "3.27.0"
26
          channel: "stable"
27
          cache: true
28

29
      - name: Setup Ruby
30
        uses: ruby/setup-ruby@v1
31
        with:
32
          ruby-version: "3.2"
33
          bundler-cache: true
34
          working-directory: android
35

36
      - name: Decode keystore
37
        run: |
38
          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode > android/app/upload-keystore.jks
39

40
      - name: Create key.properties
41
        run: |
42
          cat > android/key.properties << EOF
43
          storePassword=${{ secrets.STORE_PASSWORD }}
44
          keyPassword=${{ secrets.KEY_PASSWORD }}
45
          keyAlias=${{ secrets.KEY_ALIAS }}
46
          storeFile=upload-keystore.jks
47
          EOF
48

49
      - name: Get dependencies
50
        run: flutter pub get
51

52
      - name: Build App Bundle
53
        run: flutter build appbundle --release
54

55
      - name: Setup Play Store credentials
56
        run: |
57
          echo '${{ secrets.PLAY_STORE_CREDENTIALS }}' > android/play-store-credentials.json
58

59
      - name: Deploy to Play Store
60
        run: |
61
          cd android
62
          bundle exec fastlane beta

Android용 Fastfile입니다.

1
# android/fastlane/Fastfile
2
default_platform(:android)
3

4
platform :android do
5
  lane :beta do
6
    upload_to_play_store(
7
      track: "internal",
8
      aab: "../build/app/outputs/bundle/release/app-release.aab",
9
      json_key: "play-store-credentials.json",
10
      skip_upload_metadata: true,
11
      skip_upload_images: true,
12
      skip_upload_screenshots: true
13
    )
14
  end
15

16
  lane :release do
17
    upload_to_play_store(
18
      track: "production",
19
      aab: "../build/app/outputs/bundle/release/app-release.aab",
20
      json_key: "play-store-credentials.json"
21
    )
22
  end
23
end

build.gradle에서 서명 설정입니다.

1
def keystoreProperties = new Properties()
2
def keystorePropertiesFile = rootProject.file('key.properties')
3
if (keystorePropertiesFile.exists()) {
4
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
5
}
6

7
android {
8
    signingConfigs {
9
        release {
10
            keyAlias keystoreProperties['keyAlias']
11
            keyPassword keystoreProperties['keyPassword']
12
            storeFile file(keystoreProperties['storeFile'])
13
            storePassword keystoreProperties['storePassword']
14
        }
15
    }
16

17
    buildTypes {
18
        release {
19
            signingConfig signingConfigs.release
20
        }
21
    }
22
}

Watch out#

WARNING
키스토어 파일을 절대 Git에 커밋하지 마세요. .gitignore에 반드시 추가하세요.
android/.gitignore
1
key.properties
2
*.jks
3
*.keystore
4
play-store-credentials.json

결론: 서명 키를 시크릿으로 관리하고 fastlane으로 Play Store 업로드를 자동화할 수 있다.

챕터 8: 버전 관리와 릴리스 전략#

Why#

NOTE
앱 버전을 수동으로 관리하면 빌드 번호 충돌이나 버전 누락이 발생할 수 있습니다. CI/CD와 연동하여 버전을 자동으로 관리하면 이런 문제를 방지할 수 있습니다.

What#

NOTE
시맨틱 버저닝⁷을 따르는 버전 관리 전략입니다.
flowchart TD subgraph Version["버전 구조"] M[Major.Minor.Patch+Build] E["1.2.3+45"] end subgraph Triggers["버전 증가 트리거"] T1["호환성 깨짐 → Major"] T2["기능 추가 → Minor"] T3["버그 수정 → Patch"] T4["모든 빌드 → Build"] end M --> E T1 --> M T2 --> M T3 --> M T4 --> M

구성요소 설명 증가 시점
Major 호환성 깨지는 변경 대규모 리뉴얼
Minor 기능 추가 새 기능 릴리스
Patch 버그 수정 핫픽스
Build 빌드 번호 모든 CI 빌드

구성요소	설명	증가 시점
Major	호환성 깨지는 변경	대규모 리뉴얼
Minor	기능 추가	새 기능 릴리스
Patch	버그 수정	핫픽스
Build	빌드 번호	모든 CI 빌드

How#

TIP

Git 태그 기반 자동 버전 관리입니다.

1
name: Release
2

3
on:
4
  push:
5
    tags:
6
      - "v*.*.*"
7

8
jobs:
9
  extract-version:
10
    runs-on: ubuntu-latest
11
    outputs:
12
      version: ${{ steps.version.outputs.version }}
13
      build_number: ${{ steps.version.outputs.build_number }}
14

15
    steps:
16
      - name: Extract version from tag
17
        id: version
18
        run: |
19
          # v1.2.3 형식에서 버전 추출
20
          VERSION=${GITHUB_REF#refs/tags/v}
21
          echo "version=$VERSION" >> $GITHUB_OUTPUT
22

23
          # 빌드 번호는 GitHub run number 사용
24
          echo "build_number=${{ github.run_number }}" >> $GITHUB_OUTPUT
25

26
  build:
27
    needs: extract-version
28
    runs-on: ubuntu-latest
29

30
    steps:
31
      - name: Checkout
32
        uses: actions/checkout@v4
33

34
      - name: Update version in pubspec.yaml
35
        run: |
36
          VERSION="${{ needs.extract-version.outputs.version }}"
37
          BUILD="${{ needs.extract-version.outputs.build_number }}"
38
          sed -i "s/^version:.*/version: $VERSION+$BUILD/" pubspec.yaml
39

40
      - name: Build
41
        run: flutter build appbundle --release

pubspec.yaml 버전 설정입니다.

1
name: my_app
2
description: My Flutter App
3

4
# 버전 형식: major.minor.patch+build_number
5
# CI에서 자동으로 업데이트됨
6
version: 1.0.0+1
7

8
environment:
9
  sdk: ">=3.0.0 <4.0.0"

릴리스 워크플로우 예시입니다.

1
# 새 버전 릴리스
2
# 1. 변경사항 커밋
3
git add .
4
git commit -m "feat: add new feature"
5

6
# 2. 태그 생성
7
git tag -a v1.2.0 -m "Release version 1.2.0"
8

9
# 3. 푸시 (태그 포함)
10
git push origin main --tags
11

12
# 4. CI/CD 자동 실행
13
# - 테스트
14
# - 빌드
15
# - 스토어 배포

Watch out#

WARNING
iOS와 Android의 빌드 번호는 항상 증가해야 합니다. 이전보다 낮은 빌드 번호로 업로드하면 스토어에서 거부됩니다.
1
# GitHub run_number를 사용하면 항상 증가 보장
2
build_number: ${{ github.run_number }}
3

4
# 또는 날짜 기반
5
build_number: $(date +%Y%m%d%H%M)

결론: Git 태그와 CI/CD를 연동하면 버전 관리와 릴리스 프로세스를 자동화할 수 있다.

한계#

복잡한 초기 설정: 인증서, API 키, 시크릿 등 초기 설정에 상당한 시간이 필요하다
플랫폼별 차이: iOS와 Android의 빌드/배포 방식이 달라 각각 설정해야 한다
비용: iOS 빌드를 위한 macOS 러너는 비용이 높고, 대규모 프로젝트는 유료 플랜이 필요하다
디버깅 어려움: CI 환경에서 발생하는 문제는 로컬에서 재현하기 어려울 수 있다

CI/CD(Continuous Integration/Continuous Delivery): 코드 변경을 자동으로 빌드, 테스트, 배포하는 개발 방식이다. ↩
fastlane(패스트레인): iOS와 Android 앱의 빌드와 배포를 자동화하는 오픈소스 도구이다. ↩
Code Signing(코드 서명): 앱의 출처와 무결성을 보장하기 위해 인증서로 서명하는 과정이다. ↩
CI/CD Service(CI/CD 서비스): 클라우드에서 빌드와 배포 파이프라인을 실행하는 서비스이다. ↩
GitHub Actions(깃허브 액션): GitHub에 내장된 CI/CD 및 자동화 플랫폼이다. ↩
Signing Key(서명 키): 앱에 디지털 서명을 하기 위한 암호화 키이다. ↩
Semantic Versioning(시맨틱 버저닝): Major.Minor.Patch 형식의 버전 관리 규칙이다. ↩

Flutter 튜토리얼 65편: CI/CD 설정 - 자동화된 빌드와 배포 파이프라인 구축

요약#

핵심 요지#

문서가 설명하는 범위#

참고 자료#

문제 상황#

기존 방식의 한계#

해결 방법#

챕터 1: CI/CD 개념 이해#

Why#

What#

How#

Watch out#

챕터 2: fastlane 기초 설정#

Why#

What#

How#

Watch out#

챕터 3: iOS 코드 서명 자동화#

Why#

What#

How#

Watch out#

챕터 4: CI/CD 서비스 비교#

Why#

What#

How#

Watch out#

챕터 5: GitHub Actions 기본 설정#

Why#

What#

How#

Watch out#

챕터 6: iOS 빌드 자동화#

Why#

What#

How#

Watch out#

챕터 7: Android 빌드 자동화#

Why#

What#

How#

Watch out#

챕터 8: 버전 관리와 릴리스 전략#

Why#

What#

How#

Watch out#

한계#

Footnotes#

공유

목차