backup_actions/to-do.md

Git Mirroring Workflow 개선 작업 목록

• backup.yml: 브랜치 백업 스텝에서 오류 발생 시 exit 1로 종료하던 것을 제거하고 안내 메시지 출력으로 변경 (최종 실패 처리는 마지막 스텝에 위임)
• mirror.yml: 작업 시간 초과(timeout) 설정 추가
• mirror.yml: 수동 실행 시 특정 브랜치를 지정할 수 있는 입력(input) 기능 추가
• mirror.yml: Gitea 관련 시크릿 및 변수 이름을 BASE_GITEA_ 접두사로 변경 (secrets.BASE_GITEA_TOKEN, vars.BASE_GITEA_URL, vars.BASE_GITEA_USER)
• mirror.yml: 스크립트 로직을 수정하여 수동 입력된 브랜치를 처리하거나, 입력이 없을 경우 branch_list 파일을 사용하도록 변경
• mirror.yml: 대상 저장소가 이미 있으면 재생성 대신 pull/fetch 후 업데이트만 수행하도록 변경
• mirror.yml: 브랜치명이 Develop_Net8로 시작하지 않으면 브랜치명을 그대로 저장소 이름으로 사용하도록 로직 추가
• to-do.md: 모든 작업 완료 후 KST 시간 기준으로 완료 시간 기록
• 문서: AGENTS.md 생성 및 최신 요구사항(기존 저장소 업데이트, 비-Develop_Net8 브랜치 저장소명 규칙) 반영
• backup.yml: 프리스캔 기반 백업 워크플로우 신규 작성(소스/타겟 head 해시 기록 → 판정 테이블 생성 → skip/증분/신규 분기 실행), 알림에 heads 정보 포함
• backup.yml: 스케줄을 매일 02:00 KST(UTC 17:00)로 설정, mirror.yml은 수동 실행만 유지
• 문서: README에 backup.yml 흐름/스케줄과 보고서 경로를 추가하고 mirror.yml을 수동 전용으로 명시
• backup.yml: TARGET_SEED_DEPTH를 검증해 0/음수/비숫자 입력 시 50으로 보정, fallback depth 오류 메시지 최소화
• backup.yml/mirror.yml: 소스 호스트를 172.16.10.191로 교체하고 실행 전 미러 서버 홈 내 모든 .git에 대해 git fetch --mirror --prune 수행
• backup.yml: 소스별 로컬 캐시(mirror 클론)를 제거하고 미러 서버를 직접 원격으로 사용하도록 단순화

---

Trouble shooting 기록

• 2025-12-19: 미러 서버 사전 fetch에서 git fetch --mirror 옵션 미지원으로 실패 → git fetch --prune --prune-tags origin "+refs/*:refs/*"로 교체.
• 2025-12-19: .cache_sources/<repo>.git.git 이중 확장자 및 중복 클론 문제 → 캐시 경로 접미사 제거 후 최종적으로 캐시 로직 자체 제거, 미러 서버 원격을 직접 사용하도록 변경.
• 2025-12-19: backup.yml에 중복된 Step 1 코드 블록으로 continue/fi 구문 오류 발생 → 중복 블록 제거하고 단일 ls-remote 결과만 사용.
• 2025-12-19: 보고서 생성 스텝이 로그 부재로 실패 → 보고서 생성 스텝을 분리하고 로그가 없을 때도 기본 테이블을 출력하도록 방어 로직 추가.
• 2025-12-19: TSV 제거 후 남은 TARGET_HEADS_FILE 참조로 unbound variable 오류 발생 → 잔여 echo를 제거해 변수 미정의 오류 해결.
• 2025-12-19: 소스 서버가 shallow-exclude를 지원하지 않는 환경에서 반복 오류 발생 → USE_SHALLOW_EXCLUDE 변수로 기능을 끌 수 있도록 토글 추가하고 기본값은 켜둔 상태 유지.
• 2025-12-19: shallow-exclude 에러(ambiguous deepen-not) 대응을 위해 워크플로우에 GIT_PROTOCOL=version=2를 설정해 프로토콜 v2를 강제, 서버에서는 git 2.43.0 확인.

2025-12-16 09:04:36 KST 업데이트: mirror.yml에서 대상 저장소를 git clone --mirror 대신 --bare로 받도록 변경하여 fatal: --mirror can't be combined with refspecs 오류를 제거. 기존 저장소가 있을 때는 Gitea 원격을 bare 클론 후 source 리모트를 원본 SSH에 추가하고 브랜치만 fetch → origin의 main으로 강제 푸시하도록 정리. 새 저장소일 때는 원본을 bare 클론해 origin을 source로 rename 후 Gitea를 origin으로 추가, 같은 fetch→push 동작 수행. 작업 루트 경로를 ROOT_DIR에 저장해 fetch/push 실패 시에도 항상 원위치로 돌아가며 임시 디렉터리를 정리하도록 수정. 2025-12-16 09:42:00 KST 업데이트: mirror.yml에 NOTIFY_WEBHOOK 기반 상태 알림(start/success/error, 소요시간 포함) 추가 및 heredoc 제거로 문법 오류 수정. 브랜치명 매핑을 확장해 Develop_Net8_* 접두사는 제거, Develop_/develop_ 접두사는 제거하여 develop_boxzainer → boxzainer로 푸시되도록 수정하고, 접두사 없는 develop 등은 그대로 사용. 2025-12-16 09:42:00 KST 추가 업데이트: mirror.yml에서 타겟이 존재할 때 git ls-remote로 main 커밋을 조회하고 소스 브랜치 커밋과 동일하면 클론/푸시를 건너뛰도록 최적화. 알림에 skip 상태를 추가해 동일 커밋 시 건너뛰는 로그를 남기도록 개선. 2025-12-16 09:46:30 KST 추가 업데이트: mirror.yml에서 기존 타겟 클론을 없애고 임시 bare repo를 직접 init 후 source 브랜치만 fetch(--no-tags)하여 푸시하도록 변경, 불필요한 대상 전체 클론을 제거해 데이터 전송 최소화. 2025-12-16 09:48:20 KST 추가 업데이트: mirror.yml에서 타겟이 새로 생성된 경우 소스 브랜치를 git clone --bare --single-branch로 전체 클론 후 push, 기존 타겟이 있을 때만 빈 bare repo를 init해 필요한 브랜치만 fetch→push 하도록 분기. 생성된 경우에도 백업 모드/알림이 “신규 전체 백업”으로 정확히 표시되도록 just_created 플래그를 추가. 2025-12-16 11:10:39 KST 추가 업데이트: 증분 경로에서 빈 bare init 후 타겟 main을 fetch --no-tags로 선반입해 객체를 시드한 뒤 소스 브랜치 fetch를 수행하도록 변경, 델타 전송을 활용해 변경량이 적을 때 트래픽을 줄이도록 개선. 2025-12-16 13:28:01 KST 추가 업데이트: mirror.yml에 branch_list 주석(#) 스킵 및 sourceRepo/branch,alias 구문을 추가해, 콤마 뒤의 별도 저장소 이름(alias)으로 타겟을 지정할 수 있도록 개선. 2025-12-16 14:03:18 KST 추가 업데이트: mirror.yml에 태그 동기화 옵션(SYNC_TAGS, 기본 true) 추가. 소스 태그를 fetch --prune/--prune-tags 후 타겟으로 push --force --prune해 태그를 미러링하도록 개선하며, 태그 동기화 실패 시 알림을 보냄. 2025-12-16 16:16:39 KST 추가 업데이트: README.md 작성(목적/사용법/입력 규칙/시크릿/러너 조건/태그 옵션 등). mirror.yml의 cron을 매일 02:07 KST로 조정하고 runs-on 라벨을 internal로 제한. 2025-12-16 17:59:05 KST 추가 업데이트: mirror.yml에 runner_label 입력 및 RUNNER_LABEL 변수 기반 실행러너 선택 로직 추가(없으면 ubuntu-latest 사용), README에 러너 지정 방법 반영. 2025-12-16 18:10:22 KST 추가 업데이트: runner 설정을 다시 runs-on: [internal]로 고정한 상태에 맞춰 README 실행 환경 설명을 internal 러너 기준으로 롤백 정리. 2025-12-16 18:16:34 KST 추가 업데이트: 증분 성능 검토를 위해 타겟 main 선-fetch를 켜고 끄기 위한 SEED_FROM_TARGET 옵션(기본 false) 추가. README에 옵션 설명 반영. 2025-12-16 18:20:26 KST 추가 업데이트: 증분 fetch 시 타겟 main 커밋을 shallow-exclude로 지정해 필요한 부분만 받아오도록 변경, README 동작 개요에 반영. 2025-12-16 18:29:58 KST 추가 업데이트: SEED_FROM_TARGET 옵션과 타겟 main 선-fetch 시드를 제거하고 shallow-exclude 기반 증분 fetch만 유지하여 증분 로직을 단순화. 2025-12-17 08:27:54 KST 추가 업데이트: 스케줄 cron을 UTC 기준임을 명시하고 02:07 KST 실행을 위해 7 17 * * *로 설정, 동기화 결과 요약(총/성공/건너뜀/오류) 메시지를 마지막에 출력하고 알림 웹훅으로 전송하도록 추가. 2025-12-17 08:35:58 KST 추가 업데이트: 소스 서버가 --shallow-exclude를 지원하지 않을 때 타겟 main을 depth=50으로 시드한 후 일반 fetch로 재시도하도록 폴백을 추가, README 동작 개요 반영. 2025-12-17 08:48:00 KST 추가 업데이트: 동일 커밋 건너뛰기 시 모드를 “변경 없음”으로 분리하고 shallow-exclude 실패 시 fetch 로그 tail을 실행 로그에 남기며 폴백 모드를 표시하도록 개선. 2025-12-17 09:38:49 KST 추가 업데이트: Gitea API 오류가 발생해도 전체 작업이 중단되지 않도록 exit 대신 return 처리하여 다음 브랜치로 계속 진행하도록 수정. 2025-12-17 09:50:00 KST 추가 업데이트: Gitea API(조회/생성/기본 브랜치 설정)에 최대 3회 재시도(5초 대기)를 추가해 일시 오류 발생 시에도 작업이 이어지도록 개선, README 반영. 2025-12-18 08:55:36 KST 추가 업데이트: 최근 크론 실행에서 푸시 성공 후 set -e가 미처리된 curl 실패에 반응해 Step이 실패한 사례 대응. Gitea API curl 호출이 실패해도 000 코드로 재시도하도록 가드했고, 전체 처리 후 TOTAL_ERROR>0이면 명시적으로 exit 1, 아니면 0으로 종료하도록 종료 코드를 고정해 불필요한 실패를 방지함. 2025-12-19 14:09:09 KST 추가 업데이트: backup.yml을 프리스캔 기반으로 신규 작성하여 소스/타겟 head 해시 스냅샷과 판정 테이블을 TSV로 기록하고 heads 정보를 포함한 알림을 전송하도록 구성. backup.yml 스케줄을 02:00 KST로 설정하고 mirror.yml은 수동 실행 전용으로 유지. README에 신규 워크플로우와 보고서 경로를 반영. 2025-12-19 14:23:07 KST 추가 업데이트: backup.yml에서 TARGET_SEED_DEPTH가 0/음수/비숫자일 때 50으로 자동 보정해 depth 0 fetch 오류와 반복 경고를 방지. 2025-12-24 09:44:54 KST 추가 업데이트: backup.yml에서 실패 브랜치명을 ERROR_BRANCHES에 수집해 요약/노티스에 표시하고, REPORT_DIR 기본 생성 및 GITHUB_WORKSPACE 부재 시 현재 작업 디렉터리를 사용해 보고서 스텝 실패를 방지. 2025-12-24 10:13:22 KST 추가 업데이트: single_branch_backup.yml에도 오류 브랜치 수집/요약 노출 로직을 맞추고 노티스에 목록을 남기도록 정렬.