Capacitor 안드로이드 자동 빌드에 GitHub 액션을 사용합니다.

CI/CD를 위한 Capacitor 앱 설정은 복잡하고 시간이 많이 걸립니다. 여기서 필요한 정보를 알려드리겠습니다.

새로운 빌드에 권장: Capgo 빌드 사용

현재는 __CAPGO_KEEP_1__ __CAPGO_KEEP_2__를 사용하는 것을 추천합니다. Capgo CLI를 사용하여 Capgo 앱을 빌드할 수 있습니다. 자연스러운 Capacitor 빌드에 사용됩니다. 이 Fastlane 가이드는 기존 GitHub 액션 PIPELINE을 유지 관리하는 팀을 위해 유지됩니다. 그러나 새로운 안드로이드 빌드는 Fastlane, Gradle 런너, 키스토어 및 업로드 스크립트를 유지 관리하지 않도록 Capgo CLI를 사용해야 합니다.

필수 조건

시작하기 전에 다음을 설정해야 합니다.

GitHub 계정에 관리자 권한이 있는 계정
Google Play Store에 이미 올려져 있는 앱
안드로이드 signing 키 및 키스토어 파일
Google Cloud Console 프로젝트에 Play Store API가 활성화된 상태
__CAPGO_KEEP_0__ 권한이 있는 계정
GitHub Actions 워크플로우 이해
Fastlane 구성에 대한 지식
pipeline 유지 및 디버깅에 소요되는 시간

Capgo CI/CD를 위해 Capgo 빌드

Fastlane, Gradle 런너, 키스토어 및 업로드 스크립트 유지 관리를 생략합니다. Capgo 빌드 기존 CI/CD pipeline에서 signed native Android 빌드를 실행합니다.

__CAPGO_KEEP_0__ 빌드는 다음 CI/CD pipeline과 호환됩니다.: Trigger Capgo Build from GitHub Actions, GitLab CI, Jenkins, or local scripts after your web build and npx cap sync.
CI/CD pipeline에서 __CAPGO_KEEP_0__ Build를 트리거합니다. CI/CD pipeline에서 __CAPGO_KEEP_0__ Build를 트리거합니다.
자연스러운 실행기 유지: Capgo 빌드는 유지 관리되는 Android 빌드 환경을 제공하므로 SDK 이미지를 관리하지 않아도, Gradle 캐시 문제, 또는 Fastlane 경로를 관리하지 않아도 됩니다.
아티팩트 및 제출: QA에 서명된 아티팩트를 다운로드하거나 Capgo CLI를 통해 릴리스 빌드를 제출할 수 있습니다.

가격

Capgo 플랜은 1달에 12달러부터 시작합니다.
OTA 업데이트 및 매월 약 15개의 네이티브 빌드를 포함합니다.
추가 빌드 분량은 분당 크레딧으로 청구됩니다.

CI/CD에서 Capgo 빌드를 설정하세요

수동 설정 안내서

다음과 같은 작업을 수행해야 합니다.

GitHub 액션 가격

가격 GitHub 액션

GitHub 액션은 저장소 유형에 따라 무료 분량을 제공합니다:

공개 저장소: 월 2,000 분
비공개 저장소: 월 2,000 분 (리눅스 러너)

비공개 프로젝트의 경우 비용은 약 $0.008/분입니다. 일반적인 빌드는 3-5 분이 걸립니다.

수동 설정 단계

Android 키 스토어 만들기
Google Play 서비스 계정 설정
Fastlane 설정
GitHub 비밀 설정
GitHub 액션 워크플로우 만들기

1. Android 키 스토어 만들기

애플리케이션을 Android로 출시하기 전에 키 스토어 파일을 생성해야 합니다. 이 작업은 한 번만 수행합니다.

키 스토어 생성

터미널에서 다음 명령어를 실행하세요:

keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

다음과 같은 정보를 입력하실 것입니다:

키 스토어 비밀번호: 강력한 비밀번호를 선택하세요 (이 비밀번호를 필요로 할 것입니다. KEYSTORE_STORE_PASSWORD)
키 비밀번호: 강력한 비밀번호를 선택하세요 (이 비밀번호를 필요로 할 것입니다. KEYSTORE_KEY_PASSWORD)
이름, 조직 등: 정보를 입력하세요

중요한 참고 사항

이 정보를 안전하게 저장하세요:
- Keystore 파일 위치 (예: my-release-key.keystore)
- 키 별칭 (예: my-key-alias) - 이 값을 필요로 할 것입니다. KEYSTORE_KEY_ALIAS
- Keystore 비밀번호 - 이 값을 필요로 할 것입니다. KEYSTORE_STORE_PASSWORD
- 키 비밀번호 - 이 값을 필요로 할 것입니다. KEYSTORE_KEY_PASSWORD
Keystore 파일 백업: 만약 잃어버리면, 업데이트할 수 없습니다.
비밀로 유지하십시오.: Keystore 파일을 git에 커밋하지 마십시오.
안전한 장소에 여러 백업을 저장하십시오.대안: 기존 Keystore 사용

__CAPGO_KEEP_0__

If you already published your app, you must use the same keystore you used initially. You can find it:

Your local machine where you first built the app
Play Console → 설정 → 앱 서명 (Google Play 앱 서명 사용 시)

2. Google Play Service Account 설정

To allow GitHub Actions to upload builds to Google Play, you need a service account.

Step 2.1: Google Cloud Project 만들기

Google Cloud Console로 이동 새로운 프로젝트 만들기 또는 기존 프로젝트 선택
프로젝트 ID를 기록하세요
Step 2.2: Google Play Developer __CAPGO_KEEP_0__ 활성화

Step 2.2: Enable Google Play Developer API

2. Google Play Service Account 설정 APIs & Services → Library
"Google Play Android Developer API"을 검색하세요.
클릭 활성화

2.3 단계: 서비스 계정 만들기

이동 IAM & Admin → 서비스 계정
클릭 서비스 계정 만들기
세부 정보 입력:
- 이름: github-actions-uploader
- 설명: “GitHub 액션을 위한 서비스 계정으로 빌드 업로드”
클릭 생성 및 계속
현재 역할 assignement을 건너뛰세요 (클릭 계속, 그런 다음 완료)

2.4 단계: 서비스 계정 키 생성

새로 생성된 서비스 계정을 클릭하세요
가기 키 탭
클릭 키 추가 → 새 키 생성
선택 JSON 형식
클릭 생성
JSON 파일이 다운로드 될 것입니다 - 이것을 안전하게 저장하세요, 나중에 필요할 것입니다

Step 2.5: Google Play Console에서 권한 부여

Go to Google Play Console
Go to Setup → API 권한
Under Service accountsclick 권한 부여 for your service account
On the 앱 권한 탭, 앱 추가
On the 계정 권한 탭, 다음 권한 부여:
- 앱 정보 보기 및 bulk 보고서 다운로드 (읽기 전용)
- draft 앱 만들기, 편집, 삭제
- 테스트 트랙으로 앱 릴리즈
- 생산, 제외, 기타 트랙으로 앱 릴리즈
Click 사용자 초대
Click 초대하기

2.6 단계: JSON 키를 확인하세요.

다운로드 한 JSON 파일은 다음과 같이 보아야 합니다.

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "github-actions-uploader@your-project-id.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

GitHub 비밀 설정 단계에서 이 것을 base64로 변환하겠습니다.

3. Fastlane 설정

프로젝트 루트에 폴더를 만들고 다음 내용을 포함하는 파일을 추가하세요. fastlane 4. __CAPGO_KEEP_0__ 비밀 설정 Fastfile 키스토어와 서비스 계정 JSON을 안전하게 저장하려면 __CAPGO_KEEP_0__에 저장해야 합니다.

default_platform(:android)

KEYSTORE_KEY_ALIAS = ENV["KEYSTORE_KEY_ALIAS"]
KEYSTORE_KEY_PASSWORD = ENV["KEYSTORE_KEY_PASSWORD"]
KEYSTORE_STORE_PASSWORD = ENV["KEYSTORE_STORE_PASSWORD"]

platform :android do
    desc "Deploy a beta version to the Google Play"
    private_lane :verify_changelog_exists do |version_code: |
      changelog_path = "android/metadata/en-US/changelogs/#{version_code}.txt"
      UI.user_error!("Missing changelog file at #{changelog_path}") unless File.exist?(changelog_path)
      UI.message("Changelog exists for version code #{version_code}")
    end

    private_lane :verify_upload_to_staging do |version_name: |
      UI.message "Skipping staging verification step"
    end
    
    lane :beta do
        keystore_path = "#{Dir.tmpdir}/build_keystore.keystore"
        File.write(keystore_path, Base64.decode64(ENV['ANDROID_KEYSTORE_FILE']))
        json_key_data = Base64.decode64(ENV['PLAY_CONFIG_JSON'])
        
        # Get previous build number and increment
        previous_build_number = google_play_track_version_codes(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            track: "internal",
            json_key_data: json_key_data,
        )[0]
        current_build_number = previous_build_number + 1
        sh("export NEW_BUILD_NUMBER=#{current_build_number}")
        
        # Build the app
        gradle(
          task: "clean bundleRelease",
          project_dir: 'android/',
          print_command: false,
          properties: {
            "android.injected.signing.store.file" => "#{keystore_path}",
            "android.injected.signing.store.password" => "#{KEYSTORE_STORE_PASSWORD}",
            "android.injected.signing.key.alias" => "#{KEYSTORE_KEY_ALIAS}",
            "android.injected.signing.key.password" => "#{KEYSTORE_KEY_PASSWORD}",
            'versionCode' => current_build_number
          })
        
        # Upload to Play Store
        upload_to_play_store(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            json_key_data: json_key_data,
            track: 'internal',
            release_status: 'completed',
            skip_upload_metadata: true,
            skip_upload_changelogs: true,
            skip_upload_images: true,
            skip_upload_screenshots: true,
        )
    end
end

4.1 단계: GitHub 비밀 확인

GitHub에 접속하여 repository를 확인하세요.

4.1 단계: GitHub 비밀 확인

GitHub에 접속하여 repository를 확인하세요.
Click 설정 → 비밀과 변수 → 액션
Click 새로운 저장소 비밀

4.2 단계: 필요한 비밀 추가

각 비밀을 하나씩 추가하세요.

PLAY_CONFIG_JSON

2.4 단계에서 다운로드 한 서비스 계정 JSON 파일을 가져옵니다.
base64로 변환하세요.

macOS/Linux에서:

base64 service_account_key.json | pbcopy

Windows (PowerShell)에서:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard

새로 생성한 비밀 이름을 PLAY_CONFIG_JSON base64 문자열을 붙여넣으세요.

ANDROID_KEYSTORE_FILE

base64로 변환한 키스토어:

macOS/Linux에서:

base64 my-release-key.keystore | pbcopy

Windows (PowerShell)에서:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("my-release-key.keystore")) | Set-Clipboard

새로 생성한 비밀 이름을 ANDROID_KEYSTORE_FILE base64 문자열을 붙여넣으세요.

KEYSTORE_KEY_ALIAS

키스토어를 생성할 때 사용한 키 별칭을 사용하여 새 비밀을 생성하세요 (예: my-key-alias)

KEYSTORE_KEY_PASSWORD

__CAPGO_KEEP_0__을 생성하세요. 키 스토어를 생성할 때 설정한 비밀번호를 사용하세요.

__CAPGO_KEEP_1__

__CAPGO_KEEP_0__을 생성하세요. 키 스토어를 생성할 때 설정한 비밀번호를 사용하세요.

__CAPGO_KEEP_2__

__CAPGO_KEEP_0__을 생성하세요. 앱의 패키지 이름을 입력하세요 (예: com.example.app)

앱의 패키지 이름을 찾으려면 android/app/build.gradle 에서 applicationId

4.3 단계: 모든 비밀번호를 확인하세요.

6개의 비밀번호를 설정했는지 확인하세요.

✅ PLAY_CONFIG_JSON
✅ ANDROID_KEYSTORE_FILE
✅ __CAPGO_KEEP_1__
✅ 키스토어 키 암호
✅ 키스토어 저장소 암호
✅ 개발자 패키지 이름

5. GitHub 액션 워크플로우를 생성합니다.

생성 .github/workflows/build-upload-android.yml:

name: Build and Deploy Android App

on:
  push:
    tags:
      - '*'

jobs:
  build_android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          
      - name: Install dependencies
        run: npm ci
        
      - name: Cache Gradle
        uses: actions/cache@v5
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            ${{ runner.os }}-gradle-
            
      - name: Build app
        run: npm run build
        
      - name: Sync Capacitor
        run: npx cap sync
        
      - name: Setup Java
        uses: actions/setup-node@v5
        with:
            distribution: 'zulu'
            java-version: '17'
            
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.0'
          bundler-cache: true
          
      - name: Run Fastlane
        uses: maierj/fastlane-action@v3.1.0
        env:
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          DEVELOPER_PACKAGE_NAME: ${{ secrets.DEVELOPER_PACKAGE_NAME }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        with:
          lane: android beta
          
      - name: Upload artifact
        uses: actions/upload-artifact@v2
        with:
          name: android-release
          path: ./android/app/build/outputs/bundle/release/app-release.aab
          retention-days: 10

작동 방식

__CAPGO_KEEP_0__ 액션에서 Git 태그를 생성하여 워크플로우를 트리거합니다.
GitHub 액션은 앱을 빌드합니다.
Fastlane은 Google Play 베타 채널로 업로드합니다.
앱이 자동으로 업데이트됩니다.

빌드 시간 및 비용

빌드 시간: 3-5분
개인 저장소의 비용: ~$0.04 per build
오픈 소스 프로젝트는 무료입니다

CI/CD 설정 가이드

자동 Capacitor iOS 빌드와 GitHub 액션 - iOS CI/CD 설정 완료
자동 빌드 및 릴리즈와 GitHub 액션 - CI/CD pipeline 튜토리얼
개발 및 프로덕션 빌드 관리와 GitHub 액션 - 환경 관리

대안 CI/CD 플랫폼

GitLab CI로 빌드 - 안드로이드용 GitLab 대체
CodeMagic으로 빌드 - CodeMagic 설정 가이드

실시간 업데이트 및 배포

Capgo 실시간 업데이트 문서 - 앱에 OTA 업데이트 추가
CI/CD 통합 Capgo - pipeline에 실시간 업데이트 통합

자원

자동 Capacitor 안드로이드 빌드부터 GitHub 액션으로 계속 진행

만약 __CAPGO_KEEP_0__을 사용하고 있다면 Capacitor Android 빌드에 GitHub 작업을 자동으로 사용하여 CI/CD 자동화 계획을 만든다. CI/CD 자동화 계획을 만드는 __CAPGO_KEEP_0__ CI/CD와 연결한다. Capgo CI/CD를 사용하여 제품 워크플로우를 만든다. Capgo Native Builds를 사용하여 제품 워크플로우를 만든다. Capgo Integrations를 사용하여 제품 워크플로우를 만든다. for the product workflow in Capgo Native Builds, Capgo Integrations Capgo Actions 통합 __CAPGO_KEEP_0__ Actions 통합 구현 세부 사항을 설명한다. __CAPGO_KEEP_0__ CI/CD를 사용하여 제품 워크플로우를 만든다. GitHub CI/CD를 사용하여 제품 워크플로우를 만든다. 구현 세부 정보에 대한 GitHub 액션 통합.

Capacitor Android 자동 빌드에 GitHub 액션을 사용하는 방법

새로운 빌드에 권장: Capgo 빌드 사용

필수 조건

Capgo CI/CD를 위해 Capgo 빌드

가격

수동 설정 안내서

GitHub 액션 가격

수동 설정 단계

1. Android 키 스토어 만들기

키 스토어 생성

중요한 참고 사항

__CAPGO_KEEP_0__

2. Google Play Service Account 설정

Step 2.1: Google Cloud Project 만들기

Step 2.2: Enable Google Play Developer API

2.3 단계: 서비스 계정 만들기

2.4 단계: 서비스 계정 키 생성

Step 2.5: Google Play Console에서 권한 부여

2.6 단계: JSON 키를 확인하세요.

3. Fastlane 설정

4.1 단계: GitHub 비밀 확인

4.1 단계: GitHub 비밀 확인

4.2 단계: 필요한 비밀 추가

PLAY_CONFIG_JSON

ANDROID_KEYSTORE_FILE

KEYSTORE_KEY_ALIAS

KEYSTORE_KEY_PASSWORD

__CAPGO_KEEP_1__

__CAPGO_KEEP_2__

4.3 단계: 모든 비밀번호를 확인하세요.

5. GitHub 액션 워크플로우를 생성합니다.

작동 방식

빌드 시간 및 비용

관련 문서

CI/CD 설정 가이드

대안 CI/CD 플랫폼

실시간 업데이트 및 배포

자원

자동 Capacitor 안드로이드 빌드부터 GitHub 액션으로 계속 진행