| tags | ["area/system","type/reference","status/active"] |
| name | github-workflow |
| description | Use when working on GitHub operations in this KEG repo, including git status review, branch setup, commit, push, pull request, issue triage/creation, release/tag creation, and GitHub hygiene. Aligns every GitHub action with the repo's evidence and workspace-sync rules. |
| up | [[.agent/skills/README]] |
GitHub Workflow
이 스킬은 이 프로젝트의 GitHub 운영 전반을 다룬다.
언제 사용하나
- 커밋을 만들거나 푸시할 때
- 새 브랜치를 만들 때
- PR을 열거나 정리할 때
- 이슈를 만들거나 업데이트할 때
- 릴리즈/태그를 만들 때
- GitHub 운영 상태를 점검할 때
반드시 읽을 파일
.agent/AGENTS.md.agent/system/ops/PLAN.md.agent/system/ops/PROGRESS.md.agent/system/contracts/workspace-contract.md.agent/rules/logging.md_MOC/_04_증빙_MOC.md- 필요 시
.agent/skills/workspace-sync/SKILL.md
- issue 운영이면
.agent/skills/github-issue-ops/SKILL.md
- project 보드 운영이면
.agent/skills/github-project-ops/SKILL.md
- release 작업이면
_system/tools/github/release-policy.md
기본 원칙
- GitHub 작업도 증빙의 일부다.
- 의미 있는 GitHub 작업은
04_증빙/01_핵심로그/에 남긴다.
- 사용자 승인 없이 destructive action을 하지 않는다.
commit/push 전에는 secret/privacy preflight를 먼저 통과한다.- release는 기본값이
draft 또는 보류다. 사용자가 명시적으로 원할 때만 final로 간다.
- release는 배포만이 아니라
운영 업데이트 기록으로도 사용한다.
- GitHub 관련 note, changelog, release note 초안도 Obsidian note 규칙에 맞춰 관리한다.
표준 순서
1. Preflight
먼저 아래를 확인한다.
git status --short- 현재 브랜치와 원격
- 변경 범위가 요청과 맞는지
- 증빙 로그 업데이트 필요 여부
bash _system/tools/github/pre-push-safety-check.sh
2. Commit / Push
커밋 전 체크:
- 변경 파일이 요청 범위 안에 있는지 확인
PROGRESS.md 또는 관련 증빙 로그 반영 여부 확인- 테스트/검증 가능하면 최소 1개 이상 수행
- staged diff에 secret, token, credentials, runtime profile이 없는지 확인
- 커밋 메시지는 의도와 범위를 짧게 설명
푸시 전 체크:
- 브랜치명이 목적을 설명하는지 확인
- 원격이 올바른지 확인
- release 준비가 아닌데 main 직푸시는 피한다
pre-push-safety-check.sh 결과를 다시 확인한다
3. Pull Request
2인 협업 브랜치 규칙 (이승보 + 김주용)
main 브랜치는 직접 push 불가 (브랜치 보호 활성화). 모든 변경은 PR을 통해 병합한다.
브랜치 네이밍
river/<작업명> ← 이승보
juyong/<작업명> ← 김주용
예시:
river/배포-railway
river/E2E-검증
juyong/AI-리포트
juyong/데모-스크립트
작업 플로우
git checkout main && git pull
git checkout -b river/배포-railway
git add <파일> && git commit -m "feat: ..."
git push -u origin river/배포-railway
gh pr create --title "feat: ..." --assignee "@me"
gh pr merge --squash
PR 본문 최소 항목
## 변경 내용
-
## 검증
- [ ] 로컬 실행 확인
## 관련 태스크
-
병렬 작업 시 주의
- 같은 파일을 동시에 수정하면 충돌 발생 → 작업 시작 전 Slack/카톡으로 담당 파일 공유
03_제품/app/ 코드는 가능하면 담당 영역을 나눈다 (서버 ↔ UI)
PR 기본값:
- 가능하면
draft로 시작
- 본문에는 목적, 변경 범위, 검증, 남은 리스크를 쓴다
- 증빙이 중요한 변경이면 관련
04_증빙/01_핵심로그/ 파일을 함께 언급한다
4. Issue
이슈 생성/정리 원칙:
- 중복 이슈를 먼저 확인
- 제목은 문제 중심으로 쓴다
- 본문은
배경 / 해야 할 일 / 완료 조건 / 관련 문서 순으로 쓴다
- 전략, 제품, 증빙 중 어디에 속하는지 분명히 한다
- 반복적인 triage, dedupe, 상태 전환은
github-issue-ops를 우선 따른다
추천 템플릿:
## 배경
## 해야 할 일
- [ ]
## 완료 조건
- [ ]
## 관련 문서
-
5. Release / Tag
release 전 체크:
- 무엇을 릴리즈하는지 명확한가
- 제출물 기준으로 재현 가능한 상태인가
- README, 제출 문서, 증빙 링크가 따라오는가
- 사용자 승인 또는 명시적 요청이 있는가
release 판단 기준:
- 구조 개편, 운영 규칙 변경, 도구 체계 확정, 문제정의 동결, MVP 동결, 제출 동결처럼 상태 변화가 분명할 때 release를 만든다.
- 사소한 수정은 release를 만들지 않는다.
- 기존 draft release를 업데이트 기록으로 계속 보강할 수 있다.
release 노트 소스:
05_제출/04_증빙/01_핵심로그/decision-log.md04_증빙/01_핵심로그/evolution-log.md04_증빙/01_핵심로그/ai-usage-stats.md_system/tools/github/release-note-template.md
6. Project Management
- GitHub Project 운영은
github-project-ops를 우선 따른다
PLAN, PROGRESS, _system/dashboard/project-dashboard.base와 충돌이 나지 않게 유지한다- project scope가 필요하면
gh auth refresh -s project 여부를 먼저 점검한다
GitHub 작업과 증빙 연결
아래 작업은 끝난 뒤 증빙 반영을 확인한다.
- commit / push
- PR 생성
- issue 생성 또는 상태 전환
- release / tag 생성
최소 연결 대상:
04_증빙/01_핵심로그/master-evidence-ledger.md- 필요 시
04_증빙/01_핵심로그/decision-log.md
- 필요 시
.agent/system/logs/evidence-gate-log.md
- 필요 시
.agent/skills/obsidian-workspace/SKILL.md 기준으로 MOC/운영 note도 함께 갱신
절대 규칙
- 변경 범위를 모른 채
git add . 하지 않는다.
.env, runtime/, local profile, token file을 추적 상태로 올리지 않는다.- 사용자가 요청하지 않은 release를 만들지 않는다.
- 증빙이 필요한 GitHub 작업을 로그 없이 끝내지 않는다.
- 브랜치/PR/이슈/릴리즈 설명을 빈 상태로 두지 않는다.
결과물
- GitHub 상태가 명확해진다
- commit / push / PR / issue / release가 요청 범위와 일치한다
- 증빙 로그와 GitHub 작업이 서로 연결된다
