CodeSync 설치 및 운영 가이드

Git Bundle 기반 폐쇄망 코드 동기화 도구의 설치부터 운영까지 안내합니다.

1. 개요

CodeSync는 Public Azure DevOps의 소스코드를 폐쇄망 Azure DevOps로 자동 전달하는 도구입니다. Git Bundle 방식을 사용하여 커밋 히스토리, 브랜치, 태그를 완전 보존하며 증분 전송을 지원합니다.

핵심 특징

• Git Bundle: 오프라인 환경에서도 커밋 히스토리 완전 보존
• 증분 전송: 변경분만 bundle 생성 (트래픽 절약)
• 데몬 모드: EXE 하나로 백그라운드 주기적 실행
• 에러 격리: 한 repo 실패 시 나머지 계속 처리
• HTTP 모드: AKS Bundle Server에서 HTTP로 bundle 다운로드 (git 불필요)

대상 Repository (5개)

2. 아키텍처

기본 모드 (Git Fetch)

AKS HTTP 모드

3. 사전 요구사항

Host PC (인터넷 연결 가능한 PC)

VDI (폐쇄망 가상 데스크톱)

4. 설치

4.1 파일 배치

Host PC와 VDI 모두 동일한 파일을 배치합니다:

C:\code-sync\
  codesync.exe              # 실행 파일
  config\
    fetcher.yaml            # Host PC 설정 (Host PC에만)
    pusher.yaml             # VDI 설정 (VDI에만)

1. 다운로드 페이지에서 OS에 맞는 실행 파일을 다운로드
2. C:\code-sync\ 폴더를 생성하고 실행 파일 배치
3. 설정 템플릿을 다운로드하여 config\ 폴더에 복사

5. Fetcher 설정 (Host PC)

5.1 Git 모드 (기본)

fetcher.yaml.example을 config\fetcher.yaml로 복사 후 수정합니다:

# config/fetcher.yaml - Host PC (Git 모드)
shared_folder: D:/code-sync/shared
mirror_folder: D:/code-sync/mirrors
log_folder: D:/code-sync/logs
pat_env_var: AZURE_DEVOPS_PAT

repos:
  - name: aiworker-admin
    url: https://dev.azure.com/AIWORKER/AIWORKER/_git/aiworker-admin
    branches: "*"
  - name: aiworker-workflow
    url: https://dev.azure.com/AIWORKER/AIWORKER/_git/aiworker-workflow
    branches: "*"
  - name: super-agent
    url: https://dev.azure.com/AIWORKER/AIWORKER/_git/super-agent
    branches: "dev"
  - name: mcp-context-forge
    url: https://dev.azure.com/AIWORKER/AIWORKER/_git/mcp-context-forge
    branches: "*"
  - name: aiwoker-knowledge
    url: https://dev.azure.com/AIWORKER/AIWORKER/_git/aiwoker-knowledge
    branches: "*"

max_bundle_age_days: 30

5.2 HTTP 모드 (AKS Bundle Server)

AKS에서 Bundle Server가 운영 중인 경우, Git 없이 HTTP로 bundle을 다운로드할 수 있습니다:

# config/fetcher.yaml - Host PC (HTTP 모드)
source: http
bundle_server: https://codesync.4.230.72.248.nip.io/api
shared_folder: D:/code-sync/shared
log_folder: D:/code-sync/logs

repos:
  - name: aiworker-admin
  - name: aiworker-workflow
  - name: super-agent
  - name: mcp-context-forge
  - name: aiwoker-knowledge

# mirror_folder, pat_env_var 불필요 (AKS가 처리)

6. Pusher 설정 (VDI)

# config/pusher.yaml - VDI
shared_folder: V:/code-sync/shared
mirror_folder: C:/code-sync/mirrors
log_folder: C:/code-sync/logs
pat_env_var: INTERNAL_DEVOPS_PAT

repos:
  - name: aiworker-admin
    remote_url: https://devops.internal/{org}/{project}/_git/aiworker-admin
  - name: aiworker-workflow
    remote_url: https://devops.internal/{org}/{project}/_git/aiworker-workflow
  - name: super-agent
    remote_url: https://devops.internal/{org}/{project}/_git/super-agent
  - name: mcp-context-forge
    remote_url: https://devops.internal/{org}/{project}/_git/mcp-context-forge
  - name: aiwoker-knowledge
    remote_url: https://devops.internal/{org}/{project}/_git/aiwoker-knowledge

max_bundle_age_days: 30

7. PAT (Personal Access Token) 설정

Host PC (Public Azure DevOps)

:: 영구 환경변수 등록
setx AZURE_DEVOPS_PAT "your_public_devops_pat_here"

:: 현재 세션에서 즉시 사용
set AZURE_DEVOPS_PAT=your_public_devops_pat_here

VDI (폐쇄망 Azure DevOps)

:: 영구 환경변수 등록
setx INTERNAL_DEVOPS_PAT "your_internal_devops_pat_here"

8. Fetch 실행 (Host PC)

1회 실행

:: 전체 repo fetch
codesync.exe fetch -c config\fetcher.yaml -v

:: 특정 repo만
codesync.exe fetch -c config\fetcher.yaml --repo super-agent -v

:: Dry-run (실제 git 명령 실행 안 함)
codesync.exe fetch -c config\fetcher.yaml --dry-run

HTTP 모드로 실행

:: AKS Bundle Server에서 HTTP로 bundle 다운로드
codesync.exe fetch -c config\fetcher.yaml --source http -v

:: config에 source: http 설정된 경우
codesync.exe fetch -c config\fetcher.yaml -v

실행 결과 예시

2026-03-06 10:00:00 [INFO ] === Fetch 시작 (5 repos) ===
2026-03-06 10:00:01 [INFO ] [aiworker-admin] 처리 시작
2026-03-06 10:00:15 [INFO ] [aiworker-admin] 완료: incremental (aiworker-admin_20260306_100015.bundle, 0.5 MB)
2026-03-06 10:00:16 [INFO ] [super-agent] 변경사항 없음, 건너뜀
...
2026-03-06 10:01:30 [INFO ] === Fetch 완료 (5/5 성공) ===

Fetch 결과: 4 성공, 0 실패, 1 기타
  [+] aiworker-admin -> incremental (0.5 MB)
  [=] super-agent (no-change)
  ...

9. Push 실행 (VDI)

:: 전체 repo push
codesync.exe push -c config\pusher.yaml -v

:: 특정 repo만
codesync.exe push -c config\pusher.yaml --repo aiworker-admin -v

10. 상태 확인

codesync.exe status -c config\fetcher.yaml

출력 예시

Repo                      마지막 Fetch            Push 여부  번들 타입        오류
-----------------------------------------------------------------------------------------------
aiworker-admin            2026-03-06T10:00:15     X          incremental     -
aiworker-workflow         2026-03-06T10:00:25     O          full            -
super-agent               2026-03-06T09:30:00     O          incremental     -

미 push repo: aiworker-admin

11. 데몬 모드

백그라운드에서 주기적으로 fetch 또는 push를 자동 실행합니다:

:: Host PC: 30분 간격 fetch
codesync.exe run --mode fetch -c config\fetcher.yaml --interval 30

:: VDI: 15분 간격 push
codesync.exe run --mode push -c config\pusher.yaml --interval 15

Push-Watch 모드 (VDI 권장)

공유 디스크를 실시간 감시하여, 새 번들이 감지되면 로컬로 복사한 뒤 자동으로 push합니다:

:: VDI: 공유 디스크 감시 → 로컬 복사 → 자동 push
codesync.exe run --mode push-watch -c config\pusher.yaml ^
  --local-cache C:\code-sync\local-cache --watch-interval 10 -v

12. HTTP 모드 (AKS Bundle Server)

AKS에 배포된 Bundle Server가 주기적으로 Public Azure DevOps를 fetch하고 bundle을 생성합니다. Host PC는 git 없이 HTTP API로 bundle만 다운로드하면 됩니다.

동작 흐름

1. AKS Pod: 30분 간격으로 5개 repo를 git fetch + bundle 생성
2. Host PC: codesync.exe fetch --source http로 manifest 확인 후 새 bundle 다운로드
3. VDI: 기존과 동일하게 shared folder에서 bundle 읽어 push

Bundle Server API

13. 자동 실행 설정 (Windows)

방법 1: Windows 작업 스케줄러

:: 제공된 배치 파일로 자동 등록
scripts\install_fetcher_task.bat   :: Host PC
scripts\install_pusher_task.bat    :: VDI

방법 2: 시작프로그램 등록

위 배치 파일은 시작 폴더에 바로가기도 생성합니다. 로그인 시 자동으로 데몬 모드가 시작됩니다.

방법 3: 데몬 모드 직접 실행

:: cmd 창을 열고 직접 실행
C:\code-sync\codesync.exe run --mode fetch -c C:\code-sync\config\fetcher.yaml --interval 30

14. 문제 해결

Git을 찾을 수 없음

ERROR: Git을 찾을 수 없습니다

해결: Git for Windows를 설치하고 PATH에 등록하거나, GIT_EXECUTABLE 환경변수를 설정합니다:

set GIT_EXECUTABLE=C:\Program Files\Git\cmd\git.exe

PAT 인증 실패

ERROR: fatal: Authentication failed

해결: PAT 환경변수가 올바르게 설정되었는지 확인합니다:

echo %AZURE_DEVOPS_PAT%

PAT의 만료일을 확인하고 필요 시 재발급합니다.

증분 번들 실패

WARNING: 증분 번들 실패, 전체 번들로 재시도

force push 등으로 히스토리가 변경된 경우 발생할 수 있습니다. 자동으로 전체 번들로 폴백하므로 정상 동작합니다.

번들 검증 실패

WARNING: bundle verify 실패, 건너뜀

이전 번들과의 연속성이 깨진 경우입니다. 다음 전체 번들이 생성되면 자동 해결됩니다.

HTTP 모드 연결 실패

ERROR: Bundle Server 연결 실패: https://codesync.4.230.72.248.nip.io/api

해결: AKS Bundle Server가 정상 동작 중인지 확인합니다:

curl https://codesync.4.230.72.248.nip.io/api/health

15. FAQ

Q: 최초 동기화 시간이 오래 걸리나요?

첫 fetch는 전체 히스토리를 clone하므로 repo 크기에 따라 수분~수십분 소요됩니다. 이후는 증분 bundle만 생성하므로 빠릅니다.

Q: 동시에 같은 repo를 fetch/push할 수 있나요?

manifest.json에 파일 잠금이 적용되어 있어 동시 실행 시 충돌을 방지합니다. 다만 같은 repo를 동시에 처리하는 것은 권장하지 않습니다.

Q: bundle 파일은 자동 삭제되나요?

네, max_bundle_age_days (기본 30일) 설정에 따라 오래된 bundle은 fetch 시 자동 삭제됩니다.

Q: HTTP 모드와 Git 모드를 혼용할 수 있나요?

가능합니다. 설정 파일의 source 필드로 모드를 선택하거나, CLI에서 --source http 플래그를 사용하여 오버라이드할 수 있습니다.

Q: VDI에서 bundle 파일이 보이지 않습니다

공유 폴더 마운트를 확인하세요. pusher.yaml의 shared_folder가 마운트된 드라이브 경로와 일치해야 합니다.