Git으로 관리하기 어려운 파일을 자동 전달하기

시작하기

기본 개념

소스 코드와 설정 파일은 Git으로 관리하기 적합하지만, 대용량 빌드 결과물이나 바이너리, 영상과 같은 파일까지 동일한 방식으로 관리하면 저장소 크기가 커지고 Clone, Pull과 같은 작업에 영향을 줄 수 있습니다.

예를 들어 개발 환경에서 생성된 설치 파일과 컨테이너 이미지, 모델 파일 또는 미디어 결과물을 여러 서버와 테스트 환경으로 전달해야 할 수 있습니다.

이러한 파일은 소스 코드와 함께 Git에서 관리하기보다, Git은 코드 변경을 관리하고 대용량 파일은 별도의 파일 전송 흐름으로 전달하도록 역할을 나눌 수 있습니다.

Developer
    │
    ├── Source Code ──────────────▶ Git Repository
    │
    └── Build Artifacts
            │
            ▼
        Transfer Flow
            │
     ┌──────┼────────┐
     ▼      ▼        ▼
   Test   Server   Storage

이렇게 구성하면 코드 변경과 대용량 파일 전달을 분리하면서, 빌드 결과 생성 → 파일 감지 → 대상 환경 전송 → 결과 확인까지 이어지는 별도의 자동화 흐름을 만들 수 있습니다.

파일 구분

자동 전달할 파일은 모든 프로젝트 파일이 아니라 Git으로 관리하지 않는 대용량 결과물을 중심으로 구성할 수 있습니다.

예를 들어 하나의 빌드 작업에서 소스 코드는 Git Repository로 관리하고, 빌드가 완료된 이후 생성되는 결과 파일만 전송 대상으로 지정할 수 있습니다.

project/
│
├── src/
│   └── application source
│
├── config/
│   └── application settings
│
└── build/
    ├── application.zip
    ├── application.bin
    └── media/
        ├── video.mp4
        └── assets.tar

이처럼 파일의 성격에 따라 관리 방식을 나누면 Git Repository에는 실제 변경 관리가 필요한 파일을 유지하고, 대용량 파일은 별도의 전송 경로를 통해 필요한 환경으로 전달할 수 있습니다.

전달 흐름

빌드 결과물은 생성되는 시점에 바로 전달하거나, 빌드와 검증 작업이 완료된 이후 다음 단계로 전송할 수 있습니다.

예를 들어 CI 환경에서 빌드가 완료된 뒤 결과 파일을 테스트 서버로 전달하고, 이후 검증이 완료되면 운영 배포 환경이나 별도 스토리지로 전달하는 흐름을 구성할 수 있습니다.

Code Change
    │
    ▼
Build
    │
    ▼
Artifacts Ready
    │
    ├── Build Failed ──▶ Review
    │
    ▼
Transfer
    │
    ▼
Test Environment
    │
    ▼
Validation
    │
    ├── Approved ─────▶ Next Distribution
    │
    └── Check Needed ─▶ Review Result

이때 파일 전송은 단순히 특정 폴더를 복사하는 작업이 아니라, 이전 작업의 결과와 파일 준비 상태를 기준으로 다음 환경에 필요한 결과물을 연결하는 과정으로 구성할 수 있습니다.

IT 엔지니어

원본 연결

먼저 빌드 결과물이나 바이너리 파일이 생성되는 시스템을 Source로 연결합니다.

Source는 개발 서버, 빌드 서버, CI 환경 또는 대용량 파일을 준비하는 스토리지일 수 있습니다.

전송할 파일이 생성되는 위치를 지정하면 해당 경로를 기준으로 자동 전달할 파일 범위를 구성할 수 있습니다.

Build Server
     │
     ▼
/var/build/output/
     │
     ├── app-v2.4.0.zip
     ├── installer.exe
     └── media-package.tar
              │
              ▼
         Transfer Source

Source 구성에서는 다음 항목을 함께 정할 수 있습니다.

예를 들어 build/output 경로에서 .zip, .tar, .bin 파일만 선택해 전송하고, 빌드 중 생성되는 임시 파일은 제외하도록 구성할 수 있습니다.

실행 조건

대용량 결과 파일은 파일이 생성되었다고 바로 전달하기보다, 빌드 작업이 실제로 완료된 이후 전송하도록 구성할 수 있습니다.

예를 들어 빌드 완료 이벤트 이후 전송하거나, CI 작업의 성공 결과를 기준으로 다음 파일 전송 작업을 실행할 수 있습니다.

Build Started
      │
      ▼
Building Files
      │
      ▼
Build Completed?
   ┌──┴──┐
   │     │
  No    Yes
   │     │
   ▼     ▼
 Review  File Ready
              │
              ▼
          Transfer Run

이렇게 하면 아직 생성 중인 파일이나 빌드가 완료되지 않은 결과물을 대상 환경으로 전달하는 상황을 줄일 수 있습니다.

대상 분기

하나의 빌드 결과물을 여러 환경에서 사용해야 하는 경우 하나의 Source에서 여러 Target으로 전송 경로를 분기할 수 있습니다.

예를 들어 생성된 설치 패키지를 테스트 서버로 전달하면서 동시에 장기 보관을 위한 스토리지에도 저장할 수 있습니다.

                Build Artifacts
                       │
                       ▼
                  Transfer Flow
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       QA Server   Release Server  Archive
          │            │            │
          ▼            ▼            ▼
       Testing     Deployment      Storage

대상 환경은 파일의 활용 목적에 따라 나눌 수 있습니다.

이처럼 하나의 결과물을 여러 위치에서 사용해야 하는 경우에도 파일을 각각 복사하는 대신 하나의 Flow에서 대상별 전달 경로를 구성할 수 있습니다.

버전 관리

빌드 결과물은 동일한 파일 이름을 계속 덮어쓰는 대신 버전이나 빌드 번호를 기준으로 관리할 수 있습니다.

예를 들어 빌드마다 생성되는 파일 이름에 버전을 포함하고, Target에서도 동일한 구조를 유지하도록 구성할 수 있습니다.

Source
/build/releases/
├── app-v2.3.0.zip
├── app-v2.4.0.zip
└── app-v2.5.0.zip
          │
          ▼
Target
/releases/
├── v2.3.0/
├── v2.4.0/
└── v2.5.0/

파일 경로나 이름을 기준으로 전달 범위를 구분하면 특정 버전의 결과물만 별도로 전달할 수도 있습니다.

후속 연결

파일이 대상 환경에 전달된 이후에는 결과물을 사용하는 다음 작업까지 연결할 수 있습니다.

예를 들어 테스트 서버에 빌드 결과물이 도착하면 자동 검증을 시작하고, 검증 결과에 따라 다음 배포 작업을 실행하도록 구성할 수 있습니다.

Build Complete
      │
      ▼
Artifact Transfer
      │
      ▼
Target Ready
      │
      ├──────────────┐
      ▼              ▼
   Validation      Archive
      │
      ▼
  Result Review
      │
 ┌────┴─────┐
 ▼          ▼
Success    Review
 │
 ▼
Next Deployment

후속 작업을 연결하면 파일이 전달된 이후 별도의 담당자가 파일을 확인하고 다음 작업을 시작하는 과정을 줄일 수 있습니다.

예를 들어 다음과 같은 흐름으로 구성할 수 있습니다.

결과 확인

파일 전달 작업이 실행되면 Runs에서 전체 진행 상태와 Source, Target별 처리 결과를 확인합니다.

하나의 빌드 결과물을 여러 대상 환경으로 전달한 경우에도 대상별 실행 결과를 구분해 확인할 수 있습니다.

실행 결과에서는 다음 항목을 확인할 수 있습니다.

특정 Run을 선택하면 파일별 처리 결과를 확인해 어떤 결과물이 어느 대상 환경에 정상적으로 반영되었는지 확인할 수 있습니다.

이를 통해 대용량 파일의 전달 상태를 서버별 스크립트나 개별 로그에서 각각 확인하지 않고 하나의 실행 흐름에서 관리할 수 있습니다.

실패 대응

특정 대상 환경으로 파일이 정상적으로 전달되지 않은 경우에는 Run의 상세 정보를 통해 문제가 발생한 위치와 파일 처리 상태를 확인합니다.

예를 들어 대상 서버의 연결이 중단되었거나 저장 경로에 접근할 수 없는 경우에는 해당 Target의 연결 상태와 경로, 접근 권한을 확인할 수 있습니다.

Transfer Run
      │
      ▼
Result Review
      │
 ┌────┼─────────────┐
 ▼    ▼             ▼
QA ✓  Release ✓   Archive !
                       │
                       ▼
                  View Details
                       │
             ┌─────────┼─────────┐
             ▼         ▼         ▼
         Connection   Path   Permission
             │         │         │
             └─────────┼─────────┘
                       ▼
                     Adjust
                       │
                       ▼
                      Retry
                       │
                       ▼
                   New Run

문제가 해결된 뒤에는 전체 빌드 과정을 다시 수행하는 대신 필요한 파일과 대상 환경을 중심으로 전송 작업을 다시 실행할 수 있습니다.

재실행 후에는 새로운 Run을 통해 대용량 빌드 결과물과 바이너리 파일이 지정된 위치에 정상적으로 반영되었는지 확인합니다.

이 과정을 통해 빌드 결과 준비 → 전송 파일 선택 → 실행 조건 설정 → 대상 환경 분기 → 버전별 전달 → 후속 작업 연결 → 결과 확인 → 실패 대상 대응까지 이어지는 대용량 파일 전달 흐름을 구성할 수 있습니다.

Git은 소스 코드와 변경 이력을 관리하고, 대용량 빌드 결과물과 바이너리, 미디어 파일은 별도의 Flow를 통해 필요한 환경으로 자동 전달하면 코드 관리와 대용량 파일 배포를 분리하면서도 전체 개발·배포 흐름은 자연스럽게 연결할 수 있습니다.

개발자

Git 외부의 대용량 산출물을 버전 경로로 전달하고 참조를 기록하기

빌드 서버와 저장 대상을 장비로 등록한 뒤, 버전 경로로 산출물을 전송하고 종료 상태를 확인합니다. 시작 전에 다음 항목을 준비합니다.

Python·Node.js는 REST를 직접 호출하는 최소 api() 헬퍼와 상태 상수(STATUS_COMPLETE·TERMINAL)를 API 호출 레시피의 것을 재사용합니다. Java·C#은 번들 소스의 InnorixClient(상수 포함)와 Json(C#은 J) 헬퍼를 사용합니다. 장비 식별자와 경로는 실제 값으로 바꿔 넣습니다.

버전 경로로 산출물 전달

산출물을 저장루트/버전 경로로 전송하고, 반환된 전송 정보에서 소비 측이 참조할 경로를 만듭니다. 반환된 참조 정보(device·경로·버전)를 CI 단계에서 Git 메타데이터나 배포 매니페스트에 기록합니다.

import time


def push_artifact(source, source_path, target, store_root, version):
    target_path = f"{store_root.rstrip('/')}/{version}"   # version path
    transfer = api("POST", "/api/transfers/manual", {
        "sourceDevice": source,
        "targetDevice": target,
        "targetPath": target_path,
        "sourcePaths": [source_path],
        "sendAllFolder": True,
        "checkIntegrity": True,
        "transferOptions": {"target-action": "overwrite"},
    })
    detail = wait_transfer(transfer["monitorId"])
    ok = detail.get("status") == STATUS_COMPLETE
    # reference to record in Git (device + path + version)
    return {"ok": ok, "device": target, "path": target_path, "version": version}


def wait_transfer(monitor_id, timeout=14400, interval=5):
    deadline = time.time() + timeout
    while time.time() < deadline:
        detail = api("GET", f"/api/transfers/{monitor_id}") or {}
        if detail.get("status") in TERMINAL:
            return detail
        time.sleep(interval)
    raise TimeoutError(monitor_id)


ref = push_artifact("build-src", "/out/2.14.0", "artifact-store", "/artifacts", "2.14.0")
print("delivered" if ref["ok"] else "needs check", "->", ref["path"])

버전 경로 규칙 산출물을 저장루트/버전 경로로 전달하면 어떤 버전인지 경로로 구분됩니다. Git에는 이 참조(device·경로·버전)만 기록하고 실제 파일은 저장소 밖에 둡니다.

무결성 검증 소스·대상 장비 조합이 무결성 검증을 지원하는 경우 checkIntegrity: true로 원본과 도착 파일의 일치를 확인할 수 있습니다. 객체 스토리지 간 전송처럼 지원되지 않는 조합에서는 사용하지 않습니다(무결성 검증 레시피 참고).

소비 측은 기록된 device ID와 버전 경로를 사용해 해당 산출물을 조회하거나 별도 전송으로 받을 수 있으며, 실패 시 중단 후 재개 레시피의 retry_failed로 실패분만 다시 전송합니다.

구현 결과

이 레시피를 적용하면 다음 흐름으로 Git 외부의 대용량 파일을 전달할 수 있습니다.

빌드 산출물 (build-src) /out/2.14.0
   ↓  버전 경로로 전송(checkIntegrity)  

공유 스토리지 (artifact-store) /artifacts/2.14.0
   ↓  Git에는 참조만 기록  

소비 측이 같은 경로에서 수신

대용량 산출물을 Git 저장소 밖에서 버전 경로로 전달하고, 참조만 커밋에 남겨 저장소를 가볍게 유지하면서 무결성을 검증할 수 있습니다.