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로 표시합니다.

두 명의 업무량

M3의 Raw workload 합계는 105점입니다.

담당자	Issue	합계
@hywznn	#23 5, #4 13, #6 10, #11 13, #24 13, #25 5, #9 3, #27 3	65
@chaeliki	#5 10, #13 9, #7 11, #8 5, #10 5	40

65:40은 raw weight이고 정규화하면 약 61.9%:38.1%입니다. M4 Issue와 Epic에는 점수를 넣지 않습니다. 파트너 계정이 다르면 Assignee와 Project 값을 함께 바꿉니다.

파일 소유권

개발자 A · @hywznn	개발자 B · @chaeliki
auth/**, company/**	worker/**
task/**, workflow/**	document/**, file/**
approval/**, audit/**	workerlink/**
airun/**, reliability/**	aiintegration/**
ADR, Server 배포 파일	Product E2E, 데모 런북

공유 파일인 build.gradle, SecurityConfig, application*.yaml, 공통 오류, Flyway 순서는 개발자 A가 통합합니다. 상대 모듈의 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를 사용합니다. 기술 identifier를 억지로 모두 번역하지 않습니다.

feat(auth): add company-scoped JWT authentication
fix(workflow): 승인 version 불일치 전이 차단
test(event): restart recovery scenario 추가
docs(wiki): align AI Runtime boundary

한국어 규칙은 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. 배포 대상이면 Smoke 결과 기록

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

저장소 보호

#27에서 다음을 추적합니다.

• main 직접 push 제한과 PR 필수
• 최소 1명 승인·CI·conversation 해결 필수
• force push·branch 삭제 금지
• CODEOWNERS와 최소 권한 Team
• Secret scanning·Push protection·Dependabot 검토

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

처음 참여자 추천 순서

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