backup_actions/README.md

Git Repository Mirroring Workflow

목적

• 외부 SSH Git 저장소(센터 공용 코드 관리용 깃, engdev@172.16.10.191)의 특정 브랜치를 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 (해당 라벨이 있는 셀프호스티드 러너에서만 실행)
• 수동 실행: workflow_dispatch 입력을 통해 선택 브랜치만 실행 가능

시크릿/변수

• secrets.SSH_PRIVATE_KEY: 소스 저장소 접근용 SSH 키
• secrets.BASE_GITEA_TOKEN: Gitea API/푸시 토큰
• vars.BASE_GITEA_URL: Gitea URL (예: https://gitea.example.com)
• vars.BASE_GITEA_USER: 토큰 소유자 ID
• vars.NOTIFY_WEBHOOK (선택): 채팅 웹훅 URL. 없으면 알림 미전송.
• vars.SYNC_TAGS (선택): "false"로 설정 시 태그 동기화 비활성화. 미설정 시 태그를 동기화함.

저장소 이름 매핑 규칙

• Develop_Net8 → base
• Develop_Net8_* → * 부분만 사용 (예: Develop_Net8_heh → heh)
• Develop_* / develop_* → 접두사 제거 (예: develop_boxzainer → boxzainer)
• 그 외 브랜치는 브랜치명을 그대로 사용
• sourceRepo/branch,alias 형태를 사용하면 alias로 최종 저장소명을 강제 설정
• 동일 이름 타겟이 이미 존재하면 소스가 달라도 덮어쓰기 가능하므로 목록 구성 시 주의

branch_list 사용법

• 기본 실행 시 branch_list 파일을 위에서 아래로 순차 처리
• #로 시작하거나 줄 내 # 이후는 주석으로 무시
• sourceRepo/branch 또는 sourceRepo/branch,alias 형식을 한 줄에 하나씩 기입

수동 실행 입력

• branches: 콤마로 구분한 sourceRepo/branch 또는 sourceRepo/branch,alias 목록
• 입력이 비어 있으면 branch_list 전체를 처리

backup.yml (프리스캔 백업) 동작 개요

1. 입력 또는 branch_list를 파싱해 유효 항목을 확정하고, 사전 단계에서 미러 서버(engdev@172.16.10.191) 홈 내 .git 디렉터리마다 git fetch --mirror --prune로 최신 상태로 맞춥니다.
2. 소스별 로컬 캐시(워크플로우 내 생성/갱신)를 이용해 브랜치 해시를 수집하고 필요한 브랜치만 fetch하므로 동일 커밋 다중 브랜치에서도 중복 전송을 줄입니다. 캐시가 없으면 원본을 직접 조회합니다.
3. Gitea에 해당 저장소가 있는지 조회 후 main 해시를 확인합니다.
4. 사전 판정: 타겟이 없거나 main이 없으면 “신규 백업”, 해시가 같으면 “건너뜀”, 다르면 “증분 백업”으로 결정합니다.
5. 판정/타이밍 정보를 로그 파일(decisions/timings)로 남기고, 이후 스텝에서 report_<ts>.md로 전체 테이블을 생성합니다.
6. “건너뜀”은 바로 알림 후 종료, “신규/증분”만 fetch→push 실행합니다.
7. 실행 단계: 저장소 존재 확인/생성(default_branch=main) → shallow-exclude 기반 fetch(미지원 시 타겟 main 얕은 시드 후 일반 fetch) → main으로 강제 푸시 → 태그 동기화(옵션) → 기본 브랜치 main 패치 → 임시 폴더 정리.
8. 알림은 시작/성공/실패/건너뜀에 대해 KST 타임스탬프, 모드, 소요시간을 포함해 전송합니다.
9. 실행 후 backup_reports/ 전체를 backup_reports_<run_id> 이름으로 artifact 업로드합니다. report_*.md 하나에 Decisions/Timings 전체 테이블이 포함됩니다.

mirror.yml (즉시 복제) 동작 개요

1. 브랜치 존재 여부 확인 (git ls-remote)
2. 타겟 저장소 존재 확인/생성 (default_branch=main)
3. 커밋 동일 시 skip (알림 전송)
4. 신규 생성: 소스 브랜치를 bare single-branch clone 후 main으로 강제 푸시
5. 기존 존재: 빈 bare 저장소 init → 타겟 main 커밋을 shallow-exclude로 지정해 소스 브랜치만 fetch → main으로 강제 푸시
6. 태그 동기화가 켜져 있으면 태그 fetch/push(강제+prune)
7. 기본 브랜치를 main으로 패치, 임시 디렉터리 정리
8. 소스 서버가 --shallow-exclude를 지원하지 않으면 타겟 main을 얕게(depth=50) 받아 시드한 뒤 일반 fetch로 재시도
9. Gitea API(조회/생성/기본브랜치 설정)는 최대 3회 재시도 후 실패 시 해당 브랜치를 건너뛰고 다음 브랜치로 진행

알림

• NOTIFY_WEBHOOK 설정 시 시작/성공/실패/건너뛰기 상태를 KST 타임스탬프와 소요시간, 모드(신규/증분)와 함께 전송

주의사항

• 대용량 데이터로 인해 순차 실행을 전제로 함(병렬 실행 비권장)
• 태그 푸시는 --force --prune로 수행되어 소스에 없는 태그가 타겟에서 제거됨
• 동일 저장소명을 의도하지 않은 소스 조합으로 사용할 경우 덮어쓰기가 발생할 수 있으므로 branch_list/alias를 신중히 관리