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

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

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

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

필수 조건

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

GitHub 계정에 관리자 권한이 있는 계정
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__
API
__CAPGO_KEEP_0__
GitHub
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__

Capgo CI/CD를 위한 빌드에 Capgo을 사용합니다.

__CAPGO_KEEP_0__ Capgo __CAPGO_KEEP_0__

__CAPGO_KEEP_0__ Build: Capgo 빌드를 GitHub Actions, GitLab CI, Jenkins, 또는 로컬 스크립트로 트리거하세요. npx cap sync.
: CI 비밀을 통해 서명합니다.: Android 키 스토어, 키 별칭, 패스워드, Play Console 서비스 계정 JSON을 CI 비밀에 저장하세요.
: __CAPGO_KEEP_0__ 빌드는 유지 관리되는 Android 빌드 환경을 제공하므로 __CAPGO_KEEP_1__ 이미지를 관리하거나 Gradle 캐시 문제 또는 Fastlane 레인 관리를 하지 않아도 됩니다.: QA를 위해 다운로드한 서명된 아티팩트를 제출하거나 Capgo SDK를 통해 릴리즈 빌드를 제출하세요.
: __CAPGO_KEEP_0__ 플랜은 $12/월부터 시작됩니다.: Download signed artifacts for QA or submit release builds through the Capgo CLI.

Pricing

: CI/CD에서 Capgo 빌드를 설정하세요.
: __CAPGO_KEEP_0__ 가격
context

Capgo

설치 가이드

다음과 같은 단계를 수행해야 합니다:

GitHub 액션 가격

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

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

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

수동 설정 단계

Android Keystore 생성
Google Play Service Account 설정
Fastlane 설정
GitHub 설정을 구성하세요
GitHub Actions 워크플로우를 생성하세요

1. Android Keystore를 생성하세요

Android 앱을 서명하고 배포하기 전에 Android Keystore 파일을 생성해야 합니다. 이 작업은 한 번만 수행합니다.

keytool을 사용하여 Keystore를 생성하세요

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

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

다음과 같은 입력을 입력하실 것입니다:

Keystore 비밀번호: 강력한 비밀번호를 선택하세요 (이 비밀번호를 필요로 함) KEYSTORE_STORE_PASSWORD)
Key 비밀번호: 강력한 비밀번호를 선택하세요 (이 비밀번호를 필요로 함) KEYSTORE_KEY_PASSWORD)
이름, 조직 등: 정보를 입력하세요

중요한 주의 사항

이 값을 안전하게 저장하세요:
- Keystore 파일 위치 (예: my-release-key.keystore)
- Key alias (예: my-key-alias) - 이 값을 앱을 업데이트할 때 필요합니다 KEYSTORE_KEY_ALIAS
- Keystore 비밀번호 - 이 값을 앱을 업데이트할 때 필요합니다 KEYSTORE_STORE_PASSWORD
- Key 비밀번호 - 이 값을 앱을 업데이트할 때 필요합니다 KEYSTORE_KEY_PASSWORD
Keystore 파일을 백업하세요: 만약 잃어버리면, 이미 출시된 앱을 업데이트할 수 없습니다
비밀을 지켜야 합니다: Keystore 파일을 git에 커밋하지 마세요
안전하게 보관하세요: 여러 개의 백업을 안전한 위치에 저장하세요

대안: 기존 Keystore 사용

앱을 이미 배포한 경우, 처음으로 앱을 빌드한 기계에서 사용한 동일한 Keystore를 사용해야 합니다. Keystore를 찾을 수 있습니다:

앱을 처음으로 빌드한 기계에서
Play Console → 설정 → 앱 서명 (Google Play App Signing 사용 시)

2. Google Play Service Account 설정

Google Play로 GitHub 액션으로 빌드를 업로드하려면 서비스 계정이 필요합니다.

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

가기 가기
Google Cloud 콘솔
주의하십시오 프로젝트 ID

2.2 단계: Google Play 개발자에게 API 활성화

구글 클라우드 콘솔에서 API 및 서비스 → 라이브러리
구글 클라우드 콘솔에서 "Google Play Android 개발자 API"를 검색하십시오
클릭 활성화

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

구글 클라우드 콘솔에서 IAM 및 관리 → 서비스 계정
클릭 서비스 계정 만들기
세부 정보 입력:
- 이름: github-actions-uploader
- 설명: “GitHub 액션을 통해 빌드 업로드를 위한 서비스 계정”
클릭 만들기 및 계속
현재 역할 assignments를 생략합니다 (클릭) 계속, 그런 다음 완료)

Step 2.4: 서비스 계정 키 만들기

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

Step 2.5: Play Console에서 접근 권한 부여

가서 Google Play Console로 이동하세요
가서 Setup → API 접근
Under Service accounts 아래에서클릭 권한 부여 서비스 계정에 대한
페이지에서 권한 탭에 앱을 추가하세요
페이지에서 계정 권한 권한을 부여하세요:
- 앱 정보를 조회하고 bulk 리포트를 다운로드(읽기 전용)
- _draft 앱을 생성, 편집, 삭제
- 테스트 트랙으로 앱을 릴리즈
- 제품 트랙, 제외, 기타 트랙으로 앱을 릴리즈
Click 사용자를 초대하십시오
Click 초대장 전송

Step 2.6: JSON Key을 확인하십시오

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": "..."
}

이 JSON 파일을 GitHub 비밀 변수 설정 단계에서 base64로 변환하십시오.

3. Fastlane 설정

Create a fastlane 4. __CAPGO_KEEP_0__ 비밀 변수 설정 Fastfile context

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. GitHub 설정

GitHub

4.1 단계: GitHub 비밀

GitHub
클릭 설정 → 비밀 및 변수 → 액션
클릭 새 저장소 비밀

4.2 단계: 필요한 비밀 추가

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

Capacitor Android 빌드 GitHub Action

다운로드한 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

keystore를 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

키스토어 키 비밀번호를 생성하세요.

KEYSTORE_STORE_PASSWORD

키스토어 비밀번호를 생성하세요.

Capacitor

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

패키지 이름은 android/app/build.gradle under applicationId

Step 4.3: 모든 비밀을 확인하세요

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

✅ PLAY_CONFIG_JSON
✅ 안드로이드 키스토어 파일
✅ 키스토어 키 별칭
✅ 키스토어 키 비밀번호
✅ 키스토어 저장소 비밀번호
✅ 개발자 패키지 이름

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

작동 방식

자동화된 Android 빌드 GitHub 작업을 트리거하기 위한 Git 태그를 생성하세요.
GitHub 액션은 앱을 빌드합니다.
__CAPGO_KEEP_0__ 액션은 앱을 빌드합니다.
자동으로 앱이 업데이트됩니다.

빌드 시간 및 비용

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

CI/CD 설정 가이드

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

- CI/CD 플랫폼 대안

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

- 실시간 업데이트 및 배포

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

- 리소스

자동 Capacitor 안드로이드 빌드에서 GitHub 작업으로 계속 진행

만약 __CAPGO_KEEP_0__ Actions을 사용중이라면 자동 Capacitor 안드로이드 빌드에 대한 GitHub 작업의 자동화 __CAPGO_KEEP_0__ CI/CD와 연결하여 Capgo CI/CD Capgo Native Builds Capgo 원시 빌드 Capgo Integrations Capgo 통합(Integrations) Capgo Integrations CI/CD 통합 CI/CD 통합 구현 세부 사항에 대해 GitHub 액션 통합 CI/CD 통합 구현 세부 사항에 대해 GitHub 액션 통합

자동 Capacitor Android 빌드와 GitHub 액션