CI/CD를 위한 Capacitor 앱 설정은 복잡하고 시간이 많이 걸립니다. 여기서 알려드릴 내용은 다음과 같습니다.
Capgo 빌드 추천
우리는 __CAPGO_KEEP_0__ 빌드 Capgo 빌드와 Capgo CLI 로 native Capacitor 빌드를 추천합니다. 이 Fastlane 가이드는 기존 GitHub Actions pipeline 유지 관리하는 팀을 위해 유지되지만, 새로운 Android 빌드는 Capgo CLI를 사용하여 Fastlane, Gradle 런너, 키스토어, 업로드 스크립트를 유지 관리할 필요가 없습니다.
필수 조건
시작하기 전에 다음을 설정해야 합니다.
- GitHub 계정에 관리자 권한이 있는 계정
- Google Play Store에 이미 올려진 앱
- Android 서명 키와 키스토어 파일
- Google Cloud Console 프로젝트에 Play Store API이 활성화된 상태
- 권한이 있는 서비스 계정
- GitHub Actions 워크플로우 이해
- Fastlane 구성에 대한 지식
- pipeline 유지 및 디버깅에 소요되는 시간
Capgo Build for CI/CD by Capgo
Fastlane, Gradle 런너, 키스토어 및 업로드 스크립트 유지 관리를 생략합니다. Capgo Build __CAPGO_KEEP_0__ Build는 다음을 수행합니다:
- __CAPGO_KEEP_0__ Build는 CI/CD pipeline에서 이미 존재하는 빌드에서 signed native Android 빌드를 실행합니다.: Trigger Capgo Build from GitHub Actions, GitLab CI, Jenkins, or local scripts after your web build and
npx cap sync. - : __CAPGO_KEEP_0__ Build를 __CAPGO_KEEP_1__ Actions, GitLab CI, Jenkins, 또는 로컬 스크립트에서 웹 빌드 후에 트리거합니다.__CAPGO_KEEP_0__ Build는 CI 비밀에서 Android 키스토어, 키 별칭, 비밀번호 및 Play Console 서비스 계정 JSON을 유지합니다.
- 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부터 시작됩니다.
OTA 업데이트와 월 15개 이상의 네이티브 빌드를 포함합니다.
Extra build minutes are billed by minute through credits
GitHub Actions Pricing
GitHub 액션은 저장소 유형에 따라 무료 분량을 제공합니다:
- 공개 저장소: 월 2,000 분
- 개인 저장소: 월 2,000 분 (리눅스 실행자)
개인 프로젝트의 경우 비용은 약 $0.008/분입니다. 일반적인 빌드는 3-5 분이 걸립니다.
수동 설정 단계
- Android Keystore 생성
- Google Play 서비스 계정 설정
- 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 파일을 백업하세요.: 앱을 배포한 경우 앱을 업데이트할 수 없습니다.
-
비밀로 유지하세요.: 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
- 프로젝트 ID를 기록하세요 APIs & Services → 라이브러리
- “Google Play Android Developer API”를 검색하세요
- 클릭 사용
2.3 단계: 서비스 계정 만들기
- 이동 IAM & Admin → 서비스 계정
- 클릭 서비스 계정 만들기
- 세부 정보 입력:
- 이름:
github-actions-uploader - 설명: “GitHub 액션을 위한 서비스 계정으로 빌드 업로드”
- 이름:
- 클릭 생성 및 계속
- 현재 역할 assignement을 생략 (클릭 계속, 그런 다음 완료)
2.4 단계: 서비스 계정 키 생성
- 새로 생성된 서비스 계정 클릭
- 가장 키 탭
- 클릭 API 키 추가 → 새 키 생성
- 선택 JSON 형식 클릭
- 생성 JSON 파일이 다운로드 될 것입니다 -
- 이 파일을 안전하게 저장하세요 이 파일을 저장하면 나중에 필요합니다, you’ll need it later
Step 2.5: Google Play Console에 접근 권한 부여
- Go to Google Play Console
- Go to 설정 → API access
- __CAPGO_KEEP_0__ 접근 권한 Service accounts, Grant access 서비스 계정에 대한 접근 권한 부여
- On the 앱 권한 탭, 앱에 추가하세요
- On the 계정 권한 탭, 다음 권한을 부여하세요:
- 앱 정보를 조회하고 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
end4.1 단계: GitHub 비밀 확인
GitHub으로 이동합니다.
GitHub
- GitHub
- 클릭 설정 → 비밀 키 및 변수 → 액션
- 클릭 새 레포지토리 비밀
4.2 단계: 필요한 비밀 추가
각 비밀을 하나씩 추가하세요:
PLAY_CONFIG_JSON
- 2.4 단계에서 다운로드 한 서비스 계정 JSON 파일을 가져옵니다.
- base64로 변환하세요:
macOS/Linux에서:
base64 service_account_key.json | pbcopyOn Windows (PowerShell):
[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard- 새로운 비밀을 생성하세요.
PLAY_CONFIG_JSONbase64 문자열을 붙여넣으세요.
ANDROID_KEYSTORE_FILE
- base64로 변환된 키스토어:
On macOS/Linux:
base64 my-release-key.keystore | pbcopyOn Windows (PowerShell):
[Convert]::ToBase64String([IO.File]::ReadAllBytes("my-release-key.keystore")) | Set-Clipboard- 새로운 비밀을 생성하세요.
ANDROID_KEYSTORE_FILEbase64 문자열을 붙여넣으세요.
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
- ✅ KEYSORT_KEY_PASSWORD
- ✅ KEYSORT_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__ 액션은 앱을 빌드합니다.
- 빠른 라인 업로드는 구글 플레이 베타 채널로 앱을 업로드합니다.
앱이 자동으로 업데이트됩니다.
- 빌드 시간 및 비용
- 개인 저장소의 비용: ~$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 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, __CAPGO_KEEP_0__ CI/CD CI/CD 통합 GitHub Actions Integration 구현 세부 사항에 대한 GitHub Actions 통합을 위해.
