PetAI 팀 CI 운영 가이드

대상: PetAI 저장소에서 Unity·iOS·AI·공통 계약을 작업하는 팀원
기준 저장소: mornye-minor-gallery/PetAI
기준일: 2026-07-25 KST
현재 상태: 자동 경량 검사와 수동 Unity/iOS 게이트 운영 가능 · 실제 iPhone 실행은 아직 미검증

30초 요약

팀원이 기억할 흐름은 네 단계다.

최신 main에서 작업 브랜치를 만든다.
Draft PR을 열어 자동 CI 결과를 먼저 본다.
작업 위험도에 따라 Unity 또는 iOS 수동 게이트를 실행한다.
실패 원인과 미검증 항목을 PR에 남기고, 팀원 검토 후 Squash merge한다.

작업 브랜치
  → Draft PR
  → 자동 경량 CI
  → Ready for review
  → 위험도별 수동 CI
  → 사람 리뷰
  → Squash merge

중요: CI가 초록색이어도 실제 iPhone에서 앱이 열리고 Gemma가 동작한다는 뜻은 아니다. 각 검사가 무엇을 증명하는지는 아래에서 구분한다.

CI란 무엇인가

CI는 팀원이 코드를 GitHub에 올릴 때마다, 정해 둔 검사를 깨끗한 컴퓨터에서 자동 또는 수동으로 다시 실행하는 장치다.

PetAI에서는 다음 실수를 조기에 잡는 데 사용한다.

Unity 버전을 실수로 바꿈
JSON 필수 필드나 공통 contract 이름을 삭제함
GitHub Actions YAML을 잘못 수정함
Unity C# 코드가 컴파일되지 않음
EditMode·PlayMode 테스트가 깨짐
Swift 패키지 계약이 깨짐
Unity가 만든 iOS Xcode 프로젝트에 Swift bridge나 LiteRT-LM이 빠짐
생성된 Xcode 프로젝트가 iOS 앱으로 컴파일되지 않음

반대로 현재 CI만으로는 다음을 증명하지 못한다.

서명된 앱이 실제 iPhone에 설치되는가
Unity 화면과 Swift bridge가 기기에서 실제로 통신하는가
Gemma 모델이 iPhone 메모리 안에서 로드되는가
응답 스트리밍이 자연스러운가
장시간 실행 시 메모리·발열 문제 없이 유지되는가

팀원 실제 작업 순서

1. 작업 시작

git switch main
git pull --ff-only
git switch -c <분야>/<짧은-작업명>

브랜치 예시:

feat/relationship-event
fix/save-recovery
ai/gemma-streaming
ci/ios-device-gate
docs/backend-contract

한 브랜치에는 가능한 한 하나의 목적만 담는다.

2. Draft PR 열기

아직 완성되지 않았더라도 Draft PR을 먼저 연다. 그러면 변경 경로에 맞는 자동 검사가 실행된다.

PR 본문에는 최소한 다음을 적는다.

무엇을 바꿨는가
왜 바꿨는가
어떤 자동 검사가 실행됐는가
직접 확인한 내용은 무엇인가
아직 확인하지 못한 내용은 무엇인가

3. 자동 검사 확인

빨간 검사가 있으면 Details를 눌러 실패한 단계와 로그를 확인한다. 수정 후 같은 브랜치에 push하면 자동 검사가 다시 돈다.

4. Ready for review 전환

작업이 끝나고 자동 검사가 통과하면 Draft를 해제한다. Unity gameplay·저장·iOS 연동처럼 위험한 변경은 아래 수동 게이트도 실행한다.

5. 리뷰와 병합

관련 CI가 모두 초록색인지 확인한다.
미검증 항목이 숨겨져 있지 않은지 확인한다.
팀원 한 명 이상이 변경 내용을 읽는다.
Squash merge로 main에 합친다.

현재 저장소 요금제 제약으로 main 직접 push를 GitHub 규칙으로 완전히 차단하지 못한다. 따라서 팀 규칙으로 main 직접 push를 금지한다.

내 변경에는 무엇이 도는가

변경 영역	자동 실행	추가로 실행할 검사
`unity/**`	Unity static validation	gameplay·save·scene 변경이면 Unity Ubuntu Personal tests
`contracts/**`	Unity static validation	contract 소비 모듈의 테스트와 리뷰
`ios/EdgeLLM/**`	iOS Swift package tests	실제 모델 연동 변경이면 Unity iOS export
`ios/ThirdParty/LiteRTLM/**`	iOS Swift package tests	Unity iOS export 필수
`ios/UnityBridge/**`	iOS Swift package tests	Unity iOS export 필수
`.github/workflows/**`	경로에 따라 관련 검사	변경한 workflow를 수동 실행해 확인
문서만 변경	대부분 없음	링크·내용을 사람이 확인
백엔드	전용 CI 없음	현재 공백. 백엔드 스택 확정 후 별도 구성

자동 CI 게이트

A. Unity static validation

언제 실행되는가

unity/**, contracts/**, Unity 관련 workflow·검증 script가 포함된 PR에서 자동으로 실행된다.

무엇을 하는가

Unity 프로젝트 버전과 CI 설정을 검사한다.
Unity 관련 workflow 계약을 검사한다.
contracts/validate_contracts.mjs로 버전 고정 데이터 계약을 검사한다.

장점

Unity Editor를 실행하지 않아 빠르고 라이선스를 소모하지 않는다.

한계

C# 전체 컴파일, EditMode, PlayMode, 실제 Player 실행은 확인하지 않는다.

Unity static validation 열기

B. iOS Swift package tests

언제 실행되는가

EdgeLLM, LiteRT-LM vendor manifest, UnityBridge 관련 PR에서 자동으로 실행된다.

무엇을 하는가

macOS runner에서 Swift 6.3.1 toolchain을 사용한다.
ios/EdgeLLM의 Swift package test를 실행한다.
ios/ThirdParty/LiteRTLM package manifest를 검증한다.

현재 검증 결과

15/15 tests PASS
검증 run: 30115639642

한계

Swift 단위 계약은 확인하지만 Gemma 모델을 실제 iPhone에서 로드하지는 않는다.

iOS Swift package tests 열기

C. Codex PR review

언제 실행되는가

같은 저장소의 non-draft PR이 열리거나 업데이트될 때 실행 대상으로 잡힌다.

현재 상태

읽기 전용 권한과 drop-sudo 안전 설정은 적용되어 있다.
PR이 조작한 AGENTS.md를 자동 지시로 읽지 않도록 차단했다.
현재 저장소에 OPENAI_API_KEY가 없어 실제 Codex 리뷰 단계는 skip된다.
workflow가 초록색이어도 Codex가 코드를 읽었다는 의미는 아니다.

실제 자동 리뷰를 켜려면 저장소 관리자만 GitHub Settings의 Actions secret에 OPENAI_API_KEY를 추가한다. 키 값은 채팅·PR·로그에 올리지 않는다.

Codex PR review 열기

수동 CI 게이트

수동 workflow는 PR 화면에서 자동으로 시작되지 않는다. 변경한 브랜치를 선택해 직접 실행해야 한다.

D. Unity Ubuntu Personal tests

실행 경로

GitHub 저장소
  → Actions
  → Unity Ubuntu Personal tests
  → Run workflow
  → 작업 브랜치 선택
  → Run workflow

언제 필요한가

gameplay 규칙 변경
저장·복구·migration 변경
scene·resource·Builder 변경
PlayMode 동작 변경
Unity package 또는 Editor 설정 변경

무엇을 증명하는가

Unity 6000.5.4f1 활성화 성공
C# 컴파일 성공
EditMode와 PlayMode 테스트 통과
테스트 artifact 생성

현재 검증 결과

EditMode 40/40 PASS
PlayMode 12/12 PASS
검증 run: 30110646902

주의

Unity Personal 라이선스를 공유하는 무거운 workflow다. 다른 Unity 수동 작업과 동시에 돌지 않고 순서대로 대기한다.

Unity Ubuntu Personal tests 열기

E. Unity iOS export

실행 경로

GitHub 저장소
  → Actions
  → Unity iOS export
  → Run workflow
  → 작업 브랜치 선택
  → Run workflow

언제 필요한가

ios/UnityBridge/** 변경
LiteRT-LM dependency 변경
Unity와 Swift 사이 호출 contract 변경
iOS Player settings·plugin import 설정 변경
AI 통합 release 후보

두 단계로 진행된다

Ubuntu: Unity가 unsigned Xcode project를 만든다.
macOS: 생성된 Xcode project를 서명 없이 Release iOS 앱으로 컴파일한다.

검사 항목

Unity iOS export 성공
Unity-iPhone.xcodeproj 존재
CLiteRTLM.xcframework 포함
PetAIUnityBridge.swift 포함
Xcode project가 두 파일을 실제 참조
Xcode 16.4에서 unsigned Release compile 성공
.app 결과물이 정확히 하나 생성

현재 검증 결과

Ubuntu export: 7분 54초 PASS
macOS compile: 4분 41초 PASS
unsigned PetAIVerticalSlice.app: 약 127 MB
검증 run: 30113999254

주의

이 검사는 iPhone 서명·설치·실행을 하지 않는다. App Store용 1024×1024 icon 누락 경고도 남아 있다.

Unity iOS export 열기

변경 유형별 필수 게이트

변경 유형	반드시 확인할 것
오탈자·문서·주석	사람 리뷰, 링크 확인
Unity UI 문구만 변경	Unity static validation + 화면 직접 확인
Unity gameplay·관계·보상	Unity static validation + Unity Ubuntu Personal tests
save·schema·recovery	Unity static validation + Unity Ubuntu Personal tests + 재실행 수동 QA
`contracts/**`	Unity static validation + 계약 소비 코드 리뷰
EdgeLLM 순수 Swift 로직	iOS Swift package tests
UnityBridge·LiteRT-LM	iOS Swift package tests + Unity iOS export
CI workflow	관련 자동 검사 + 변경 workflow 수동 실행
release 후보	Unity tests + iOS export/compile + 실제 iPhone QA

PASS가 증명하는 것과 증명하지 않는 것

Unity static validation PASS

증명함: 버전·workflow·JSON contract의 정적 규칙
증명하지 않음: Unity 컴파일, 게임 실행, UI 입력

Unity Ubuntu Personal tests PASS

증명함: Linux Unity에서 C# compile, EditMode, PlayMode
증명하지 않음: iOS export, Xcode compile, iPhone 실행

iOS Swift package tests PASS

증명함: EdgeLLM Swift package의 단위 계약
증명하지 않음: Unity 연결, Gemma 로드, 기기 메모리

Unity iOS export PASS

증명함: Unity가 iOS Xcode project를 만들고 bridge/framework를 포함
증명하지 않음: Xcode compile, 서명, 기기 실행

unsigned Xcode compile PASS

증명함: 생성된 project가 iPhoneOS용 .app으로 링크·컴파일됨
증명하지 않음: 서명·설치·실행, 실제 Swift↔Unity 호출, Gemma 추론

PR 작성 템플릿

## 변경 내용
- 

## 변경 이유
- 

## 자동 검증
- ☐ Unity static validation
- ☐ iOS Swift package tests
- ☐ 해당 없음

## 수동 CI
- ☐ Unity Ubuntu Personal tests
- ☐ Unity iOS export + unsigned Xcode compile
- ☐ 해당 없음

## 직접 확인
- ☐ Unity Editor/Player
- ☐ 390×844 화면
- ☐ 앱 재실행과 persistence
- ☐ 실제 iPhone
- ☐ 해당 없음

## 미검증
- UNVERIFIED: 

## 증거
- Actions run:
- 스크린샷/영상:
- 로그/artifact:

미검증을 비워 두기보다 UNVERIFIED로 명시하는 편이 좋다. CI가 하지 않은 일을 한 것처럼 보이게 만들지 않는다.

실패했을 때 판정 순서

어떤 workflow의 어느 step이 실패했는지 본다.
제품 코드 실패와 CI 인프라 실패를 구분한다.
Unity activation 실패를 게임 테스트 실패로 기록하지 않는다.
XML이나 artifact가 생성되지 않았다면 이전 run을 현재 증거로 재사용하지 않는다.
수정 후 동일 브랜치에서 새 run을 만든다.
PR에 실패 원인과 해결 내용을 한 줄로 남긴다.

예시:

INFRA FAILURE: Unity Personal activation handshake failed.
제품 테스트는 실행되지 않았으며 PASS/FAIL 판정 대상이 아님.

PRODUCT FAILURE: PlayMode 1/12 failed.
VerticalSlice recovery flow의 두 번째 확인 조건을 수정하고 새 run으로 재검증함.

현재 남은 공백

1. 실제 iPhone 검증

현재 확인된 연결 기기는 Mac과 Simulator뿐이다. 다음 항목은 아직 UNVERIFIED다.

signing과 provisioning
실제 iPhone 설치·실행
Unity↔Swift runtime 호출
Gemma 모델 로드
token streaming
메모리·발열·장시간 안정성

2. 백엔드 CI

백엔드 언어·배포 환경·데이터베이스가 확정되지 않아 전용 workflow가 없다. 백엔드 구조가 정해지면 lint, unit test, migration validation, API contract test, container build를 별도 게이트로 추가한다.

3. Codex 리뷰 API 키

workflow는 준비됐지만 키가 없어 review step이 skip된다. 키를 넣기 전까지 사람 리뷰가 필수다.

4. Branch protection

현재 GitHub 플랜에서는 required check와 main 직접 push 차단을 강제하지 못한다. 팀원이 PR 절차를 지키는 운영 규칙으로 보완한다.

5. App Store icon

1024×1024 App Store icon이 없어 iOS compile warning이 발생한다. 배포 전 승인된 아이콘을 넣어야 한다.

현재 운영 상태

열린 PR: 0개
자동 Unity 정적 검사: 운영 중
Unity Personal EditMode·PlayMode: 수동 실행 가능, 검증 완료
Swift package tests: 자동 운영 중, 15/15 PASS
Unity iOS export와 macOS compile: 수동 실행 가능, 검증 완료
Codex 실제 자동 리뷰: API key 미설정으로 비활성
실제 iPhone·Gemma runtime: UNVERIFIED

최근 정리된 PR:

#21 iOS export gate
#22 root-owned output marker 수정
#23 macOS unsigned Xcode compile
#24 compile evidence 문서화
#25 안전한 Codex PR review workflow
#26 EdgeLLM Swift package tests

연결 문서

이 문서는 팀원이 일상적으로 PR을 만들고 검증할 때 사용하는 운영 가이드다. 출시 승인과 전체 QA 기준은 WBS 6.0 QA·CI/CD·릴리즈를 따른다.