Unity
Jenkins로 AAB 파일을 Google Play 내부 테스트 트랙에 자동 배포하기
smilemugi
2025. 6. 2. 11:44
모바일 게임이나 앱을 개발하는 분들이라면, 개발이 완료된 앱을 Google Play Store에 배포하는 과정이 얼마나 번거로운지 잘 아실 겁니다. 특히 팀 프로젝트의 경우, 새로운 빌드가 나올 때마다 수동으로 업로드하고 테스터들에게 공유하는 것은 시간 낭비가 아닐 수 없죠.
이 블로그 포스팅에서는 유니티(Unity)로 빌드한 AAB(Android App Bundle) 파일을 젠킨스(Jenkins)를 사용하여 Google Play Store의 내부 테스트 트랙에 자동으로 업로드하고 배포하는 방법을 단계별로 자세히 설명해 드리겠습니다. 한 번 설정해두면 이후 작업이 훨씬 수월해질 거예요!
1. Google Cloud Platform (GCP)에서 서비스 계정 생성 및 권한 설정
젠킨스가 Google Play Store API에 접근하여 앱을 업로드하려면, Google Cloud Platform에서 서비스 계정을 생성하고 필요한 권한을 부여해야 합니다. 이미 다른 프로젝트에서 서비스 계정을 사용하고 있다면, 해당 계정을 재활용할 수도 있습니다.
1.1. 서비스 계정 생성 (최초 1회)
- GCP 콘솔 접속: Google Cloud Console에 로그인합니다.
- 프로젝트 선택: 좌측 상단에서 해당 앱과 연결할 Google Cloud 프로젝트를 선택합니다. (새로운 프로젝트를 생성해도 됩니다.)
- 서비스 계정 페이지 이동: 좌측 메뉴에서 IAM 및 관리자 > 서비스 계정으로 이동합니다.
- 서비스 계정 만들기: 상단의 서비스 계정 만들기 버튼을 클릭합니다.
- 서비스 계정 이름: 식별하기 쉬운 이름을 입력합니다 (예: jenkins-play-uploader).
- 서비스 계정 설명: 간단한 설명을 추가합니다.
- 역할 부여: 이 서비스 계정에 프로젝트에 대한 액세스 권한 부여 단계에서 이 서비스 계정이 가질 역할을 선택합니다.
- 여기서는 주로 소유자 또는 편집자 역할을 임시로 부여한 후, Google Play Console에서 더 세부적인 권한을 설정하는 것이 일반적입니다. 아니면 서비스 계정 사용자 등 제한된 역할을 부여할 수도 있습니다.
- 키 생성 (JSON 파일 다운로드):
- 서비스 계정에 키 부여 단계에서 키 만들기 버튼을 클릭합니다.
- 키 유형으로 JSON을 선택하고 만들기를 클릭합니다.
- JSON 파일이 자동으로 다운로드됩니다. 이 파일은 매우 중요하므로 안전한 곳에 보관하세요! 젠킨스에서 Google Play 인증에 이 파일이 사용됩니다.
1.2. 기존 서비스 계정 권한 확인 및 재활용 (선택 사항)
이미 사용 중인 서비스 계정이 있다면, 해당 계정의 이메일 주소만 확인하고 다음 단계에서 권한을 부여하면 됩니다.
- 서비스 계정 이메일 확인: GCP 콘솔에서 IAM 및 관리자 > 서비스 계정으로 이동하여 사용할 서비스 계정의 이메일 주소를 복사해 둡니다.
2. Google Play Console 설정 (API 액세스 및 테스터 관리)
이제 Google Play Console에서 위에서 생성한 서비스 계정이 앱에 접근하여 출시 작업을 수행할 수 있도록 권한을 부여하고, 내부 테스트 트랙의 테스터를 설정합니다.
2.1. API 액세스 설정 및 서비스 계정 연결
- Google Play Console 로그인: Google Play Console에 로그인합니다.
- 앱 선택: 왼쪽 메뉴에서 작업할 앱을 선택합니다.
- API 액세스 이동: 좌측 메뉴에서 설정 > API 액세스로 이동합니다.
- 서비스 계정 연결:
- "새 서비스 계정 만들기" 섹션에서 새 서비스 계정 만들기를 클릭합니다. (GCP로 이동하여 서비스 계정을 만들도록 안내되지만, 이미 만들었으므로 이 단계는 건너뛰고 다음을 진행합니다.)
- 바로 아래에 있는 "기존 Google Cloud 프로젝트 연결" 섹션을 찾습니다.
- GCP에서 생성한 서비스 계정의 이메일 주소를 입력하고 연결 버튼을 클릭합니다.
- 서비스 계정에 권한 부여:
- 연결된 서비스 계정 목록에서 방금 추가한 서비스 계정을 찾습니다.
- 해당 서비스 계정 옆에 있는 권한 보기 또는 앱 권한 버튼을 클릭합니다.
- 필수 권한 부여:
- 출시 관리자 (Release Manager)
- 테스트 트랙 버전 관리자 (Manage Test Track Versions)
- 테스트 트랙 설정 관리자 (Manage Test Track Settings)
- 이 외에도 필요한 역할이 있다면 추가로 부여합니다.
- 변경사항 저장을 클릭합니다.
2.2. 내부 테스트 트랙 테스터 설정
테스트 트랙에 앱이 업로드되어도, 실제 테스터들이 앱에 접근하려면 이 단계가 필수입니다.
- Google Play Console에서 앱 선택 후 테스트 > 내부 테스트로 이동합니다.
- 테스터 탭을 클릭합니다.
- 테스터 그룹 생성 또는 선택:
- 새 목록 만들기를 클릭하여 새로운 테스터 그룹을 만들거나, 기존에 생성된 그룹을 선택합니다.
- 그룹 이름을 입력하고, 테스트에 참여할 Google 계정 이메일 주소를 직접 입력하거나 CSV 파일로 가져옵니다.
- 변경사항 저장을 클릭합니다.
- 테스트 참여 링크 공유: 테스터 탭 상단에 표시되는 테스트 참여 링크를 테스터들에게 공유합니다. 이 링크를 통해 테스터들은 내부 테스트용 앱을 다운로드할 수 있습니다.
3. Jenkins에서 AAB 파일 업로드 자동화 설정
이제 젠킨스에서 유니티 빌드 AAB 파일을 Google Play 내부 테스트 트랙에 업로드하도록 설정합니다.
3.1. Jenkins 플러그인 설치 (최초 1회)
- Jenkins 대시보드에서 Jenkins 관리 > 플러그인 관리로 이동합니다.
- 설치 가능 탭에서 **"Google Play Android Publisher Plugin"**을 검색하여 설치합니다.
3.2. Google Play Credentials 등록 (최초 1회)
젠킨스가 Google Play API에 접근할 때 사용할 인증 정보를 등록합니다.
- Jenkins 대시보드에서 Jenkins 관리 > Credentials > System > Global credentials (unrestricted)로 이동합니다.
- Add Credentials를 클릭합니다.
- Kind: Google Service Account from private key를 선택합니다.
- ID: 이 크리덴셜을 식별할 ID를 입력합니다 (예: google-play-uploader-key). 이 ID는 젠킨스 Job에서 참조할 때 사용됩니다.
- JSON Key: Upload file 버튼을 클릭하여 1단계에서 다운로드했던 서비스 계정 JSON 키 파일을 업로드합니다.
- OK를 클릭하여 크리덴셜을 저장합니다.
3.3. Jenkins Job 구성 (AAB 업로드)
Freestyle 프로젝트 또는 Pipeline 프로젝트에 따라 설정 방법이 다릅니다.
3.3.1. Freestyle Project인 경우
- 해당 Jenkins Job으로 이동하여 구성 (Configure)을 클릭합니다.
- 빌드 후 조치 (Post-build Actions) 섹션으로 스크롤합니다.
- 새로운 빌드 후 조치 추가 버튼을 클릭하고 **"Upload Android AAB/APKs to Google Play"**를 선택합니다.
- 설정 값 입력:
- Google Play account: 드롭다운 메뉴에서 3.2단계에서 등록한 Google Play Credential (ID)을 선택합니다.
- APK/AAB Files: 유니티에서 빌드된 AAB 파일의 경로를 입력합니다. (예: **/YourAppName*.aab 또는 build/Android/YourAppName.aab) 와일드카드(*)를 사용하여 빌드 시 생성되는 정확한 파일명을 찾도록 하는 것이 좋습니다.
- Release Track Name: 반드시 internal을 선택합니다.
- Release notes: Add Release Notes를 클릭하고 언어별로 출시 노트를 입력합니다 (예: ko-KR "내부 테스트용 빌드입니다.").
- 저장 버튼을 클릭합니다.
3.3.2. Pipeline Project (Jenkinsfile)인 경우
Jenkinsfile을 사용하여 파이프라인을 정의한다면, androidApkUpload 스텝을 활용합니다.
Groovy
pipeline {
agent any
stages {
stage('Build Unity AAB') {
steps {
script {
// 유니티 프로젝트를 AAB로 빌드하는 명령어.
// 실제 Unity 설치 경로와 프로젝트 경로에 맞게 수정해주세요.
// 예시 (Windows):
bat "\"C:\\Program Files\\Unity\\Hub\\Editor\\2023.2.16f1\\Editor\\Unity.exe\" -batchmode -quit -projectPath \"C:\\YourUnityProject\" -executeMethod YourBuildScript.BuildAndroidAAB -logFile unity_build.log"
// 예시 (Linux/macOS):
// sh "/Applications/Unity/Hub/Editor/2023.2.16f1/Editor/Unity.app/Contents/MacOS/Unity -batchmode -quit -projectPath /path/to/your/UnityProject -executeMethod YourBuildScript.BuildAndroidAAB -logFile unity_build.log"
}
}
}
stage('Upload to Google Play Internal Test') {
steps {
script {
// Google Play 내부 테스트 트랙에 AAB 업로드
androidApkUpload(
googleCredentialsId: 'google-play-uploader-key', // 3.2단계에서 등록한 Credential ID
aabFilesPattern: '**/YourAppName*.aab', // 빌드된 AAB 파일 경로 패턴
trackName: 'internal', // 내부 테스트 트랙 지정
releaseNotes: [
[language: 'ko-KR', text: '내부 테스트용 빌드입니다.'],
[language: 'en-US', text: 'Internal test build.']
]
)
}
}
}
}
}
- googleCredentialsId: 3.2단계에서 설정한 Credentials의 ID를 정확히 입력합니다.
- aabFilesPattern: 빌드된 AAB 파일의 경로 패턴을 입력합니다.
- trackName: 'internal': 이 부분이 내부 테스트 트랙을 지정합니다.
4. 빌드 및 확인
이제 젠킨스 Job을 실행하여 모든 설정이 올바르게 작동하는지 확인합니다.
- 젠킨스 Job을 수동으로 Build Now 하거나, 설정된 트리거에 의해 자동으로 빌드되도록 합니다.
- Jenkins 콘솔 출력: 빌드 진행 상황과 Google Play 업로드 플러그인의 로그를 주의 깊게 확인합니다. 오류가 발생하면 로그를 통해 원인을 파악할 수 있습니다.
- Google Play Console 확인: 빌드가 성공하면, Google Play Console의 내부 테스트 트랙으로 이동하여 새로 업로드된 AAB 버전이 표시되는지 확인합니다. 처리 시간은 다소 소요될 수 있습니다.
이렇게 설정하면 유니티 프로젝트가 빌드될 때마다 젠킨스가 자동으로 Google Play 내부 테스트 트랙에 AAB 파일을 업로드하여 배포 과정을 간소화할 수 있습니다. 개발팀의 생산성을 크게 향상시킬 수 있을 거예요!