pre-fetch로 먼저 전체 커밋 해시 기록하고 백업여부 판단하기 모드

README.md

@@ -1,12 +1,16 @@
 # Git Repository Mirroring Workflow
 
 ## 목적
-- 외부 SSH Git 저장소(센터 공용 코드 관리용 깃)의 특정 브랜치를 Gitea `center_dev` 조직의 개별 저장소로 순차 복제합니다.
-- 브랜치마다 대응 저장소명을 결정해 `main` 브랜치로 강제 푸시하며, 태그 동기화 옵션을 제공합니다.
+- 외부 SSH Git 저장소(센터 공용 코드 관리용 깃)의 특정 브랜치를 Gitea `center_dev` 조직으로 순차 복제합니다.
+- 브랜치→저장소 매핑 규칙을 적용해 `main` 브랜치로 강제 푸시하며, 태그 동기화 옵션을 제공합니다.
+- `backup.yml`은 소스/타겟의 head 커밋을 먼저 스캔해 건너뜀/증분/신규 여부를 사전 결정하고, `mirror.yml`은 즉시 복제합니다.
+
+## 워크플로우 파일
+- `.gitea/workflows/backup.yml`: 프리스캔 기반 백업(사전 해시 기록 → 계획 결정 → 실행). 예약 실행: 매일 02:00 KST (`cron: 0 17 * * *`, UTC 기준) + `workflow_dispatch`.
+- `.gitea/workflows/mirror.yml`: 기존 즉시 복제 워크플로우. 스케줄 없음, `workflow_dispatch`로만 수동 실행.
 
 ## 실행 환경
 - Runner 라벨: `internal` (해당 라벨이 있는 셀프호스티드 러너에서만 실행)
-- 예약 실행: 매일 02:07 KST (`cron: 7 17 * * *`, Gitea 스케줄 cron은 UTC 기준)
 - 수동 실행: `workflow_dispatch` 입력을 통해 선택 브랜치만 실행 가능
 
 ## 시크릿/변수
@@ -34,7 +38,16 @@
 - `branches`: 콤마로 구분한 `sourceRepo/branch` 또는 `sourceRepo/branch,alias` 목록
 - 입력이 비어 있으면 `branch_list` 전체를 처리
 
-## 동작 개요
+## backup.yml (프리스캔 백업) 동작 개요
+1) 입력 또는 `branch_list`를 파싱해 유효 항목을 확정하고, 소스 저장소별로 `git ls-remote --heads`를 한 번씩 수행해 브랜치→커밋 해시를 수집합니다.
+2) Gitea에 해당 저장소가 있는지 조회 후 `main` 해시를 확인합니다.
+3) 사전 판정: 타겟이 없거나 `main`이 없으면 “신규 백업”, 해시가 같으면 “건너뜀”, 다르면 “증분 백업”으로 결정합니다.
+4) 해시 스냅샷과 판정 테이블을 `backup_reports/` 폴더에 `source_heads_*.tsv`, `target_heads_*.tsv`, `decisions_*.tsv`로 기록합니다.
+5) “건너뜀”은 바로 알림 후 종료, “신규/증분”만 fetch→push 실행합니다.
+6) 실행 단계: 저장소 존재 확인/생성(`default_branch=main`) → shallow-exclude 기반 fetch(미지원 시 타겟 main 얕은 시드 후 일반 fetch) → `main`으로 강제 푸시 → 태그 동기화(옵션) → 기본 브랜치 `main` 패치 → 임시 폴더 정리.
+7) 알림은 시작/성공/실패/건너뜀에 대해 KST 타임스탬프, 모드, 소요시간을 포함해 전송합니다.
+
+## mirror.yml (즉시 복제) 동작 개요
 1) 브랜치 존재 여부 확인 (`git ls-remote`)
 2) 타겟 저장소 존재 확인/생성 (`default_branch=main`)
 3) 커밋 동일 시 skip (알림 전송)