자동 Capacitor 안드로이드 빌드와 GitHub 작업

Capacitor 앱을 위한 CI/CD 설정은 복잡하고 시간이 많이 걸립니다. 다음은 알아야 할 내용입니다.

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

현재는 __CAPGO_KEEP_0__ 빌드 사용을 추천합니다. Capgo 빌드에 Capgo CLI를 사용하세요. 자연스러운 Capacitor 빌드에 사용합니다. 이 Fastlane 가이드는 기존 GitHub Actions pipeline 유지 관리하는 팀을 위해 유지되지만, 새로운 안드로이드 빌드는 Capgo CLI를 사용하여 Fastlane, Gradle 런너, 키스토어, 업로드 스크립트를 유지 관리할 필요가 없습니다.

필수 조건

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

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

Capgo Build for CI/CD by Capgo

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

__CAPGO_KEEP_0__ Build는 다음과 함께 작동합니다.: 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를 __CAPGO_KEEP_1__ Actions, GitLab CI, Jenkins, 또는 로컬 스크립트에서 트리거합니다.CI 비밀에서 서명합니다.
자연스러운 실행기 유지: Capgo 빌드는 유지 관리되는 Android 빌드 환경을 제공하므로 SDK 이미지를 관리하거나 Gradle 캐시 문제 또는 Fastlane 경로를 관리할 필요가 없습니다.
아티팩트 및 제출: QA를위한 서명된 아티팩트를 다운로드하거나 Capgo CLI를 통해 릴리스 빌드를 제출하세요.

가격

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

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

수동 설정 안내서

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

GitHub 액션 가격

가격 GitHub 액션

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

공개 저장소: 월 2,000 분
개인 저장소: 월 2,000 분 (Linux 실행자)

개인 프로젝트의 비용은 약 $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 사용

이미 앱을 배포한 경우, 처음으로 사용한 키스토어를 사용해야 합니다. 키스토어를 찾을 수 있습니다:

앱을 처음으로 빌드한 로컬 머신
Play Console → 설정 → 앱 서명 (Google Play 앱 서명 사용 시)

2. Google Play Service Account 설정

Google Play로 GitHub 액션을 업로드할 수 있도록 서비스 계정을 만듭니다.

2.1 단계: Google Cloud 프로젝트 만들기

Google Cloud Console로 이동하세요 새 프로젝트를 만들거나 기존 프로젝트를 선택하세요
프로젝트 ID를 기록하세요
2.2 단계: Google Play Developer __CAPGO_KEEP_0__ 활성화

Step 2.2: Enable Google Play Developer API

In Google Cloud Console, go to APIs & Services → Library
"Google Play Android Developer API"을 검색하세요.
클릭 활성화

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

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

Step 2.4: Create Service Account Key

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

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

Go to Google Play Console
Go to 설정 → API 권한
Service accounts ,권한 부여 서비스 계정에 대한 권한 부여 권한 부여
서비스 계정에 대한 권한 부여 앱 권한 탭, 앱 추가
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을 안전하게 저장해야 합니다.

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

GitHub 비밀 설정에 접근하세요.

Now that you have your keystore and service account JSON, you need to store them securely in GitHub.

4.1 단계: GitHub 비밀 설정에 접근하세요.

GitHub에 접속하세요.
클릭 설정 → __CAPGO_KEEP_0__ → 액션
클릭 새로운 저장소 비밀

4.2 단계: 필요한 비밀 추가

이러한 비밀 각각을 하나씩 추가하세요:

PLAY_CONFIG_JSON

__CAPGO_KEEP_0__
다운로드한 서비스 계정 JSON 파일을 가져옵니다.

base64로 변환하세요:

base64 service_account_key.json | pbcopy

Windows (PowerShell)에서:

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

새로 만들 secret 이름을 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

새로 만들 secret 이름을 ANDROID_KEYSTORE_FILE base64 문자열을 붙여넣기

KEYSTORE_KEY_ALIAS

키스토어를 생성할 때 사용한 키 별칭으로 새로 만들 secret를 생성하세요 (예: 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 __CAPGO_KEEP_3__ applicationId

Step 4.3: Verify All Secrets

6개의 비밀번호를 설정하세요.

✅ PLAY_CONFIG_JSON
✅ ANDROID_KEYSTORE_FILE
✅ __CAPGO_KEEP_1__
✅ KEYSTORE_KEY_PASSWORD
✅ KEYSTORE_STORE_PASSWORD
✅ DEVELOPER_PACKAGE_NAME

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

작동 방식

Git 태그를 생성하여 워크플로우를 트리거합니다.
GitHub 액션은 앱을 빌드합니다.
빠른 빌드 시간으로 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 자동화를 계획하고 __CAPGO_KEEP_0__ CI/CD Capgo CI/CD에서 제품 워크플로우를 위해 Capgo Native Builds Capgo Native Builds에서 제품 워크플로우를 위해 Capgo Integrations Capgo Integrations에서 제품 워크플로우를 위해 for the product workflow in Capgo Integrations, CI/CD Integration의 구현 세부 정보를 위해 __CAPGO_KEEP_0__ Actions Integration GitHub Actions Integration GitHub 액션 통합 구현 세부 사항에 대해.

자동 Capacitor 안드로이드 빌드와 GitHub 액션