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

CI/CD를 위한 Capacitor 앱 설정은 복잡하고 시간이 많이 걸립니다. 알아야 할 점은 다음과 같습니다.

새로운 빌드에 권장되는 Capgo 빌드

__CAPGO_KEEP_0__ 빌드와 __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ Capgo 빌드에 사용하는 Capgo CLI 이 Fastlane 가이드는 기존 Capacitor Actions pipeline 유지 관리하는 팀을 위해 유지되지만, 새로운 Android 빌드는 __CAPGO_KEEP_1__ __CAPGO_KEEP_2__을 사용하여 Fastlane, Gradle 런너, 키스토어, 업로드 스크립트 유지 관리할 필요가 없습니다. 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.

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

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

A GitHub account with admin access
Android 서명 키와 키스토어 파일
Google Cloud Console 프로젝트에 Play Store __CAPGO_KEEP_0__이 활성화된 상태
API Build
서비스 계정에 적절한 권한
GitHub Actions 워크플로 이해
Fastlane 구성에 대한 지식
pipeline 유지 및 디버깅에 소요되는 시간

Capgo Build는 CI/CD에 의해 Capgo로 빌드됩니다.

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

pipeline과 함께 작동: Capgo Build를 GitHub Actions, GitLab CI, Jenkins, 또는 로컬 스크립트에서 웹 빌드 후 트리거합니다. npx cap sync.
CI 비밀에서 서명: Android 키스토어, 키 별칭, 비밀번호 및 Play Console 서비스 계정 JSON을 자신의 CI 비밀에 유지합니다.
No native runner upkeep: Capgo Build는 유지 관리되는 안드로이드 빌드 환경을 제공하므로 SDK 이미지를 관리하거나 Gradle 캐시 문제 또는 Fastlane 경로를 관리할 필요가 없습니다.
Artifacts and submission: QA를위한 서명된 아티팩트를 다운로드하거나 Capgo CLI를 통해 릴리즈 빌드를 제출할 수 있습니다.

Pricing

Capgo plans start at $12/month
__CAPGO_KEEP_0__ plans start at $12/month
OTA 업데이트와 월 15회 정도의 네이티브 빌드를 포함합니다.

Set up Capgo Build in CI/CD

추가 빌드 분량은 분당 요금으로 청구됩니다.

Set up __CAPGO_KEEP_0__ Build in CI/CD

GitHub Actions Pricing

GitHub 액션

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

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

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

수동 설정 단계

Android Keystore 생성
Google Play Service Account 설정
Fastlane 설정
GitHub 비밀 설정
GitHub 액션 워크플로우 생성

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_STORE_PASSWORD)
키 비밀번호: 강력한 비밀번호를 선택하세요 (이 비밀번호를 필요로 할 것입니다) 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 사용

만약 앱을 이미 배포했다면, 동일한 키스토어를 사용해야 합니다. 키스토어는 다음과 같은 곳에서 찾을 수 있습니다:

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

2. Google Play Service Account 설정

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

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

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

Step 2.2: Enable Google Play Developer API

__CAPGO_KEEP_0__은 Capgo에서 사용하는 서비스 계정입니다. APIs & Services → 라이브러리
“Google Play Android Developer API”를 검색하세요
클릭 사용

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

가장 IAM & Admin → 서비스 계정
클릭 서비스 계정 만들기
세부 정보 입력
- 이름: github-actions-uploader
- 설명: “GitHub 액션을 사용하여 빌드 업로드하기 위한 서비스 계정”
클릭 생성 및 계속
현재 역할 할당을 생략 (클릭 계속, 그런 다음 완료)

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

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

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

Go to Google Play Console
Go to 설정 → API access
__CAPGO_KEEP_0__ 접근 권한 Under서비스 계정 , click 접근 권한 부여
서비스 계정에 대한 접근 권한 부여 앱 권한 탭, 앱 추가
탭, 계정 권한 탭, 권한 부여:
- 앱 정보 조회 및 대량 보고서 다운로드 (읽기 전용)
- _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": "..."
}

이 JSON을 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 비밀 확인

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

Step 4.1: Access GitHub Secrets

GitHub
클릭 설정 → 비밀 및 변수 → 액션
클릭 새 레포지토리 비밀

4.2 단계: 필요한 비밀 추가

다음 비밀을 하나씩 추가하세요:

PLAY_CONFIG_JSON

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

macOS/Linux:

base64 service_account_key.json | pbcopy

On Windows (PowerShell):

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

새로운 비밀을 생성하세요. PLAY_CONFIG_JSON base64 문자열을 붙여넣으세요.

ANDROID_KEYSTORE_FILE

base64로 변환된 키스토어:

On macOS/Linux:

base64 my-release-key.keystore | pbcopy

On 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_0__ com.example.app)

__CAPGO_KEEP_0__ android/app/build.gradle __CAPGO_KEEP_1__ applicationId

__CAPGO_KEEP_1__

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

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

작동 방식

생성
GitHub Actions builds your app
생성
생성

__CAPGO_KEEP_0__ 액션은 앱을 빌드합니다.

빠른 라인은 구글 플레이 베타 채널에 업로드합니다.
개인 저장소의 비용: ~$0.04 per build
오픈 소스 프로젝트는 무료입니다.

CI/CD 설정 가이드

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

대안 CI/CD 플랫폼

GitLab CI로 빌드 - 안드로이드용 GitLab 대체
코드 마법으로 빌드 - 코드 마법 설정 가이드

실시간 업데이트 및 배포

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

자원

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

만약에 당신이 자동 Capacitor 안드로이드 빌드를 GitHub 액션으로 사용하고 있다면 CI/CD 자동화 계획을 위해 __CAPGO_KEEP_0__ 액션과 연결하세요 Capgo CI/CD Capgo CI/CD에서 제품 워크플로우를 Capgo Native Builds Capgo Native Builds에서 제품 워크플로우를 Capgo Integrations Capgo Integrations에서 제품 워크플로우를 CI/CD 통합 CI/CD 통합에서 구현 세부 정보를 GitHub Actions Integration Capgo GitHub Actions Integration.

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

새로운 빌드에 권장되는 Capgo 빌드

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

Capgo Build는 CI/CD에 의해 Capgo로 빌드됩니다.

Pricing

추가 빌드 분량은 분당 요금으로 청구됩니다.

GitHub Actions Pricing

수동 설정 단계

1. Android Keystore 생성

키 스토어 생성을 위한 keytool을 사용하세요.

중요한 참고 사항

대안: 기존 Keystore 사용

2. Google Play Service Account 설정

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

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 비밀 확인

Step 4.1: Access GitHub Secrets

4.2 단계: 필요한 비밀 추가

PLAY_CONFIG_JSON

ANDROID_KEYSTORE_FILE

KEYSTORE_KEY_ALIAS

KEYSTORE_KEY_PASSWORD

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

5. GitHub 액션 워크플로우를 생성하세요.

작동 방식

__CAPGO_KEEP_0__ 액션은 앱을 빌드합니다.

관련 글

CI/CD 설정 가이드

대안 CI/CD 플랫폼

실시간 업데이트 및 배포

자원

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