08 GitHub Workflow

GitHub 협업 가이드

두 명이 병렬 개발할 때 중요한 것은 “누가 더 많이 맡았는가”보다 같은 파일과 같은 책임을 동시에 구현하지 않는 것입니다. Project는 일정과 업무량을 보여주고, Issue는 실제 완료 조건을 설명합니다.

GitHub 기능을 언제 쓰나요?

기능	사용하는 때	예시
Discussion	질문·아이디어·합의 전 설계	AI Runtime contract 선택
Issue	구현할 범위와 완료 조건이 정해짐	JWT 인증 구현
Epic/Sub-issue	여러 작업을 하나의 목표로 묶음	Controlled AI Workflow MVP
Label	검색 가능한 분류	area:server, priority:P0
Milestone	같은 출시 목표와 기한	M3 Backend MVP
Project	Status·담당자·업무량을 한눈에 관리	Server Roadmap
PR	코드·문서 변경을 검토하고 병합	Closes #24
Wiki	오래 유지할 온보딩·설계·운영 설명	저장소 경계, 보안, 배포

Discussion에서 결론이 나면 실행 항목은 Issue로 옮기고, 오래 유지할 결정은 ADR/Wiki에 반영합니다.

Server Roadmap 읽는 순서

1. Server Roadmap을 엽니다.
2. Milestone=M3, Priority=P0인지 확인합니다.
3. Assignees와 Raw workload를 확인합니다.
4. Issue 본문의 “담당 범위”와 “완료 조건”을 읽습니다.
5. native blocked by에서 hard blocker를 확인합니다.
6. 시작할 때 Project Status와 status:* label을 함께 갱신합니다.
7. PR에서 Closes #번호로 연결합니다.

blocked by가 있어도 Fake Port로 독립 구현할 수 있으면 준비 작업은 진행할 수 있습니다. 실제로 더 진행할 수 없을 때만 Blocked로 표시합니다.

현재 역할 분담과 진행 순서

실제 담당자는 GitHub Issue의 Assignee를 기준으로 확인합니다. Raw workload는 대략적인 난이도 참고값이며 담당 비율이나 완료율로 해석하지 않습니다.

담당	작업
@hywznn	#4 Auth·Company, #6 Task Workflow, #11 Approval·Audit, #8 AI Integration, #24 AiRun, #25 Outbox·Reliability
@chaeliki	#5 Worker·Document metadata, #13 Document·File, #7 Worker Link, #15 Dashboard, #16 Settings
공동	#9 Demo deployment, #10 Product E2E, 서로의 PR review

현재 첫 병렬 작업은 @hywznn의 #4와 @chaeliki의 #5입니다. #5는 독립 가능한 domain·API metadata부터 진행하고 Auth·Tenant 통합은 #4 계약이 준비된 뒤 연결합니다. #25는 기반 업무 흐름 뒤에 진행하되 #24 AiRun 통합 전에는 완료합니다. #15·#16은 M4 후순위입니다.

1. Notion API 명세에서 담당 API의 요청값·응답·권한을 확인합니다.
2. GitHub Issue에서 실제 담당 범위·완료 조건·blocked by를 확인합니다.
3. 작업을 시작할 때 Project Status를 Todo → In Progress로 바꾸고 Issue의 status:* label도 맞춥니다.
4. 최신 main에서 Issue 번호가 들어간 branch를 만듭니다.
5. 구현과 test 후 PR을 열고 상대 담당자가 review합니다.
6. 병합되면 Project를 Done으로 바꾸고 Notion 구현 상태를 구현됨으로 갱신합니다.

Swagger UI 기반은 이미 준비되어 있습니다. endpoint별 Swagger/OpenAPI 명세 정리는 이번 주 공통 작성 방식을 확정할 때까지 잠시 보류하고, 이후 진행 중인 API까지 함께 보완합니다.

DB 모델과 migration은 DB 팀의 최신 ERD를 시작 기준으로 삼습니다. 차이가 생기면 임의로 해석하지 않고 Issue/PR에서 합의하며, 이미 적용된 Flyway migration은 수정하지 않습니다.

파일 소유권

@hywznn	@chaeliki	공동
auth/**, company/**	worker/**	Demo deployment
task/**, workflow/**	document/**, file/**	Product E2E·demo runbook
approval/**, audit/**	workerlink/**	서로의 PR review
aiintegration/**, airun/**, reliability/**	dashboard/**, settings/**	공통 설정·OpenAPI/Error 계약

공유 파일인 build.gradle, SecurityConfig, application*.yaml, 공통 오류, Flyway 순서는 수정 전에 상대 담당자에게 알리고 PR에서 함께 검토합니다. 상대 모듈의 Entity·Repository를 직접 참조하기보다 Port와 ID로 연결합니다.

Label 읽는 법

Area

• area:server: Spring Boot API·Domain·DB·tenant·Task Workflow
• area:ai-integration: Server↔AI Runtime contract·Client·검증·trace
• area:infra: Server Dockerfile·DB 설정·CI hook·deployability

Prompt·모델·Provider 코드는 area:ai-integration이 아니라 fowoco/ai의 작업입니다.

Priority

• priority:P0: M3 핵심 흐름을 막는 작업
• priority:P1: M4 또는 핵심 다음 고도화
• priority:P2: 일정에 따라 미룰 수 있는 보완

Status

• status:ready: 바로 시작 가능
• status:backlog: 범위는 있으나 순서 대기
• status:blocked: 실제 선행조건 때문에 진행 불가
• status:in-progress: 구현 중
• status:in-review: PR 리뷰 중

Project는 팀원만 볼 수 있으므로 status label도 유지합니다. 두 값이 다르면 담당자가 같은 작업에서 맞춥니다.

Type과 Security

• type:epic, type:feature, type:integration, type:tooling, type:chore, type:bug, type:docs
• security:privacy: 개인정보·token·권한·Worker Link·AI 입력에 영향

담당자 이름 label은 만들지 않고 GitHub Assignee를 사용합니다.

Branch

docs/23-architecture-adr
feat/4-auth-multitenancy
feat/24-async-ai-run
fix/7-worker-link-expiry

한 branch와 PR은 가능하면 한 Issue를 해결합니다. Issue 번호를 넣으면 추적하기 쉽습니다.

Commit과 PR 언어 규칙

Commit은 Conventional Commits를 사용하고 type(scope)는 기술 표기 그대로, 설명은 한국어로 작성합니다. 기술 identifier를 억지로 번역하지 않습니다.

feat(auth): 사업장 범위 JWT 인증 추가
fix(workflow): 승인 version 불일치 전이 차단
test(event): 재시작 복구 scenario 추가
docs(wiki): AI Runtime 경계 동기화

PR 제목도 한국어로 작성합니다. AI Run, JWT, class/API 이름 같은 정확한 기술명은 그대로 사용할 수 있습니다.

PR 제목 예시:

사업장 범위 JWT 인증과 Refresh Token 회전을 구현한다
AI Run 영속 상태와 재시작 복구를 추가한다

PR 본문 예시:

## 변경 이유

## 변경 내용

## 검증
- [ ] ./gradlew test
- [ ] 권한·사업장 격리 test
- [ ] Swagger/문서 갱신

## 보안·데이터 영향

## 배포·롤백

Closes #24

Review 기준

• Issue 완료 조건과 범위를 충족했나요?
• 저장소 경계와 계약을 침범하지 않나요?
• 정상뿐 아니라 validation·권한·타 사업장·중복·동시성 test가 있나요?
• migration이 기존 DB와 호환되나요?
• API 변경이 OpenAPI와 Client에 반영됐나요?
• AI 결과가 승인·전달을 우회하지 않나요?
• 개인정보·token·Secret·Prompt가 log/event/metric에 없나요?

Done 기준

1. CI 성공
2. 리뷰와 conversation 해결
3. Issue 완료 조건 확인
4. test·migration·OpenAPI·필요 문서 포함
5. PR 병합
6. Issue 종료와 Project Status 확인
7. Notion API 명세의 구현 상태를 구현됨으로 갱신
8. 배포 대상이면 Smoke 결과 기록

코드만 병합됐어도 배포·migration·문서가 완료 조건이면 모두 끝날 때까지 Done이 아닙니다.

저장소 보호

2026-07-23에 #27을 완료하면서 다음 규칙을 실제 저장소 설정에 적용했습니다.

• main은 Pull Request를 통해서만 변경합니다.
• 승인 1명, Test and build 성공, review conversation 해결이 모두 필요합니다.
• main이 최신 상태가 아니면 먼저 갱신해야 하며, 오래된 승인은 새 commit이 추가되면 취소됩니다.
• Admin도 같은 보호 규칙을 따릅니다.
• force push와 main 삭제를 금지하고 linear history를 유지합니다.
• Squash Merge만 허용하고 병합된 작업 branch는 자동 삭제합니다.
• Secret scanning, Push protection, Dependabot security update를 활성화했습니다.

현재 조직 구성원은 조직 설정에서 Admin 권한을 상속받습니다. 특정 구성원의 권한을 이 저장소에서 임의로 낮추면 다른 저장소 협업에도 영향을 줄 수 있어 #27에서는 변경하지 않았습니다. 대신 main 보호를 Admin에게도 강제해 직접 push와 검증 없는 병합을 막습니다. 조직 권한을 바꿀 때는 조직 Owner가 전체 저장소 영향을 확인하고 팀 단위 권한으로 전환합니다.

현재는 두 담당자가 서로의 PR을 직접 review하므로 CODEOWNERS 승인을 필수화하지 않습니다. 파일 소유권 표를 기준으로 reviewer를 지정하며, 인원이 늘거나 누락이 반복될 때 CODEOWNERS를 도입합니다.

GitHub 장애나 잘못된 필수 check 설정 때문에 긴급 복구가 필요하면 저장소 Admin이 보호 규칙을 잠시 수정할 수 있습니다. 이 경우 Issue 또는 Discussion에 변경 이유·담당자·시각을 먼저 남기고, 복구가 끝난 즉시 위 규칙을 다시 적용해 설정 화면과 Audit 기록을 확인합니다.

초보자에게 맡기기 쉬운 것과 보안상 안전한 것은 다릅니다. P0 인증·tenant·token 작업은 작은 vertical slice와 리뷰로 나누되 보호 규칙을 완화하지 않습니다.

처음 참여자 추천 순서

1. 저장소 경계와 계약
2. MVP 로드맵
3. 본인에게 배정된 Issue와 blocker
4. 로컬 개발 가이드
5. 작은 test 또는 문서 변경으로 첫 PR