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

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

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

__CAPGO_KEEP_0__ 빌드와 __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ Capgo Build with the Capgo CLI 이 Fastlane 가이드는 기존 Capacitor 액션 PIPELINE을 유지 관리하는 팀을 위해 유지되지만, 새로운 안드로이드 빌드는 __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
안드로이드 서명 키와 키 스토어 파일
Google Cloud Console 프로젝트에 Play Store __CAPGO_KEEP_0__가 활성화된 상태
API
권한이 있는 서비스 계정
GitHub Actions 워크플로우 이해
Fastlane 구성에 대한 지식
pipeline 유지 및 디버그에 소요되는 시간

Capgo Build for CI/CD by 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 Builder의 Capgo 계획은 월 $12부터 시작됩니다.
__CAPGO_KEEP_0__ plans start at $12/month
: __CAPGO_KEEP_0__ 계획은 월 $12부터 시작됩니다.

Set up Capgo Build in CI/CD

: __CAPGO_KEEP_0__ 계획은 월 $12부터 시작되며 OTA 업데이트와 약 15개의 네이티브 빌드를 포함합니다.

Extra build minutes are billed by minute through credits

GitHub Actions Pricing

GitHub 액션

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

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

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

수동 설정 단계

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

1. Android Keystore 생성

앱을 서명하고 배포하기 전에 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 App Signing을 사용하는 경우)

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__ APIs & Services → 라이브러리
“Google Play Android Developer API”를 검색하세요
클릭 사용

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

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

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

새로 생성된 서비스 계정 클릭
가장 키 탭
클릭 API 키 추가 → 새 키 생성
선택 JSON 형식 클릭
생성 JSON 파일이 다운로드 될 것입니다 -
이것을 안전하게 저장하세요 이것을 나중에 필요로 하실 것입니다이 키를 사용하여 나중에 작업을 수행할 수 있습니다

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

Go to Google Play Console
Go to 설정 → API access
__CAPGO_KEEP_0__ 접근 권한 Under서비스 계정 , click 권한 부여
서비스 계정에 대한 권한 부여 앱 권한 앱 추가
탭, 계정 권한 탭,
- 앱 정보를 조회하고 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 설정

프로젝트 루트 폴더에 폴더를 만들고 다음 내용을 포함하는 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에서 프로젝트에 대한 접근

GitHub

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

비밀 키를 생성할 때 설정한 키스토어 비밀번호로 새로운 비밀을 생성하세요.

KEYSTORE_STORE_PASSWORD

비밀 키를 생성할 때 설정한 키스토어 비밀번호로 새로운 비밀을 생성하세요.

개발자 패키지 이름

비밀 키를 생성할 때 설정한 키스토어 비밀번호로 새로운 비밀을 생성하세요. com.example.app)

예를 들어, android/app/build.gradle 앱의 패키지 이름을 찾으려면 applicationId

아래

4.3 단계: 모든 비밀을 확인하세요.

다음 6개의 비밀을 설정했는지 확인하세요:
✅ PLAY_CONFIG_JSON
✅ ANDROID_KEYSTORE_FILE
✅ KEYSURE_KEY_PASSWORD
✅ KEYSURE_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

작동 방식

생성
액션을 생성하여 GitHub 워크플로우를 트리거하세요.
__CAPGO_KEEP_0__ 액션은 앱을 빌드합니다.
빠른 빌드

Google Play 베타 채널에 업로드합니다.

자동으로 앱이 업데이트됩니다.
개인 저장소의 비용: ~$0.04당 빌드
오픈 소스 프로젝트는 무료입니다

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 액션으로 계속 진행

If you are using Automatic Capacitor Android build with GitHub actions to plan CI/CD automation, connect it with Capgo CI/CD for the product workflow in Capgo CI/CD Capgo Native Builds for the product workflow in Capgo Native Builds Capgo Integrations for the product workflow in Capgo Integrations CI/CD 연동 CI/CD 연동 구현 세부 사항에서 GitHub Actions 연동 구현 세부 사항에 대한 GitHub Actions 통합을 위해.

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

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

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

Capgo Build for CI/CD by Capgo

Pricing

: __CAPGO_KEEP_0__ 계획은 월 $12부터 시작되며 OTA 업데이트와 약 15개의 네이티브 빌드를 포함합니다.

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

GitHub

4.2 단계: 필요한 비밀 추가

PLAY_CONFIG_JSON

ANDROID_KEYSTORE_FILE

KEYSTORE_KEY_ALIAS

KEYSTORE_KEY_PASSWORD

KEYSTORE_STORE_PASSWORD

개발자 패키지 이름

아래

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

작동 방식

Google Play 베타 채널에 업로드합니다.

관련된 글

CI/CD 설정 가이드

대안 CI/CD 플랫폼

실시간 업데이트 및 배포

자원

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