Organization GitHub Workflows

MapSee-Lab Organization에서 공통으로 사용하는 GitHub Projects V2 자동화 워크플로우 템플릿입니다.

📁 디렉토리 구조

organization_github/
├── workflows/
│   ├── COMMON-PROJECT-PROJECT-AUTO-ADD-TO-PROJECT.yml       # 이슈/PR 자동 추가
│   ├── COMMON-PROJECT-PROJECT-SYNC-LABEL-TO-PROJECT.yml     # 라벨 → 프로젝트 상태 동기화
│   ├── COMMON-PROJECT-PROJECT-SYNC-PROJECT-TO-LABEL.yml     # 프로젝트 상태 → 라벨 동기화 (수동)
│   └── COMMON-PROJECT-PROJECT-SETUP-TEMPLATE.yml            # 프로젝트 템플릿 자동 생성
├── scripts/
│   └── create-project-template.js                            # 프로젝트 생성 Node.js 스크립트
├── ISSUE_TEMPLATE/
│   └── issue-label.yml                                       # 정리된 라벨 설정
└── README.md                                                 # 이 파일

🚀 사용 방법

1. 새 레포지토리에 적용하기

1. workflows/ 디렉토리의 워크플로우 파일을 레포지토리의 .github/workflows/로 복사

2. 각 워크플로우 파일의 환경변수 수정:

   env:
     PROJECT_URL: https://github.com/orgs/MapSee-Lab/projects/[번호]
     PROJECT_NUMBER: [번호]
     ORG_NAME: MapSee-Lab

3. .github/scripts/ 디렉토리 생성 후 create-project-template.js 복사

4. 라벨 설정 업데이트:

   cp organization_github/ISSUE_TEMPLATE/issue-label.yml .github/ISSUE_TEMPLATE/

2. Organization Secrets 설정

필수: _GITHUB_PAT_TOKEN Secret 생성 및 권한 설정

1. GitHub 프로필 → Settings → Developer settings → Personal access tokens
2. Generate new token (classic)
3. 권한 선택:
   • repo: Full control of private repositories
   • write:org: Read/write org projects
   • project: Full control of projects
4. Organization Settings → Secrets and variables → Actions
5. New organization secret:
   • Name: _GITHUB_PAT_TOKEN
   • Value: [생성한 토큰]
   • Repository access: All repositories

3. 프로젝트 보드 상태 설정

프로젝트 보드의 Status 컬럼 이름을 라벨과 1:1 매핑:

작업 전 → 작업 중 → 확인 대기 → 피드백 → 작업 완료
                                        ↓
                                      취소

🔧 워크플로우 설명

COMMON-PROJECT-PROJECT-AUTO-ADD-TO-PROJECT.yml

• 트리거: 이슈/PR 생성 시 (issues.opened, pull_request.opened)
• 기능: 자동으로 프로젝트 보드에 추가
• 액션: actions/add-to-project@v0.5.0

COMMON-PROJECT-PROJECT-SYNC-LABEL-TO-PROJECT.yml

• 트리거: 이슈 라벨 변경 시 (issues.labeled, issues.unlabeled)
• 기능: 라벨 변경 → 프로젝트 보드 상태 자동 업데이트
• 기술: GitHub GraphQL API

COMMON-PROJECT-PROJECT-SYNC-PROJECT-TO-LABEL.yml

• 트리거: 수동 실행 (workflow_dispatch)
• 기능: 프로젝트 보드 상태 → 이슈 라벨 동기화
• 사용법: Actions 탭에서 "Run workflow" 클릭

COMMON-PROJECT-PROJECT-SETUP-TEMPLATE.yml

• 트리거: 수동 실행 (workflow_dispatch)
• 기능: Organization 프로젝트 자동 생성
• 스크립트: .github/scripts/create-project-template.js

📋 상태 라벨 매핑

라벨	프로젝트 상태	색상	설명
작업 전	작업 전	E3F2FD	작업 시작 전 준비 상태
작업 중	작업 중	74D7CB	작업이 진행 중인 상태
확인 대기	확인 대기	FBC61E	담당자 확인 필요
피드백	피드백	A439D6	수정 필요
작업 완료	작업 완료	0A4ABB	작업 완료
취소	취소	f28b25	작업 취소됨

추가 분류 라벨 (프로젝트 상태와 무관):

• 긴급 (d73a4a): 긴급한 작업
• 문서 (000000): 문서 작업 관련

⚠️ 제약사항

프로젝트 → 라벨 동기화

• ❌ Projects V2는 상태 변경 webhook 미지원
• ✅ 대안: COMMON-PROJECT-PROJECT-SYNC-PROJECT-TO-LABEL.yml 수동 실행
• 💡 향후: GitHub App + webhook 구현 가능

환경변수 수정 필수

각 레포지토리에서 다음 환경변수를 반드시 수정하세요:

• PROJECT_URL: Organization 프로젝트 URL
• PROJECT_NUMBER: 프로젝트 번호 (URL에서 확인)
• ORG_NAME: Organization 이름

🎯 검증 방법

1. 이슈 자동 추가

1. 새 이슈 생성
2. 프로젝트 보드에 자동 추가 확인
3. Actions 탭에서 워크플로우 로그 확인

2. 라벨 → 프로젝트 동기화

1. 이슈 라벨 변경 (예: "작업 중" 추가)
2. 프로젝트 보드 상태 자동 변경 확인
3. Actions 로그에서 GraphQL 성공 확인

3. 프로젝트 → 라벨 동기화

1. Actions 탭에서 "Sync Project Status to Label" 실행
2. 이슈 번호와 상태 입력
3. 이슈 라벨 변경 확인

📚 참고 자료

• GitHub Projects V2 API
• actions/add-to-project
• actions/github-script

🤝 기여

이 템플릿에 대한 개선 사항이나 버그는 MapSy-AI 레포지토리에 이슈로 등록해주세요.

---

Last Updated: 2026-01-19 Maintained by: MapSee-Lab