Gitea Action을 이용한 Git 저장소 미러링 계획

1. 개요

이 문서는 외부 SSH 프로토콜 기반의 Git 저장소를 Gitea로 미러링하는 Gitea Action 워크플로우의 설계 및 구현 계획을 정의합니다.

소스 저장소의 특정 브랜치들을 각각 별개의 Gitea 저장소로 매핑하고, 주기적으로 (Cron) 소스 저장소의 변경 사항을 가져와 Gitea 저장소에 반영하는 것을 목표로 합니다. 데이터의 크기가 크다는 점을 감안하여 모든 작업은 순차적으로 진행되도록 설계합니다.

2. 주요 요구사항

소스 저장소: engdev@172.16.42.118:dev_Net8.git (SSH 프로토콜)
인증: SSH 비공개 키 (engdev -> Gitea Secret SSH_PRIVATE_KEY로 저장)
대상: Gitea center_dev 조직 (Organization)
작업 트리거: 스케줄링 (Cron) 및 수동 실행 (workflow_dispatch)
처리 방식: branch_list 파일에 명시된 브랜치 목록을 순차적으로 처리
저장소 매핑 규칙:
- Develop_Net8 브랜치 -> base 저장소
- Develop_Net8_* 브랜치 -> * 이름의 저장소 (예: Develop_Net8_box -> box)
제약 조건: 대용량 데이터를 고려하여 병렬 처리를 지양하고 순차적으로 미러링을 수행합니다.

3. Gitea Action 설계

워크플로우는 하나의 Job으로 구성되며, 해당 Job 안에서 스크립트를 통해 브랜치 목록을 순회하며 미러링 작업을 순차적으로 수행합니다.

워크플로우 트리거

on:
  workflow_dispatch: # 수동 실행
  schedule:
    - cron: '0 2 * * *' # 매일 새벽 2시에 실행 (주기는 추후 변경 가능)

필요한 Gitea Secrets

Gitea 저장소의 Settings > Secrets에 다음 정보들을 추가해야 합니다.

SSH_PRIVATE_KEY: 소스 Git 저장소(engdev@172.16.42.118)에 접근하기 위한 SSH 비공개 키.
GITEA_TOKEN: Gitea 저장소를 생성하고 코드를 Push 하기 위한 Gitea 개인용 액세스 토큰. 이 토큰은 center_dev 조직에 저장소를 생성하고 코드를 쓸 수 있는 권한을 가져야 합니다.
GITEA_URL: Gitea 인스턴스의 전체 URL (예: https://gitea.yourdomain.com)

워크플로우 주요 단계 (Steps)

워크플로우 실행 환경 준비:
- actions/checkout@v4를 사용하여 현재 워크플로우가 포함된 저장소의 코드를 체크아웃합니다. (branch_list 파일을 읽기 위함)
SSH 환경 설정:
- Gitea Secret으로 등록된 SSH_PRIVATE_KEY를 runner의 특정 파일(~/.ssh/id_rsa)에 저장합니다.
- 저장된 키 파일의 권한을 600으로 설정하여 SSH 클라이언트가 사용할 수 있도록 합니다.
- ssh-keyscan을 사용하여 소스 Git 서버(172.16.42.118)의 호스트 키를 ~/.ssh/known_hosts에 추가하여, "man-in-the-middle" 공격 경고 없이 SSH 접속이 가능하도록 설정합니다.
미러링 스크립트 실행:
- branch_list 파일을 한 줄씩 읽어 반복문을 실행합니다.
- 저장소 이름 결정: 각 브랜치 이름에 따라 위 "저장소 매핑 규칙"에 맞게 Gitea에 생성될 저장소 이름을 결정합니다.
- Gitea 저장소 확인 및 생성 (API):
  - Gitea API를 사용하여 center_dev 조직 아래에 해당 이름의 저장소가 있는지 확인합니다.
  - 저장소가 없다면 Gitea API를 통해 새로 생성합니다. (GITEA_TOKEN 사용)
- 소스 코드 클론 및 푸시:
  - git clone --mirror를 사용하여 소스 저장소의 모든 레퍼런스를 가져옵니다. (최초 한 번만 실행되거나, 매번 새로 실행할 수 있음. 효율성을 위해 git fetch를 사용하는 방향으로 최적화)
  - 클론된 로컬 저장소에서 현재 처리 중인 브랜치를 Gitea의 대상 저장소로 git push --force 명령어를 사용하여 푸시합니다. 이때 브랜치의 내용을 Gitea 저장소의 main (또는 다른 기본) 브랜치로 덮어쓰게 됩니다.
  - 예시: git push --force https://<user>:${GITEA_TOKEN}@${GITEA_URL}/center_dev/${repo_name}.git refs/remotes/origin/${branch_name}:refs/heads/main
- 임시 파일 정리: 각 브랜치 처리 후 생성된 임시 클론 저장소를 삭제하여 디스크 공간을 관리합니다.

4. 구현 단계

Gitea 저장소에 SSH_PRIVATE_KEY, GITEA_TOKEN, GITEA_URL 시크릿을 추가합니다.
.gitea/workflows/ 디렉터리 아래에 mirror.yml (또는 원하는 이름) 파일을 생성합니다.
위 설계에 따라 워크플로우 YAML 파일의 내용을 작성합니다.
작성된 워크플로우 파일을 Gitea 저장소에 푸시하여 활성화합니다.
Gitea Actions 탭에서 workflow_dispatch를 통해 수동으로 실행하여 정상 동작하는지 테스트합니다.

5. 고려사항

초기 실행 시간: 첫 미러링 시에는 모든 Git 데이터를 가져와야 하므로 상당한 시간이 소요될 수 있습니다.
오류 처리: 특정 브랜치 미러링에 실패하더라도 다음 브랜치 작업은 계속 진행되도록 스크립트를 구성해야 합니다.
Gitea API: Gitea API를 사용하는 부분은 Gitea 버전에 따라 endpoint나 요청 방식이 다를 수 있으므로, 사용 중인 Gitea 버전에 맞는 API 문서를 참고해야 합니다.
보안: GITEA_TOKEN은 저장소 생성 및 쓰기 권한을 가지므로 안전하게 관리되어야 합니다.

5.5 KiB Raw Blame History