빌드/배포

Tuist 프로젝트 생성

초기 설정

Tuist 설치 및 의존성 설치

bash

# Tuist가 설치되어 있어야 합니다
# 의존성 설치 및 프로젝트 생성
make refresh

make refresh는 다음을 순서대로 실행합니다:

tuist clean -- 캐시 정리
tuist install -- SPM 의존성 설치
make sync -- 프로젝트 생성 + Workspace 열기

프로젝트 동기화

bash

# Project.swift 변경 후 프로젝트 재생성
make sync

make sync는 다음을 실행합니다:

tuist generate -- Xcode 프로젝트 파일 생성
open TRULOOP.xcworkspace -- Workspace 열기

주요 Makefile 명령어

명령어	설명
`make refresh`	클린 + 의존성 설치 + 프로젝트 생성
`make sync`	프로젝트 생성 + Workspace 열기
`make build`	Debug 빌드 (시뮬레이터)
`make build-clean`	클린 빌드
`make clean`	Xcode 클린
`make version v=1.0.0`	앱 버전 설정 (빌드 번호 자동 1)
`make version v=1.0.0 b=42`	앱 버전 + 빌드 번호 설정
`make version-hash`	Git 해시값을 빌드 번호로 사용
`make version-timestamp`	KST 타임스탬프를 빌드 번호로 사용

빌드 구성 (Configurations)

Debug / Release

항목	Debug	Release
구성 이름	`Debug`	`Release`
xcconfig	`TRULOOP-Debug.xcconfig`	`TRULOOP-Release.xcconfig`
Firebase plist	`GoogleService-Info-Sandbox.plist`	`GoogleService-Info-Production.plist`
URL Scheme	`truloop.dev`	`truloop`
Bundle ID Suffix	`.sandbox` (개발)	(없음 - 프로덕션)

xcconfig 파일 구조

Tuist/Config/
  Project-Shared.xcconfig                        -- 프로젝트 공통 빌드 설정
  Project-Debug.xcconfig
  Project-Release.xcconfig
  TRULOOP-Shared.xcconfig                        -- App 공통 (MARKETING_VERSION, CURRENT_PROJECT_VERSION)
  TRULOOP-Debug.xcconfig                         -- App Debug 전용
  TRULOOP-Release.xcconfig                       -- App Release 전용
  TRULOOPTests-Shared.xcconfig
  TRULOOPTests-Debug.xcconfig
  TRULOOPTests-Release.xcconfig
  TruloopShare-Shared.xcconfig
  TruloopShare-Debug.xcconfig
  TruloopShare-Release.xcconfig
  TruloopLiveActivityExtension-Shared.xcconfig
  TruloopLiveActivityExtension-Debug.xcconfig
  TruloopLiveActivityExtension-Release.xcconfig
  TruloopNotificationService-Shared.xcconfig
  TruloopNotificationService-Debug.xcconfig
  TruloopNotificationService-Release.xcconfig

Firebase 설정 관리

빌드 시 Build Phase 스크립트를 통해 적절한 Firebase 설정 파일이 복사됩니다:

bash

# Pre-build Script: "Copy Firebase Configuration"
case "${CONFIGURATION}" in
  Debug)
    SRC="${SRCROOT}/Resources/GoogleService-Info-Sandbox.plist"
    ;;
  Release)
    SRC="${SRCROOT}/Resources/GoogleService-Info-Production.plist"
    ;;
esac
cp "$SRC" "$DEST"

주의

GoogleService-Info-Sandbox.plist와 GoogleService-Info-Production.plist는 빌드 리소스에서 제외되어 있으며, 빌드 시점에 스크립트로 복사됩니다. 두 파일이 App/Resources/ 디렉토리에 존재해야 합니다.

환경 변수 및 Config 관리

Config.swift 자동 업데이트

빌드 시 make update-config 명령이 실행되어 Config.swift 파일의 플레이스홀더를 환경 변수 값으로 교체합니다:

Pre-build: Config 백업 및 업데이트

Config.swift를 Config.swift.temp로 백업한 후, .env 파일 또는 CI 환경 변수의 값으로 플레이스홀더를 교체합니다.

Debug 빌드: {KEY}_DEBUG 환경 변수 우선 사용
Release 빌드: {KEY}_RELEASE 환경 변수 우선 사용

Post-build: Config 복원

빌드 완료 후 Config.swift.temp에서 원본 Config.swift를 복원합니다.

Build Phase 스크립트

App 타겟에는 4개의 Build Phase 스크립트가 설정되어 있습니다:

순서	이름	타이밍	역할
1	Copy Config File and Update Config	Pre-build	Config.swift 백업 + 환경 변수로 업데이트
2	Copy Firebase Configuration	Pre-build	환경별 Firebase plist 복사
3	Restore Original Config File	Post-build	Config.swift 원본 복원
4	Firebase Crashlytics dSYM Upload	Post-build	dSYM 파일 업로드

버전 관리

앱 버전은 xcconfig 파일에서 관리됩니다:

설정	xcconfig 키	설명
앱 버전	`MARKETING_VERSION`	사용자에게 보이는 버전 (예: 1.16.1)
빌드 번호	`CURRENT_PROJECT_VERSION`	내부 빌드 식별자

Makefile을 통해 버전을 변경할 수 있습니다:

bash

# 버전 1.2.0, 빌드 번호 자동 1 설정
make version v=1.2.0

# 버전 1.2.0, 빌드 번호 5 설정 + 자동 커밋
make version v=1.2.0 b=5 commit=true

# Git 해시를 빌드 번호로 사용
make version-hash

# KST 타임스탬프를 빌드 번호로 사용
make version-timestamp

CI/CD 배포 (Bitrise)

Makefile을 통해 Bitrise 원격 워크플로우를 트리거할 수 있습니다:

명령어	워크플로우	설명
`make deploy-sandbox`	`deploy_sandbox`	Sandbox (개발) 환경 배포
`make deploy-production`	`deploy_production`	Production 환경 배포
`make deploy-appstore`	`deploy_production_for_appstore`	App Store 제출
`make deploy-logs`	-	최근 배포 API 응답 로그 확인

bash

# Sandbox 배포 (자동으로 최근 커밋 메시지를 배포 메시지로 사용)
make deploy-sandbox

# 커스텀 메시지로 Production 배포
make deploy-production message="v1.2.0 릴리즈"

# 최근 배포 결과 확인
make deploy-logs

정보

Bitrise API Token과 App ID는 .env 파일에 BITRISE_API_TOKEN과 BITRISE_APP_ID로 설정합니다. Token은 token= 파라미터로도 전달할 수 있습니다.

Fastlane

코드 서명과 빌드/배포 자동화에 Fastlane을 사용합니다. Bitrise CI에서 Fastlane lane을 호출하여 빌드와 배포를 처리합니다.

주요 Lane

Lane	설명
`sandbox`	Sandbox (개발) 빌드. `match development` → `build_app` (Debug)
`production`	Production 빌드 + TestFlight 업로드. `match appstore` → `build_app` (Release) → `upload_to_testflight`
`upload_firebase_distribution`	Sandbox IPA를 Firebase App Distribution에 업로드 + Slack 알림
`register_new_device`	새 기기 UDID 등록 + Development 프로비저닝 프로필 갱신
`match_sandbox`	Development 인증서/프로필 동기화 (readonly)
`match_production`	App Store 인증서/프로필 동기화 (readonly)

코드 서명 (Fastlane Match)

Fastlane Match를 사용하여 인증서와 프로비저닝 프로필을 Git 저장소에서 관리합니다.

항목	값
인증서 저장소	`git@github.com:butbeautifulco/ios_certificates.git` (main 브랜치)
Team ID	`DB2KTB96F2`
Sandbox 서명 유형	`development`
Production 서명 유형	`appstore`

App Identifier 목록:

Bundle ID	타겟
`com.butbeautifulco.truloop`	Production App
`com.butbeautifulco.truloop.share`	Production Share Extension
`com.butbeautifulco.truloop.liveactivity`	Production Live Activity Extension
`com.butbeautifulco.truloop.notification-service`	Production Notification Service Extension
`com.butbeautifulco.truloop.sandbox`	Sandbox App
`com.butbeautifulco.truloop.sandbox.share`	Sandbox Share Extension
`com.butbeautifulco.truloop.sandbox.liveactivity`	Sandbox Live Activity Extension
`com.butbeautifulco.truloop.sandbox.notification-service`	Sandbox Notification Service Extension

배포 흐름

Sandbox 배포

Fastlane sandbox lane이 Development 인증서로 빌드하여 IPA를 생성합니다. 이후 upload_firebase_distribution lane으로 Firebase App Distribution에 업로드하고, Slack으로 테스트 링크를 공유합니다.

Production 배포

Fastlane production lane이 App Store 인증서로 빌드한 후 TestFlight에 자동 업로드합니다. 배포 메시지는 Bitrise의 BITRISE_GIT_MESSAGE 환경 변수에서 가져옵니다.

App Store 제출

TestFlight에 업로드된 빌드를 App Store Connect에서 수동으로 제출합니다.

App Store Connect API

Fastlane은 App Store Connect API Key를 통해 인증합니다:

환경 변수	설명
`APP_STORE_CONNECT_API_KEY_KEY_ID`	API Key ID
`APP_STORE_CONNECT_API_KEY_ISSUER_ID`	Issuer ID
`APP_STORE_CONNECT_API_KEY_KEY_CONTENT`	API Key 내용 (p8)

딥링크 테스트

시뮬레이터에서 딥링크를 테스트할 수 있습니다:

bash

# Sandbox (개발) 앱
make deeplink-sandbox url="profile?id=123"

# Production 앱
make deeplink-production url="loop/detail?eid=abc"

변경 이력

날짜	내용
2026-03-10	xcconfig 파일 목록에 누락된 파일 추가 (Project-Shared, TRULOOPTests-*, TruloopNotificationService-Shared), `make deploy-logs` 명령어 추가, Bitrise 환경 변수에 `BITRISE_APP_ID` 추가, Fastlane 섹션 신규 작성 (lane 목록, Match 코드 서명, 배포 흐름, App Store Connect API)

Loop

Recap

Mission

User

Admin

Chat

AI 비서

알림

미디어

AI 콘텐츠

2026

Core (Ktor)

Media Service (Go)

AI Server (FastAPI)

Assistant (pydantic-ai)

Functions (Lambda)

Story Worker (Serverless)

Invite (Next.js)

Admin Dashboard (React/Vite)

빌드/배포 ​

Tuist 프로젝트 생성 ​

초기 설정 ​

Tuist 설치 및 의존성 설치 ​

프로젝트 동기화 ​

주요 Makefile 명령어 ​

빌드 구성 (Configurations) ​

Debug / Release ​

xcconfig 파일 구조 ​

Firebase 설정 관리 ​

환경 변수 및 Config 관리 ​

Config.swift 자동 업데이트 ​

Pre-build: Config 백업 및 업데이트 ​

Post-build: Config 복원 ​

Build Phase 스크립트 ​

버전 관리 ​

CI/CD 배포 (Bitrise) ​

Fastlane ​

주요 Lane ​

코드 서명 (Fastlane Match) ​

배포 흐름 ​

Sandbox 배포 ​

Production 배포 ​

App Store 제출 ​

App Store Connect API ​

딥링크 테스트 ​

변경 이력 ​

빌드/배포

Tuist 프로젝트 생성

초기 설정

Tuist 설치 및 의존성 설치

프로젝트 동기화

주요 Makefile 명령어

빌드 구성 (Configurations)

Debug / Release

xcconfig 파일 구조

Firebase 설정 관리

환경 변수 및 Config 관리

Config.swift 자동 업데이트

Pre-build: Config 백업 및 업데이트

Post-build: Config 복원

Build Phase 스크립트

버전 관리

CI/CD 배포 (Bitrise)

Fastlane

주요 Lane

코드 서명 (Fastlane Match)

배포 흐름

Sandbox 배포

Production 배포

App Store 제출

App Store Connect API

딥링크 테스트

변경 이력