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

Capacitor 앱의 CI/CD 설정은 복잡하고 시간이 많이 걸립니다. 다음을 알아야 합니다.

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

__CAPGO_KEEP_0__ 빌드와 __CAPGO_KEEP_1__ __CAPGO_KEEP_2__을 사용하는 것을 추천합니다. Capgo Build는 Capgo CLI과 함께 사용하는 것을 추천합니다. For native Capacitor builds. This Fastlane guide is kept for teams maintaining existing GitHub Actions pipelines, but new Android builds should use the Capgo CLI so you do not have to maintain Fastlane, Gradle runners, keystores, and upload scripts yourself.

Prerequisites

Before starting, you’ll need to set up:

A GitHub 계정에 관리자 권한이 있는
앱이 이미 Google Play Store에 올려져 있으며 올바른 서명이 되어 있습니다.
Android 서명 키 및 키 스토어 파일
Google Cloud Console 프로젝트에 Play Store API가 활성화된
서비스 계정에 적절한 권한
GitHub Actions 워크플로우에 대한 이해
Fastlane 구성에 대한 지식
pipeline 유지 및 디버깅에 필요한 시간

전문가 CI/CD 설정을 위해 Capgo

복잡성을 피하세요. Capgo __CAPGO_KEEP_0__는 CI/CD pipeline을 직접 선호하는 플랫폼에서 구성합니다:

플랫폼 독립성: GitHub 액션, GitLab CI, 또는 기타와 함께 작동합니다.
무결합 통합: 현재 프로세스와 함께 작동할 필요가 없으며 플랫폼 switch가 필요하지 않습니다.
맞춤형 구성: 프로젝트 요구 사항에 맞춘 설정
전문가 지침: 50+ 앱에 CI/CD를 이미 설정했습니다.

가격 정보

__CAPGO_KEEP_0__: $2,600
운영 비용: ~$300/년
다른 사설 솔루션과 비교: $6,000/년
5년 동안 $26,100를 절약하세요

CI/CD 설정하기

수동 설정 가이드

자신이 모든 것을 설정하고 싶다면, 다음을 수행하세요:

GitHub Actions 가격 정보

가격: GitHub Action

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

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

개인 프로젝트의 경우, 분당 약 $0.008의 비용이 발생합니다. 일반적인 빌드는 3-5분 정도 소요됩니다.

수동 설정 단계

Android 키스토어 생성
Google Play 서비스 계정 설정
Fastlane 설정
Configure GitHub secrets
Create GitHub Actions workflow

1. Android Keystore 생성

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

keytool을 사용하여 키스토어 생성

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

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 별칭 (예시: my-key-alias) - 이 별칭이 필요합니다 KEYSTORE_KEY_ALIAS
- Keystore 비밀번호 - 이 비밀번호가 필요합니다. KEYSTORE_STORE_PASSWORD
- Key 비밀번호 - 이 비밀번호가 필요합니다. KEYSTORE_KEY_PASSWORD
Keystore 파일을 백업하세요.: 만약 잃어버리면, 당신의 앱을 업데이트할 수 없습니다.
비밀을 지켜라.: Git에 Keystore 파일을 커밋하지 마세요.
안전한 곳에 보관하라.: 여러 개의 백업을 안전한 위치에 보관하라.

대안: 기존 Keystore 사용

앱을 이미 배포한 경우, 처음으로 사용한 Keystore를 사용해야 합니다. 찾을 수 있는 곳은:

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

2. Google Play 서비스 계정 설정

Google Play로 GitHub 액션을 업로드 하기 위해 서비스 계정을 필요로 합니다.

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

Google Cloud Console로 이동하세요. Google Cloud Console
새로운 프로젝트를 만들거나 기존 프로젝트를 선택하세요.
프로젝트 ID를 기록하세요.

2단계 2: Google Play 개발자 API 활성화

Google Cloud Console에서 APIs & Services → Library
“Google Play Android Developer API””를 검색하세요.
클릭 활성화

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

로 가기 IAM & Admin → 서비스 계정
클릭 서비스 계정 만들기
세부 정보 입력:
- 이름: github-actions-uploader
- 설명: "GitHub 액션으로 빌드 업로드하기 위한 서비스 계정"
클릭 생성하고 계속
__CAPGO_KEEP_0__ 역할 할당을 지금은 건너뛰세요 (클릭 계속, 그리고 완료)

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

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

2.5 단계: Play 콘솔에서 액세스 권한 부여

Play 콘솔로 이동 Google Play 콘솔로 이동
Go to 설정 → API 접근 권한
아래 서비스 계정, 클릭 접근 권한 부여 서비스 계정에 대한
앱 권한 탭에서 앱을 추가 앱 권한
탭에서 앱을 추가 계정 권한 이 탭에서 권한을 부여하세요:
- 앱 정보를 조회하고 bulk 리포트를 다운로드할 수 있습니다 (읽기 전용)
- draft 앱을 생성, 편집, 삭제할 수 있습니다
- 테스트 트랙으로 앱을 릴리스합니다
- 생산, 배제 및 기타 트랙으로 앱을 릴리스합니다
클릭 사용자를 초대하세요
클릭 초대장을 발송하세요

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

Create a fastlane 프로젝트 루트에 폴더를 만들고 다음 내용을 포함하는 Fastfile 4. __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

이제 키 스토어와 서비스 계정 JSON을 가지고 있습니다. GitHub에서 안전하게 저장해야 합니다.

4.1 단계: GitHub 비밀 설정 접근

GitHub에 있는 리포지토리로 이동하십시오.

Go to your repository on GitHub
설정 비밀 및 변수 → Settings → Actions
클릭 새로운 저장소 비밀

4.2 단계: 필요한 비밀 추가

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

__CAPGO_KEEP_0__

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 __CAPGO_KEEP_1__

ANDROID_KEYSTORE_FILE

__CAPGO_KEEP_0__을 base64로 변환하세요:

macOS/Linux에서:

base64 my-release-key.keystore | pbcopy

Windows (PowerShell)에서:

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

__CAPGO_KEEP_0__라는 비밀을 생성하세요 ANDROID_KEYSTORE_FILE base64 문자열을 붙여넣으세요

KEYSTORE_KEY_ALIAS

__CAPGO_KEEP_0__라는 비밀을 생성하세요. 예를 들어, my-key-alias)

KEYSTORE_KEY_PASSWORD

__CAPGO_KEEP_0__라는 비밀을 생성하세요. 예를 들어,

KEYSTORE_STORE_PASSWORD