fastlane deliver로 앱스토어 스크린샷 업로드
PNG 100여 장을 App Store Connect에 손으로 끌어다 놓는 방식은 두 번째 로케일부터
무너집니다. fastlane deliver는 모든 언어·모든 디바이스의 스크린샷 세트를
명령어 하나로 업로드합니다. deliver가 기대하는 정확한 폴더 구조, API 키 설정, 그리고
다른 건 아무것도 건드리지 않게 하는 플래그를 정리했습니다. 최종 확인: 2026년 6월.
deliver가 기대하는 폴더 구조
deliver는 fastlane/screenshots/를 읽습니다 — App Store
Connect 로케일당 하위 폴더 하나, 이미지 파일은 그 안에 평평하게(하위 폴더를
재귀 탐색하지 않습니다). 디바이스 슬롯은 각 이미지의 픽셀 해상도에서 자동 감지되므로,
iphone_01.png 같은 이름 접두사는 정렬용이지 라우팅용이 아닙니다:
fastlane/
Appfile
Deliverfile
screenshots/
en-US/
iphone_01.png ← 1320×2868 → iPhone 6.9″ 슬롯
iphone_02.png
ipad_01.png ← 2064×2752 → iPad 13″ 슬롯
ko/
iphone_01.png
...
de-DE/
...이 목록에 함정이 두 개 숨어 있습니다:
- 폴더 이름은 ASC 로케일 코드이지 단순 ISO 코드가 아닙니다:
en-US,es-ES,fr-FR,de-DE— 단ko,ja는 짧은 형태 그대로입니다.en이라는 폴더는 아무것도 업로드하지 않습니다. - 해상도는 슬롯별로 정확해야 합니다(사이즈 표 참고) — 크기가 틀린 이미지는 건너뛰거나 반려될 뿐, 절대 스케일되지 않습니다.
인증: App Store Connect API 키를 쓰세요
Apple ID로 인증하지 마세요 — 2FA 프롬프트가 자동화를 끊습니다. 대신 API 키를
만드세요: App Store Connect → 사용자 및 액세스 → 통합 →
App Store Connect API → 키 생성, .p8을 한 번만 다운로드하고
Key ID와 Issuer ID를 적어 둡니다. 그 세 가지를 deliver가 읽을 수 있는
JSON 파일에 넣습니다:
{
"key_id": "YOUR_KEY_ID",
"issuer_id": "YOUR_ISSUER_ID",
"key": "-----BEGIN PRIVATE KEY-----\n…p8 내용…\n-----END PRIVATE KEY-----",
"duration": 1200,
"in_house": false
}키는 내 컴퓨터를 떠나지 않습니다 — fastlane이 로컬에서 이 키로 단기 토큰을 서명합니다.
스크린샷 전용 최소 Deliverfile
기본 설정의 deliver는 스토어 메타데이터까지 관리하려고 합니다.
스크린샷 전용 파이프라인이라면 이렇게 못 박으세요:
# fastlane/Deliverfile
overwrite_screenshots(true)
skip_binary_upload(true)
skip_metadata(true)# fastlane/Appfile
app_identifier("com.yourcompany.app")그다음 fastlane/이 들어 있는 폴더에서:
fastlane deliver --api_key_path ./asc_api_key.json
deliver는 업로드할 내용의 HTML 미리보기를 보여주고 확인을 요청합니다;
CI에서는 --force로 건너뛰세요.
overwrite_screenshots(true)는 로케일별 기존 세트를 교체합니다 —
이 옵션이 없으면 deliver는 이미 올라가 있는 스크린샷을 덮어쓰기를 거부합니다.
screenshots/<asc-locale>/<device>_NN.png 구조로 정리되고,
Appfile, Deliverfile, API 키 템플릿, upload.sh까지 함께 들어 있습니다.
압축 풀고, 값 두 개 채우고, 실행. →
FAQ
deliver가 앱 바이너리나 메타데이터를 건드리나요?
위 Deliverfile이라면 아닙니다 — skip_binary_upload와 skip_metadata가
실행 범위를 스크린샷으로 한정합니다. 라이브 앱에 돌려도 안전합니다.
스크린샷을 바꾸려면 새 앱 버전이 필요한가요?
네 — 스크린샷은 버전에 붙고, 아직 라이브가 아닌 버전(예: “제출 준비 중”)의 세트만
수정할 수 있습니다. 업로드 자체는 아무것도 제출하지 않습니다.
deliver는 이미지가 어느 디바이스 슬롯인지 어떻게 아나요?
순전히 픽셀 크기로 압니다. 1320×2868은 iPhone 6.9″ 슬롯, 2064×2752는 iPad 13″ —
내보내기 규격이 정확해야 하는 또 하나의 이유입니다.