CI/CD를 위한 Capacitor 앱 설정은 복잡하고 시간이 많이 걸립니다. 알아야 할 내용은 다음과 같습니다.
새로운 빌드에 권장: Capgo 빌드 사용
우리는 __CAPGO_KEEP_0__ 빌드와 __CAPGO_KEEP_1__ __CAPGO_KEEP_2__를 사용하는 것을 추천합니다. 우리는 Capgo 빌드와 Capgo CLI를 사용하는 것을 추천합니다. 자연 Capacitor 빌드에 대해. 이 Fastlane 가이드는 기존 GitHub Actions pipeline 유지 관리하는 팀을 위해 보존되지만, 새로운 Android 빌드는 Fastlane, Gradle 런너, 키 스토어, 업로드 스크립트 유지 관리하지 않도록 Capgo CLI 사용하십시오.
필수 조건
시작하기 전에, 다음을 설정해야 합니다.
- GitHub 계정에 관리자 권한이 있는 계정
- Google Play Store에 이미 올려진 앱과 올바른 서명
- Android 서명 키 및 키 스토어 파일
- Google Cloud Console 프로젝트에 Play Store API 활성화
- 적절한 권한이 있는 서비스 계정
- GitHub Actions 워크플로우에 대한 이해
- Fastlane 구성에 대한 지식
- pipeline 유지 및 디버깅에 필요한 시간
Capgo CI/CD 빌드에 의해 Capgo
Fastlane, Gradle 런너,_keystore_, 업로드 스크립트 유지 관리를 생략합니다. Capgo 빌드 __CAPGO_KEEP_0__ 빌드는 CI/CD pipeline에서 이미 존재하는 빌드 파이프라인에서 signed native Android 빌드를 실행합니다:
- __CAPGO_KEEP_0__ 파이프라인과 함께 작동합니다.: Capgo 빌드는 GitHub 액션, GitLab CI, Jenkins, 또는 로컬 스크립트에서 웹 빌드 후에 Capgo 빌드를 트리거합니다.
npx cap sync. - __CAPGO_KEEP_0__ 빌드에서 CI 비밀을 통해 서명: Android 키 저장소, 키 별칭, 비밀번호, Play Console 서비스 계정 JSON을 CI 비밀에 저장하여 유지합니다.
- __CAPGO_KEEP_0__ 빌드 유지 관리: Capgo 빌드는 유지 관리된 Android 빌드 환경을 제공하여 SDK 이미지를 관리하거나 Gradle 캐시 문제 또는 Fastlane 경로를 관리할 필요가 없습니다.
- 아티팩트 및 제출: QA에 서명된 아티팩트를 다운로드하거나 Capgo CLI를 통해 릴리스 빌드를 제출합니다.
가격 정보
- Capgo 플랜은 월 $12에 시작합니다
- OTA 업데이트와 월 15회 정도의 네이티브 빌드가 포함됩니다
- 추가 빌드 분량은 분당 크레딧으로 청구됩니다
수동 설정 안내서
다음과 같은 단계를 따르세요:
GitHub 액션 가격
GitHub 액션은 다음 유형의 저장소에 따라 무료 분량을 제공합니다:
- 공개 저장소: 월 2,000분
- 개인 저장소: 월 2,000분 (리눅스 러너)
개인 프로젝트의 경우 비용은 약 $0.008/분입니다. 일반적인 빌드는 3-5분 정도 걸립니다.
수동 설정 단계
- Android Keystore 생성
- Google Play Service 계정 설정
- Fastlane 설정
- GitHub 비밀 설정
- GitHub Actions 워크플로 생성
1. Android Keystore 생성
Android 앱을 서명하고 배포하기 전에 Android Keystore 파일을 생성해야 합니다. 이 작업은 한 번만 수행합니다.
Keystore 생성하기
터미널에서 다음 명령어를 실행하세요:
keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000키를 입력하라는 메시지가 표시됩니다:
- Keystore password:
KEYSTORE_STORE_PASSWORD) - Choose a strong password (you’ll need this as Key password
KEYSTORE_KEY_PASSWORD) - : Choose a strong password (you’ll need this as
Your name, organization, etc.
-
: :
- Fill in your details
my-release-key.keystore) - Important Notes
my-key-aliasSave these values securelyKEYSTORE_KEY_ALIAS - Keystore file location (e.g.,
KEYSTORE_STORE_PASSWORD - 비밀번호 - 이 비밀번호가 필요합니다.
KEYSTORE_KEY_PASSWORD
- Fill in your details
-
키스토어 파일을 백업하세요.: 앱을 배포한 후 앱을 업데이트할 수 없으므로 잃어버리지 마세요.
-
비밀을 지켜주세요.: git에 키스토어 파일을 커밋하지 마세요.
-
안전한 곳에 보관하세요.: 여러 개의 백업을 안전한 곳에 보관하세요.
대안: 기존 키스토어 사용
앱을 이미 배포한 경우, 처음으로 앱을 빌드한 기기에서 사용한 동일한 키스토어를 사용해야 합니다. 키스토어를 찾을 수 있습니다:
- 앱을 처음으로 빌드한 기기에서
- Play Console → 설정 → 앱 서명 (Google Play App Signing 사용 시)
2. Google Play Service Account 설정
Google Play에 업로드 하기 위해 GitHub Actions를 사용하려면 서비스 계정이 필요합니다.
2.1 단계: Google Cloud 프로젝트 만들기
- 다음으로 이동하세요 Google Cloud 콘솔
- 새로운 프로젝트를 만들거나 기존 프로젝트를 선택하세요
- 프로젝트 ID를 기록하세요
2.2 단계: Google Play Developer API 활성화
- Google Cloud Console에서 다음으로 이동하세요 APIs & Services → Library
- “Google Play Android Developer API”를 검색하세요
- 클릭 켜기
2.3 단계: 서비스 계정 만들기
- 가기 IAM & Admin → 서비스 계정
- 클릭 서비스 계정 만들기
- 세부 정보 입력:
- 이름:
github-actions-uploader - 설명: "GitHub 액션을 빌드 업로드하기 위한 서비스 계정"
- 이름:
- 클릭 만들기 및 계속
- Skip 역할 assignement을 일시적으로 중지합니다 (클릭 Continue, 그 다음 완료)
Step 2.4: Service Account Key 생성
- 새로 생성된 서비스 계정 클릭
- Go to Keys tab
- Click Add Key → 새 키 생성
- 선택 JSON 형식
- 클릭 만들기
- JSON 파일이 다운로드 될 것입니다 - 이 파일을 안전하게 저장하세요그런 다음 나중에 필요할 것입니다
2.5 단계: Play Console에서 액세스 권한 부여
- Google Play Console로 이동하세요 Google Play Console로 이동하세요
- Step 2.5: Play Console에서 액세스 권한 부여 설정 → 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 secret 설정 단계에서 base64로 변환하겠습니다.
3. Fastlane 설정
Create a fastlane 프로젝트 루트 폴더에 폴더를 만들고 다음 내용을 포함하는 Fastfile 4. __CAPGO_KEEP_0__ Secret 설정
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 Secret 접근
GitHub에 접속하여
- Go to your repository on GitHub
- 비밀 및 변수 액션 → Click → Settings
- 클릭 새로운 저장소 비밀
4.2 단계: 필요한 비밀 추가
이러한 비밀들을 하나씩 추가하세요:
PLAY_CONFIG_JSON
- 2.4 단계에서 다운로드한 서비스 계정 JSON 파일을 가져옵니다.
- base64로 변환하세요:
macOS/Linux:
base64 service_account_key.json | pbcopyWindows (PowerShell):
[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard- 새 비밀을 만들고 이름을
PLAY_CONFIG_JSONbase64 문자열을 붙여넣으세요.
ANDROID_KEYSTORE_FILE
- Base64으로 변환된 키스토어를 입력하세요:
macOS/Linux에서:
base64 my-release-key.keystore | pbcopyWindows (PowerShell)에서:
[Convert]::ToBase64String([IO.File]::ReadAllBytes("my-release-key.keystore")) | Set-Clipboard- 키스토어에 대한 새로운 비밀을 생성하세요.
ANDROID_KEYSTORE_FILE키스토어의 Base64 문자열을 붙여넣으세요.
키스토어의 키 별칭:
키스토어의 키 별칭을 생성하세요. (예: my-key-alias)
키스토어의 키 비밀:
키스토어의 비밀을 생성하세요.
키스토어의 비밀을 생성하세요.
개발자 패키지 이름:
DEVELOPER_PACKAGE_NAME
새로운 비밀을 생성하세요. 앱의 패키지 이름 (예를 들어,) com.example.app)
패키지 이름을 찾으려면 android/app/build.gradle 아래 applicationId
4.3 단계: 모든 비밀을 확인하세요
6개의 비밀을 구성했는지 확인하세요:
- ✅ PLAY_CONFIG_JSON
- ✅ ANDROID_KEYSTORE_FILE
- ✅ KEYSTORE_KEY_ALIAS
- ✅ KEYSTORE_KEY_PASSWORD
- ✅ KEYSTORE_STORE_PASSWORD
- ✅ DEVELOPER_PACKAGE_NAME
5. GitHub Actions Workflow을 생성하세요
만들기 .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작동 방식
- __CAPGO_KEEP_0__ 액션은 앱을 빌드합니다
- GitHub Actions builds your app
- 앱이 자동으로 업데이트됩니다
- 빌드 시간 및 비용
빌드 시간: 3-5분
- 비공개 저장소에 대한 비용: ~$0.04/빌드
- 오픈 소스 프로젝트는 무료입니다
- 관련 글
CI/CD 설정 가이드
Create a Git tag to trigger the workflow
- 자동화된 Capacitor iOS 빌드와 GitHub 액션 - iOS CI/CD 설정 완료
- 자동화된 빌드 및 릴리즈와 GitHub 액션 - CI/CD pipeline 튜토리얼
- 개발 및 프로덕션 빌드 관리와 GitHub 액션 - 환경 관리
대안 CI/CD 플랫폼
- GitLab CI로 빌드 - GitLab CI Android 대안
- CodeMagic으로 빌드 - CodeMagic 설정 가이드
실시간 업데이트 및 배포
- Capgo Live Updates Documentation - 앱에 OTA 업데이트를 추가하세요
- CI/CD Integration with Capgo - pipeline에 실시간 업데이트를 통합하세요
Resources
자동 Capacitor Android 빌드와 GitHub 액션으로 계속 진행하세요
자동 __CAPGO_KEEP_0__ Android 빌드와 __CAPGO_KEEP_1__ 액션을 사용하는 경우 CI/CD 자동화 계획을 만드는 데 사용하는 경우, 자동 Capacitor Android 빌드와 GitHub 액션을 Capacitor CI/CD와 연결하세요 __CAPGO_KEEP_0__ 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, CI/CD 통합 CI/CD 통합 구현 세부 사항에 대해 GitHub Actions Integration for the implementation detail in GitHub Actions Integration.
