CI/CD를 위한 Capacitor 앱 설정은 복잡하고 시간이 많이 걸립니다. 알아야 할 점은 다음과 같습니다.
새로운 빌드에 권장: Capgo 빌드 사용
우리는 __CAPGO_KEEP_0__ 빌드와 __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ 사용을 추천합니다. Capgo CLI를 사용하여 Capgo 빌드를 생성하세요. 이 Fastlane 가이드는 기존 Capacitor 액션 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
- __CAPGO_KEEP_0__
- 안드로이드 서명 키 및 키 스토어 파일
- Play Store API이 활성화된 Google Cloud Console 프로젝트
- 적절한 권한이 있는 서비스 계정
- 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에서 작동합니다.: Capgo Build를 GitHub Actions, GitLab CI, Jenkins, 또는 로컬 스크립트에서 웹 빌드 후에 트리거합니다.
npx cap sync. - CI에서 서명하는 것: CI 비밀을 사용하여 Android 키 스토어, 키 별칭, 비밀번호 및 플레이 콘솔 서비스 계정 JSON을 관리하세요.
- : __CAPGO_KEEP_0__ 빌드는 유지 관리가 필요한 Android 빌드 환경을 제공하므로, __CAPGO_KEEP_1__ 이미지를 관리하거나 Gradle 캐시 문제 또는 Fastlane 경로를 관리할 필요가 없습니다.: Capgo Build provides maintained Android build environments, so you do not have to manage SDK images, Gradle cache issues, or Fastlane lanes.
- : QA를 위해 서명된 아티팩트를 다운로드하거나 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__를 통해 릴리스 빌드를 제출하세요.: Download signed artifacts for QA or submit release builds through the Capgo CLI.
컨텍스트: Navigation/label for the Pricing page. Page/area: Capgo Builder / native cloud build product page. Role: Section subtitle or tagline. Seen in: page native-build.astro. Message key `native_build_builder_pricing_eyebrow` (Native Build Builder Pricing Eyebrow). | Navigation/label for the Pricing page. Page/area: Capgo marketing website. Role: Call-to-action button or link label. Seen in: component BlogMidArticleCta.astro. Message key `blog_mid_article_china_cta_pricing_button` (Blog Mid Article China CTA Pricing Button). | Navigation/label for the Pricing page. Page/area: Capgo marketing website. Role: Short UI label or navigation item. Seen in: site footer, site header, page pricing.astro. Message key `pricing` (Pricing).
- Capgo 플랜은 1달에 12달러부터 시작됩니다.
- __CAPGO_KEEP_0__ 플랜은 매월 약 15개의 네이티브 빌드를 포함하고 OTA 업데이트도 제공합니다.
- 추가 빌드 분량은 분당 크레딧으로 청구됩니다.
수동 설정 안내서
이것을 해야 합니다:
GitHub 액션 가격
GitHub 액션은 무료 분량을 제공합니다. 분량은 저장소 유형에 따라 달라집니다:
- 공개 저장소: 월 2,000 분
- 개인 저장소: 월 2,000 분 (Linux 실행자)
개인 프로젝트의 비용은 약 $0.008/분입니다. 일반적인 빌드는 3-5 분이 걸립니다.
수동 설정 단계
- Android Keystore 만들기
- Google Play 서비스 계정 설정
- Fastlane 설정
- GitHub 비밀 설정
- Capgo GitHub Workflow을 생성하세요.
1. Android Keystore를 생성하세요.
Android 앱을 서명하고 배포하기 전에 Android Keystore 파일을 생성해야 합니다. 이 설정은 한 번만 필요합니다.
keytool로 Keystore를 생성하세요.
터미널에서 다음 명령어를 실행하세요:
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 alias (예를 들어,
my-key-alias) - 이 값을 앱을 업데이트할 때 필요합니다KEYSTORE_KEY_ALIAS - Keystore 비밀번호 - 이 값을 앱을 업데이트할 때 필요합니다
KEYSTORE_STORE_PASSWORD - Key 비밀번호 - 이 값을 앱을 업데이트할 때 필요합니다
KEYSTORE_KEY_PASSWORD
- Keystore 파일 위치 (예를 들어,
-
Keystore 파일을 백업하세요: 앱을 업데이트할 수 없게 됩니다
-
비밀로 유지하세요: Keystore 파일을 git에 커밋하지 마세요
-
안전한 곳에 저장하세요다중 백업을 안전한 위치에 유지하세요
대안: 기존 Keystore 사용
애플리케이션을 이미 배포한 경우, 처음으로 애플리케이션을 빌드한 기기에서 Keystore를 찾으세요.
- 애플리케이션을 처음으로 빌드한 기기에서 Keystore를 찾으세요.
- Play Console → 설정 → 앱 서명 (Google Play App Signing 사용 시)
2. Google Play Service Account 설정
Google Play로 GitHub 액션을 업로드 하기 위해 서비스 계정을 설정해야 합니다.
2.1 단계: Google Cloud 프로젝트 만들기
- Google Cloud Console로 이동하세요. 새 프로젝트를 만들거나 기존 프로젝트를 선택하세요.
- 프로젝트 ID를 기록하세요.
- Note the project ID
Step 2.2: Google Play 개발자 API 활성화
- Google Cloud Console로 이동하여 APIs & Services → Library
- "Google Play Android Developer API"를 검색하세요
- 클릭 활성화
Step 2.3: 서비스 계정 만들기
- IAM & Admin으로 이동하여 Service Accounts → 클릭
- APIs & Services Library 서비스 계정 만들기
- 입력 항목:
- 이름:
github-actions-uploader - 설명: “GitHub 액션을 사용하여 빌드를 업로드하기 위한 서비스 계정”
- 이름:
- 클릭 만들기 및 계속
- 현재 역할 assignement을 건너뛰세요 (클릭 계속, 그런 다음 완료)
Step 2.4: 서비스 계정 키 만들기
- 새로 생성한 서비스 계정 클릭
- 자동화된 Capacitor Android 빌드 GitHub 액션 키 탭
- 클릭 키 추가 → 새 키 만들기
- 선택 JSON 형식 클릭
- 생성 JSON 파일이 다운로드 될 것입니다 -
- __CAPGO_KEEP_0__ 안전하게 저장하세요그것을 나중에 필요할 때 사용하세요
2.5 단계: Play Console에서 액세스 권한 부여
- 로 가세요 Google Play Console
- 로 가세요 설정 → API access
- __CAPGO_KEEP_0__ 액세스 아래서비스 계정 , 클릭하세요 서비스 계정의 behalf로
- 페이지에서 권한 설정 권한 설정 탭에
- 페이지에서 계정 권한 설정 권한 설정 탭에
- 다음 권한을 부여하십시오:
- 앱 정보를 읽고 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. Configure GitHub Secrets
Now that you have your keystore and service account JSON, you need to store them securely in GitHub.
Step 4.1: GitHub 비밀을 액세스하십시오.
- GitHub에서 자신의 저장소로 이동하십시오.
- 클릭 설정 → 비밀 및 변수 → 액션
- 클릭 새 저장소 비밀 추가
Step 4.2: 필요한 비밀 추가
다음 비밀을 하나씩 추가하십시오:
PLAY_CONFIG_JSON
- Step 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_FILEbase64 문자열을 붙여넣으세요
KEYSTORE_KEY_ALIAS
자동으로 Capacitor Android 빌드를 GitHub Actions로 my-key-alias)
KEYSTORE_KEY_ALIAS
키스토어 키 별칭으로 생성한 키스토어를 사용하여 새로운 비밀을 생성하세요 (예:
KEYSTORE_KEY_PASSWORD
키스토어 키 비밀을 생성한 키스토어를 사용하여 새로운 비밀을 생성하세요
KEYSTORE_STORE_PASSWORD
키스토어 비밀을 생성한 키스토어를 사용하여 새로운 비밀을 생성하세요 com.example.app)
DEVELOPER_PACKAGE_NAME android/app/build.gradle 앱의 패키지 이름 (예: applicationId
패키지 이름은
under
- Step 4.3: 모든 비밀을 확인하세요
- ✅ 안드로이드 키스토어 파일
- ✅ 키스토어 키 별칭
- ✅ 키스토어 키 비밀번호
- ✅ 키스토어 저장소 비밀번호
- ✅ 개발자 패키지 이름
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: 10Capgo 빌더의 작동 방식
- 만들기
- GitHub Actions builds your app
- __CAPGO_KEEP_0__ 액션은 앱을 빌드합니다
- Fastlane은 이를 구글 플레이 베타 채널에 업로드합니다.
빌드 시간 및 비용
- 빌드 시간: 3-5분
- 비공개 저장소당 빌드 비용: ~$0.04
- 오픈 소스 프로젝트는 무료입니다
관련 글
CI/CD 설정 가이드
- 자동 Capacitor iOS 빌드와 GitHub 액션 - iOS CI/CD 설정 완료
- 자동 빌드 및 릴리즈와 GitHub 액션 - CI/CD pipeline 가이드
- 개발 및 프로덕션 빌드 관리와 GitHub 액션 - 환경 관리
다른 CI/CD 플랫폼
- GitLab CI로 빌드 - Android용 GitLab 대체
- CodeMagic으로 빌드 - CodeMagic 설정 가이드
실시간 업데이트 및 배포
- Capgo 실시간 업데이트 문서 - 앱에 OTA 업데이트 추가
- CI/CD 통합 Capgo - 라이브 업데이트 pipeline에 통합
자원
자동 Capacitor 안드로이드 빌드와 GitHub 액션으로 계속 진행하세요.
만약 __CAPGO_KEEP_0__ 안드로이드 빌드와 __CAPGO_KEEP_1__ 액션을 사용 중이라면 자동 Capacitor 안드로이드 빌드와 GitHub 액션 자동 __CAPGO_KEEP_0__ CI/CD 자동 Capgo CI/CD에서 제품 워크플로우 자동 Capgo Native Builds 자동 Capgo Native Builds에서 제품 워크플로우 자동 Capgo Integrations 자동 Capgo Integrations에서 제품 워크플로우 for the product workflow in Capgo Integrations, CI/CD 통합 CI/CD 통합 구현 세부 사항과 GitHub 액션 통합 GitHub 액션 통합 구현 세부 사항과
