Capacitor 앱의 CI/CD 설정은 복잡하고 시간이 많이 걸릴 수 있습니다. 다음 내용을 확인해 보세요:
신규 빌드 권장 사항: Capgo Build 사용
이제 다음을 권장합니다: Capgo CLI를 활용한 Capgo Build 네이티브 Capacitor 빌드를 위한 이 Fastlane 가이드는 기존 GitHub Actions 파이프라인을 유지 관리하는 팀을 위해 남겨두었습니다. 하지만 새로운 iOS 빌드는 Capgo CLI를 사용해야 합니다. 이렇게 하면 Fastlane, Xcode 러너, 인증서, 업로드 스크립트를 직접 관리할 필요가 없습니다.
Capgo이 제공하는 CI/CD용 Capgo Build
Fastlane, Xcode 러너, 인증서, 프로비저닝 프로필, 업로드 스크립트 유지 관리 생략 Capgo 빌드 기존 CI/CD 파이프라인에서 서명된 네이티브 iOS 빌드를 실행합니다:
- 기존 파이프라인과 호환: 웹 빌드 후 GitHub Actions, GitLab CI, Jenkins 또는 로컬 스크립트에서 Capgo 빌드를 트리거하고
npx cap sync. - CI 시크릿으로 서명: App Store Connect 키, 인증서, 프로비저닝 프로필, 비밀번호, 팀 ID를 자체 CI 시크릿에 보관합니다.
- 네이티브 러너 관리 불필요: Capgo 빌드는 유지보수되는 Apple 빌드 환경을 제공하므로 macOS 러너, Xcode 이미지, Fastlane 레인을 직접 관리할 필요가 없습니다.
- 아티팩트 및 제출: QA를 위해 서명된 아티팩트를 다운로드하거나 Capgo CLI을 통해 릴리스 빌드를 제출합니다.
요금제
- Capgo 플랜은 월 $12부터
- OTA 업데이트 및 월 15회 내장 빌드 포함
- 추가 빌드 분은 크레딧으로 분당 과금됩니다
수동 설정 가이드
다음 단계를 수행하세요:
Fastlane과 GitHub 액션 및 인증서로 iOS 지속 전달
사전 요구사항
튜토리얼을 계속하기 전에:
- Fastlane이 설치되어 있는지 개발 환경에서 확인하세요.
- iOS 개발자 프로그램 멤버십에 가입되어 있는지 확인하세요.
가격에 대한 중요한 정보

https://github.com/features/actions
이 서비스는 '무료'이며, 선택한 머신에 따라 한도까지.
저희는 macOS가 머신을 사용할 예정이며, 스크린샷에서 가격과 제한 사항을 확인할 수 있습니다 (가격은 튜토리얼 작성 시점 기준이며 향후 변경될 수 있습니다).
요구 사항과 가격에 대해 알렸으니, 계속 진행하겠습니다.
참고: 이 글에서는 App Store Connect에 앱이 생성되어 있다고 가정합니다. 중요한 정보는 Fastlane이 복사합니다!
튜토리얼에서 배울 내용
포스트에서 따를 단계
- Fastlane으로 App Store Connect API 사용
- 요구 사항:
- App Store Connect API 키 생성하기
- App Store Connect API Key 사용하기
- 요구 사항:
- Fastlane 파일 복사
- GitHub Actions 설정
1. Fastlane으로 App Store Connect API 사용
2021년 2월부터 App Store Connect에 로그인하려면 모든 사용자에게 2단계 인증이 필요합니다. Apple ID에 대한 이 추가 보안 계층은 귀하만이 계정에 접근할 수 있도록 보장하는 데 도움이 됩니다.
다음 경로에서 Apple 지원
요구 사항
Fastlane이 App Store Connect API를 사용하여 앱을 업로드하려면 다음을 제공해야 합니다 세 가지 항목:
- 발행자 ID
- 키 ID
- 키 파일 또는 키 내용
App Store Connect API 키 생성
키를 생성하려면 App Store Connect에서 관리자 권한이 필요합니다. 해당 권한이 없다면 관련 담당자에게 이 문서를 공유하세요.
-
로그인 App Store Connect.
-
선택 사용자 및 액세스.

3 — Integration 탭을 선택하세요.

- Generate API Key 또는 Add(+) 버튼을 클릭하세요.

- 키 이름을 입력하세요. 이름은 참고용이며 키 자체의 일부가 아닙니다.

6 — Access에서 키의 역할을 선택하세요. 키에 적용되는 역할은 팀 사용자에게 적용되는 역할과 동일합니다. 보기 역할 권한. 다음을 선택하는 것을 권장합니다 앱 관리자.
- Generate를 클릭하세요.
API 키의 액세스 권한은 특정 앱으로 제한할 수 없습니다.
새 키의 이름, 키 ID, 다운로드 링크 및 기타 정보가 페이지에 표시됩니다.

필요한 세 가지 정보를 여기에서 모두 확인할 수 있습니다.
<1> 이슈 ID. (APPLE_ISSUER_ID secret)
<2> Key ID. (APPLE_KEY_ID secret)
<3> “Download API Key”를 클릭해 API private key를 다운로드하세요. 다운로드 링크는 private key를 아직 다운로드하지 않은 경우에만 표시됩니다. Apple은 private key 사본을 보관하지 않으므로 한 번만 다운로드할 수 있습니다.
🔴 private key는 안전한 곳에 보관하세요. 키를 절대 공유하거나, code repository에 저장하거나, 클라이언트 측 code에 포함해서는 안 됩니다.
App Store Connect API Key 사용하기
JWT 토큰을 생성하여 인증하려면 API Key 파일(다운로드한 p8 파일), Key ID, Issuer ID가 필요합니다. 이 정보를 Fastlane에 전달하는 방법은 여러 가지가 있습니다. 저는 Fastlane의 새로운 action을 사용하기로 했습니다. app_store_connect_api_key. 다른 방법은 다음에서 확인할 수 있습니다. Fastlane 문서. 환경 변수를 설정할 수 있는 대부분의 CI 환경에서 가장 간편한 방식이라고 생각해 이 방법을 소개합니다.
다운로드한 p8 파일을 Base64로 변환하여 시크릿으로 저장하세요 (APPLE_KEY_CONTENT).
base64 -i APPLE_KEY_CONTENT.p8 | pbcopy
이제 API 키를 사용해 Fastlane으로 App Store Connect를 관리할 수 있습니다. 훌륭하죠!
2. 인증서
Xcode를 열고 다음으로 이동하세요 설정 > 계정 > Apple ID > 팀 에서 팀을 선택하세요.

클릭하세요 인증서 관리.
아직 인증서를 생성하지 않았다면 새 인증서를 생성할 수 있습니다.
클릭하세요 + 를 선택한 후 Apple Distribution

그다음 키체인으로 이동해 인증서를 다음 형식으로 다운로드해야 합니다. .p12 다운로드됩니다.
이렇게 하려면 키체인으로 이동해 다음으로 전환해야 합니다. 로그인 키체인으로 이동한 다음 탭 My Certificates에서.

그다음 다운로드할 인증서를 선택할 수 있습니다. (인증서 날짜를 기준으로 확인하세요)
그다음 인증서의 개인 키를 우클릭하고 선택하세요. 내보내기.
파일 형식 선택 개인 정보 교환 (.p12).
그러면 인증서가 파일로 .p12 다운로드됩니다.
터미널에서 파일을 열고 다음 명령을 사용해 Base64로 변환하세요:
base64 -i BUILD_CERTIFICATE.p12 | pbcopy
이 값이 BUILD_CERTIFICATE_BASE64 비밀키가 됩니다. 또한 요청 시 인증서 비밀번호를 입력하세요. 이 비밀번호가 P12_PASSWORD 비밀키가 됩니다.
3. 프로비저닝 프로필
열기 Apple Developer 그리고 올바른 팀을 선택하세요.
그런 다음, 다음을 클릭해 새 프로필을 만드세요. +

그리고 다음을 선택하세요. App Store Connect.

그런 다음 올바른 앱을 선택해야 합니다. 와일드카드는 사용할 수 없으며, 사용하면 서명이 실패하니 주의하세요.

이전에 생성한 올바른 인증서를 선택하세요(만료 날짜가 오늘과 같은 날짜인지 확인)하고 클릭하세요 계속.

마지막으로 프로파일 이름을 입력하고 클릭하세요 생성.
이 이름은 Fastlane에서 프로파일을 식별하는 값으로 사용됩니다
APPLE_PROFILE_NAME.

프로파일을 다음 형식으로 다운로드할 수 있습니다 .mobileprovision 다운로드됩니다.

프로파일을 Base64로 변환하고 secret으로 저장하세요 (BUILD_PROVISION_PROFILE_BASE64).
base64 -i BUILD_PROVISION_PROFILE.mobileprovision | pbcopy
4. Fastlane 파일 복사
Fastlane은 일반적인 모바일 개발 작업을 자동화하기 위해 만들어진 Ruby 라이브러리입니다. Fastlane을 사용하면 보통 Android Studio에서 수행하던 작업을 실행하는 일련의 “actions”를 묶은 커스텀 “lanes”를 구성할 수 있습니다. Fastlane으로 많은 것을 할 수 있지만, 이 튜토리얼에서는 몇 가지 핵심 action만 사용하겠습니다.
Capacitor/Ionic 프로젝트 루트에 Fastlane 폴더를 만들고, 해당 폴더에 Fastfile을 추가하세요:
- 폴더:
<project-root>/fastlane/ - 파일:
<project-root>/fastlane/Fastfile
이것은 package.json, capacitor.config.*, 그리고 ios/ 폴더와 같은 수준입니다. 안에 만들지 마세요 ios/App/.
platform :ios do
desc 'Export ipa and submit to TestFlight'
lane :beta do
keychain_info = { keychain_name: "ios-build-#{Time.now.to_i}.keychain", keychain_password: SecureRandom.uuid }
begin
setup_signing(keychain_info)
bump_build_number
build_app_with_signing(keychain_info)
submit_to_testflight
ensure
cleanup_keychain(keychain_info)
end
end
private_lane :setup_signing do |options|
create_keychain(
name: options[:keychain_name],
password: options[:keychain_password],
unlock: true,
timeout: 0,
lock_when_sleeps: false,
add_to_search_list: true
)
import_cert(options)
install_profile
update_project_settings
end
lane :bump_build_number do
file = File.read('../package.json')
data_hash = JSON.parse(file)
api_key = app_store_connect_api_key(
key_id: ENV['APPLE_KEY_ID'],
issuer_id: ENV['APPLE_ISSUER_ID'],
key_content: ENV['APPLE_KEY_CONTENT'],
is_key_content_base64: true,
duration: 1200,
in_house: false
)
build_num = app_store_build_number(
api_key: api_key,
app_identifier: ENV['BUNDLE_IDENTIFIER'],
live: false
)
build_num = build_num + 1
UI.message("Bumped build number to #{build_num}")
increment_build_number(
build_number: build_num,
xcodeproj: "./ios/App/App.xcodeproj",
skip_info_plist: true
)
end
private_lane :import_cert do |options|
cert_path = "#{Dir.tmpdir}/build_certificate.p12"
File.write(cert_path, Base64.decode64(ENV['BUILD_CERTIFICATE_BASE64']))
import_certificate(
certificate_path: cert_path,
certificate_password: ENV['P12_PASSWORD'] || "",
keychain_name: options[:keychain_name],
keychain_password: options[:keychain_password],
log_output: true
)
File.delete(cert_path)
end
private_lane :cleanup_keychain do |options|
delete_keychain(
name: options[:keychain_name]
)
end
private_lane :install_profile do
profile_path = "#{Dir.tmpdir}/build_pp.mobileprovision"
File.write(profile_path, Base64.decode64(ENV['BUILD_PROVISION_PROFILE_BASE64']))
UI.user_error!("Failed to create provisioning profile at #{profile_path}") unless File.exist?(profile_path)
ENV['PROVISIONING_PROFILE_PATH'] = profile_path
install_provisioning_profile(path: profile_path)
File.delete(profile_path)
end
private_lane :update_project_settings do
update_code_signing_settings(
use_automatic_signing: false,
path: "./ios/App/App.xcodeproj",
code_sign_identity: "iPhone Distribution",
profile_name: ENV['APPLE_PROFILE_NAME'],
bundle_identifier: ENV['BUNDLE_IDENTIFIER'],
team_id: ENV['APP_STORE_CONNECT_TEAM_ID']
)
update_project_team(
path: "./ios/App/App.xcodeproj",
teamid: ENV['APP_STORE_CONNECT_TEAM_ID']
)
end
private_lane :build_app_with_signing do |options|
unlock_keychain(
path: options[:keychain_name],
password: options[:keychain_password],
set_default: false
)
build_app(
workspace: "./ios/App/App.xcworkspace",
scheme: "App",
configuration: "Release",
export_method: "app-store",
output_name: "App.ipa",
export_options: {
provisioningProfiles: {
ENV['BUNDLE_IDENTIFIER'] => ENV['APPLE_PROFILE_NAME']
}
},
xcargs: "-verbose",
buildlog_path: "./build_logs",
export_xcargs: "-allowProvisioningUpdates",
)
end
private_lane :submit_to_testflight do
api_key = app_store_connect_api_key(
key_id: ENV['APPLE_KEY_ID'],
issuer_id: ENV['APPLE_ISSUER_ID'],
key_content: ENV['APPLE_KEY_CONTENT'],
is_key_content_base64: true,
duration: 1200,
in_house: false
)
pilot(
api_key: api_key,
skip_waiting_for_build_processing: true,
skip_submission: true,
distribute_external: false,
notify_external_testers: false,
ipa: "./App.ipa"
)
end
end
5. 시크릿 설정
GitHub Actions는 다음 단계에서 설정하는 저장소 시크릿을 사용합니다. 로컬 .env 파일은 자신의 머신에서 Fastlane을 실행하거나 테스트할 때만 필요합니다.
로컬 테스트를 하려면 <project-root>/fastlane/.env 옆에 Fastfile를 생성하세요. 이 파일은 커밋하지 마세요. fastlane/.env …에 .gitignore 를 먼저 추가하세요(또는 이미 무시되고 있는지 확인하세요). 예시:
APP_STORE_CONNECT_TEAM_ID=UVTJ336J2D
BUNDLE_IDENTIFIER=ee.forgr.testfastlane
# See previous section for these secrets
BUILD_CERTIFICATE_BASE64=
BUILD_PROVISION_PROFILE_BASE64=
APPLE_KEY_ID=
APPLE_ISSUER_ID=
APPLE_KEY_CONTENT=
P12_PASSWORD=
APPLE_PROFILE_NAME=
APP_STORE_CONNECT_TEAM_ID 가져오기
다음으로 이동: 개발자 센터 로 이동한 다음 Membership details 섹션까지 아래로 스크롤하세요.
Team ID 에 설정해야 하는 값입니다 APP_STORE_CONNECT_TEAM_ID secret.
BUNDLE_IDENTIFIER 가져오기
- Xcode 열기
- 프로젝트 탐색기에서
App를 더블클릭하세요 - 그런 다음 탭을 클릭하세요
Signing and Capabilities - 의 값을 복사하세요
Bundle identifier. 이 값은BUNDLE_IDENTIFIERsecret.
6. 빌드 처리
GitHub Actions에서 비용은 분 단위로 청구됩니다 CI/CD 워크플로우 실행에 사용했습니다. 제 경험상 App Store Connect에서 빌드가 처리되기까지 약 10~15분이 걸립니다.
비공개 프로젝트의 경우, 빌드당 예상 비용은 최대 $0.08/분 x 15분 = $1.2또는 프로젝트 구성 및 의존성에 따라 더 많이 발생할 수 있습니다.
비공개 프로젝트의 비용이 걱정된다면 설정할 수 있습니다 skip_waiting_for_build_processing 대상 true. 이를 통해 App Store Connect의 빌드 처리 완료를 기다릴 필요가 없어 빌드 시간을 절약할 수 있습니다.
단, 트레이드오프가 있습니다. 빌드를 사용자에게 배포하기 전에 App Store Connect에서 앱의 규정 준수 정보를 수동으로 업데이트해야 합니다.
이 최적화는 빌드 시간에 비용이 발생하는 프라이빗 프로젝트에서 주로 유용합니다. 공개/무료 프로젝트는 빌드 시간이 무료이므로 이 설정을 활성화할 필요가 없습니다. 자세한 내용은 GitHub의 요금 페이지를 참조하세요.
7. GitHub Actions 설정하기
GitHub secrets 구성하기
다음 파일에서 secrets를 복사하여 .env GitHub repository secrets에 붙여넣으세요.
다음으로 이동: 설정 > Secrets 및 변수 > 액션 > 새로운 repository secret
2. BUILD_CERTIFICATE_BASE64 - Base64로 인코딩된 인증서.
3. BUILD_PROVISION_PROFILE_BASE64 - Base64로 인코딩된 프로비저닝 프로필.
4. BUNDLE_IDENTIFIER - 앱의 번들 식별자.
5. APPLE_KEY_ID — App Store Connect API 키 🔺Key ID.
6. APPLE_ISSUER_ID — App Store Connect API 키 🔺발행자 ID.
7. APPLE_KEY_CONTENT — App Store Connect API Key 🔺 Key 내용: .p8, 확인하세요
8. GitHub workflow 파일 구성
GitHub workflow 디렉토리를 생성합니다.
cd .github/workflows
해당 폴더 안에 workflow 파일을 만들고 이름은 build-upload-ios.yml로 지정한 뒤 다음을 추가하세요.
name: Build source code on ios
on:
push:
tags:
- '*'
jobs:
build_ios:
runs-on: macOS-latest
steps:
- uses: actions/checkout@v6
- name: Set Node.js
uses: actions/setup-node@v6
with:
node-version: 24
cache: npm
- name: Install dependencies
id: install_code
run: npm ci
- name: Build
id: build_code
run: npm run build
- uses: actions/cache@v5
with:
path: ios/App/Pods
key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}
restore-keys: |
${{ runner.os }}-pods-
- name: Sync
id: sync_code
run: npx cap sync
- uses: ruby/setup-ruby@v1
with:
ruby-version: '3.0'
bundler-cache: true
- uses: maierj/fastlane-action@v3.1.0
env:
APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
BUNDLE_IDENTIFIER: ${{ secrets.BUNDLE_IDENTIFIER }}
BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}
APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
APPLE_PROFILE_NAME: ${{ secrets.APPLE_PROFILE_NAME }}
with:
lane: ios beta
- name: Upload release bundle
uses: actions/upload-artifact@v6
with:
name: ios-release
path: ./App.ipa
retention-days: 10
이 workflow는 각 GitHub 태그가 있습니다tag 자동화가 필요하면 다음을 참고하세요: GitHub actions를 이용한 자동 빌드 및 릴리스 먼저.
그다음 이 워크플로우가 NodeJS 의존성을 가져와 설치하고 JavaScript 앱을 빌드합니다.
새 커밋을 보낼 때마다 TestFlight에서 릴리스가 빌드됩니다.
앱은 Ionic을 사용할 필요가 없고 Capacitor 베이스만 필수입니다. 기존 Cordova 모듈이 있어도 되지만 Capacitor JS 플러그인을 사용하는 것이 좋습니다.
8. 워크플로 트리거
커밋 생성
커밋을 만들면, 리포지토리에서 활성 워크플로우를 확인할 수 있습니다.
워크플로 트리거
새 커밋을 브랜치에 푸시하여 main 또는 development 워크플로를 트리거합니다.

몇 분 후면 App Store Connect 대시보드에서 빌드를 확인할 수 있습니다.

9. 로컬 머신에서 배포할 수 있나요?
네, 가능합니다. 매우 간단합니다.
항상 그랬듯 Xcode로 앱을 빌드하고 서명할 수 있습니다.
관련 글
CI/CD 설정 가이드
- GitHub Actions를 이용한 자동 Capacitor Android 빌드 - Android CI/CD 설정 완벽 가이드
- GitHub Actions를 이용한 자동 빌드 및 릴리스 - 전체 CI/CD 파이프라인 튜토리얼
- GitHub Actions로 개발 및 프로덕션 빌드 관리하기 - 환경 관리
- Match를 이용한 자동 Capacitor iOS Build - Fastlane Match를 사용하는 대안
대체 CI/CD 플랫폼
- GitLab CI로 빌드하기 - GitLab 대안
- CodeMagic으로 빌드하기 - CodeMagic 설정 가이드
Live Updates 및 배포
- Capgo Live Updates 문서 - 앱에 OTA 업데이트 추가
- Capgo CI/CD 통합 - 파이프라인에 라이브 업데이트 통합
감사합니다
이 블로그는 다음 아티클을 기반으로 작성되었습니다:
인증서와 함께 GitHub 액션을 사용한 자동 Capacitor iOS 빌드 계속하기
사용 중이라면 인증서를 포함한 GitHub actions 기반의 자동 Capacitor iOS build CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.