08 GitHub Workflow

GitHub 협업 가이드

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

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

Discussion과 Issue 구분

• 답이나 구현 방식이 아직 정해지지 않았으면 Discussion에 씁니다.
• 담당자, 완료 조건, 구현 범위가 정해졌으면 Issue로 만듭니다.
• Discussion에서 결론이 나면 실행 항목을 Issue로 연결하고, 오래 유지할 결정은 Wiki에 반영합니다.
• 질문 글에는 실제 개인정보·토큰·Secret·전체 로그를 첨부하지 않습니다.

시작할 작업 고르기

1. 팀원 전용 Server Roadmap을 엽니다.
2. Area, Priority, Milestone을 확인합니다.
3. Project Status=Todo 중 status:ready label인 Issue를 우선 선택합니다.
4. Issue의 선행 작업과 완료 조건을 읽습니다.
5. 댓글 또는 담당자 지정으로 맡았음을 알립니다.
6. Issue label을 status:in-progress, Project Status를 In Progress로 함께 바꾸고 branch를 만듭니다.

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

2026-07-21 기준 바로 시작할 핵심 작업은 #23 Architecture ADR과 #4 인증·사업장 권한입니다.

라벨 읽는 법

영역

• 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 리뷰 대기

Server Roadmap의 Status는 Todo·In Progress·Done으로 간단히 관리하고, 세부 상태는 Issue의 status:* label을 확인합니다. 닫힌 Issue에는 진행 label을 남기지 않습니다. 통합 Project와 값이 다르면 담당자가 함께 맞춥니다.

Server Roadmap의 추적 단위는 Issue입니다. PR을 별도 item으로 반복 추가하지 않고 Closes #번호 또는 Refs #번호로 Issue에 연결합니다.

작업 유형

• type:epic: 여러 하위 작업을 묶는 목표
• type:feature: 사용자·Agent 기능
• type:integration: 외부 LLM·DB·스토리지 연동
• type:tooling: 테스트·CI·검증 도구
• type:chore: 저장소 설정·유지보수
• type:bug: 재현 가능한 오류 수정
• type:docs: README·Wiki·API 설명 작업

보안

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

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

브랜치

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

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

커밋

Conventional Commits 형식을 사용합니다. 기술 용어와 identifier를 억지로 모두 번역하지 않고 변경의 의도가 전문적으로 드러나게 씁니다.

feat(auth): add company-scoped JWT authentication
fix(link): 만료된 근로자 링크 접근 차단
test(event): restart recovery scenario 추가
docs(wiki): reliable AI execution contract 정리

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

PR 작성

PR 제목은 팀 규칙대로 한국어로 작성합니다. 다만 AI Run, Workflow, JWT, class/API 이름처럼 정확성이 중요한 기술 식별자는 그대로 사용합니다. “전부 한글로 번역”하는 규칙으로 이해하지 않습니다.

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으로 보지 않습니다.

Milestone 기준

• M3/P0: 인증·Workflow·비동기 AI Run·HITL 승인·Worker Link·event 복구·외부 LLM 배포·Golden E2E
• M4/P1: Excel/CSV Import·대시보드·설정·분산 추적/운영 지표

대표 시나리오 선행 작업이 아닌 Import는 M4로 이동했습니다. 데모 범위가 바뀌면 Epic #2에 근거를 적고 Issue label·Milestone·Project Priority를 함께 수정합니다.

처음 참여자 추천 순서

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