08 GitHub Workflow

GitHub 협업 가이드

어디서 무엇을 관리하나요?

GitHub 기능	역할	예시
Issue	실제로 구현할 한 작업	JWT 인증 구현
Epic/Sub-issues	여러 Issue를 하나의 목표로 묶음	백엔드 Agent Workflow MVP
Label	검색 가능한 분류	area:server, priority:P0
Milestone	일정과 완료율	M3 · Backend Agent Workflow MVP
Project	팀 전체 우선순위와 상태	FOWOCO · Big Project
PR	코드·문서 변경과 리뷰	Closes #3
Wiki	오래 유지할 설명과 온보딩	아키텍처·보안·배포 가이드

시작할 작업 고르기

1. 통합 Project를 엽니다.
2. 영역 = 서버, 개발 단계 = M3를 확인합니다.
3. 진행 상태 = 준비됨인 Issue를 우선 선택합니다.
4. Issue의 선행 작업과 완료 조건을 읽습니다.
5. 댓글 또는 담당자 지정으로 맡았음을 알립니다.
6. 진행 상태를 진행 중으로 바꾸고 브랜치를 만듭니다.

차단됨 Issue는 구현을 시작하기 전에 차단 원인인 선행 Issue를 확인합니다.

라벨 읽는 법

영역

• area:server: Spring Boot API, 도메인, DB, 인증
• area:ai: AI Adapter, Prompt, 모델 연동
• area:infra: Docker, CI/CD, DB, 배포

우선순위

• priority:P0: MVP를 막는 핵심. 먼저 해결합니다.
• priority:P1: 핵심 다음의 중요 작업입니다.
• priority:P2: 일정에 따라 미룰 수 있는 보완입니다.

상태

• status:ready: 바로 시작 가능
• status:backlog: 작업 확정, 순서·선행조건 대기
• status:blocked: 선행 작업 또는 외부 조건 필요
• status:in-progress: 구현 중
• status:in-review: PR 리뷰 대기

Project의 진행 상태가 팀의 최신 실행 상태이고, Label은 검색과 자동화 보조로 사용합니다. 둘이 다르면 Project 상태를 확인하고 Issue를 정리합니다.

작업 유형

• type:epic: 여러 하위 작업을 묶는 목표
• type:feature: 사용자·Agent 기능
• type:integration: 외부 LLM·DB·스토리지 연동
• type:tooling: 테스트·CI·검증 도구
• type:chore: 저장소 설정·유지보수
• documentation: 문서 작업

보안

• security:privacy: 개인정보·토큰·접근권한에 영향

이 라벨이 있으면 보안 PR 체크리스트를 반드시 검토합니다.

브랜치

feat/3-foundation
feat/4-auth-multitenancy
feat/8-ai-adapter
fix/7-worker-link-expiry
docs/wiki-deployment

브랜치명에 Issue 번호를 포함하면 추적이 쉽습니다.

커밋

권장 형식:

feat(auth): 사업장 범위 JWT 인증 추가
fix(link): 만료된 근로자 링크 접근 차단
test(task): 금지 상태 전이 테스트 추가
docs(wiki): 데모 배포 절차 정리

한 커밋에는 설명 가능한 한 가지 변경을 담습니다. Secret이나 실제 개인정보가 들어간 파일은 커밋하지 않습니다.

PR 작성

PR 본문에 다음을 포함합니다.

## 변경 이유

## 변경 내용

## 검증
- [ ] ./gradlew test
- [ ] 보안·사업장 격리 테스트
- [ ] Swagger/문서 갱신

## 영향과 롤백

Closes #3

Closes #번호는 PR 병합 시 Issue를 자동 종료합니다. 작업 일부만 관련되면 Refs #번호를 사용합니다.

리뷰 기준

모든 PR

• Issue 완료 조건을 충족하는가?
• Controller·Service·Domain 책임이 뒤섞이지 않았는가?
• 테스트가 정상·실패·권한 경로를 포함하는가?
• DB migration이 기존 데이터와 호환되는가?
• API 변경이 Swagger와 Client 계약에 반영됐는가?

보안·AI PR

• company_id 범위가 강제되는가?
• 민감정보가 DTO·로그·AI 요청에 없는가?
• AI 오류가 자동 승인·발송으로 이어지지 않는가?
• Token과 Secret이 저장·출력되지 않는가?
• 승인과 AuditLog를 우회할 경로가 없는가?

완료 처리

1. CI 성공
2. 최소 1명 리뷰 또는 팀의 현재 합의된 승인 절차 통과
3. Issue 완료 조건 확인
4. 필요 문서·Swagger·migration 포함
5. PR 병합
6. Project 상태 완료 확인
7. 배포 대상 변경이면 Smoke Test 결과 기록

코드가 병합됐더라도 배포·migration·문서가 완료 조건에 포함돼 있으면 모두 끝나기 전에는 Done으로 보지 않습니다.

처음 참여자 추천 순서

1. Home
2. MVP 로드맵
3. 작업 Issue의 용어 도움말
4. 로컬 개발 가이드
5. 작은 테스트나 문서 보완부터 PR 경험