500개 이상의 GitHub 마이그레이션에서 얻은 교훈

Source: Dev.to

위에 제공된 링크에 있는 전체 글을 번역하려면, 해당 글의 텍스트를 제공해 주시겠어요?
링크만으로는 실제 내용에 접근할 수 없으니, 번역이 필요한 본문을 복사해서 알려주시면 한국어로 정확히 번역해 드리겠습니다.

Introduction

Azure DevOps, BitBucket, SVN 및 기타 시스템에서 GitHub로 500+ repositories를 마이그레이션한 후, 상상할 수 있는 모든 마이그레이션 문제에 직면했습니다. 우리는 이러한 문제를 해결하기 위해 자동화된 프레임워크를 구축하고 오픈‑소스화하여 엔터프라이즈 GitHub 마이그레이션을 진행하는 다른 사람들도 우리의 학습을 활용할 수 있도록 했습니다.

이 포스트에서는 우리가 마주한 도전 과제, 해결 방법, 그리고 GitHub Copilot이 skills‑based configuration을 통해 프레임워크를 유지 보수 가능하게 만든 방법을 공유합니다.

LFS 없이 큰 파일

문제: 저장소에 LFS로 추적되지 않는 큰 파일(> 100 MB)이 포함되어 있습니다. GitHub가 푸시를 거부하여 전체 마이그레이션이 차단됩니다.

해결책:

1. 푸시 전에 큰 파일을 감지합니다.
2. 해당 파일에 대해 Git LFS 추적을 자동으로 설정합니다.
3. 기존 파일을 LFS 저장소로 변환합니다.

브랜치 명명 혼란

Problem: 다양한 시스템이 main, master, 혹은 trunk를 사용합니다. 파이프라인이 깨지고, 보호된 브랜치가 실패합니다.

Solution: 소스 저장소의 기본 브랜치를 감지하고, main이나 master를 가정하는 대신 마이그레이션 중에 그것을 유지합니다.

잃어버린 기록 및 메타데이터

문제: 커밋 작성자가 “migration‑bot”으로 바뀌고, 타임스탬프가 사라지며, 브랜치가 평평해진다.

해결책: git clone (마이그레이션 API가 아니라) 를 사용하여 원본 작성자, 타임스탬프, 모든 브랜치, 태그 및 병합 토폴로지를 포함한 전체 기록을 보존한다.

비밀 스캔 장애물

문제: 과거에 남은 비밀이 전체 마이그레이션을 차단하고, 수시간의 수동 복구가 필요합니다.

해결책:

• 마이그레이션 중에 일시적으로 시크릿 스캔 푸시 보호를 비활성화합니다.
• 즉시 다시 활성화합니다.

이를 통해 팀은 마이그레이션 후에 비밀을 복구할 수 있어 프로세스를 차단하지 않습니다.

개선 여지: 현재 접근 방식은 마이그레이션 후에 팀이 노출된 비밀을 모두 폐기하는 데 의존하고 있으며, 이는 우리 규모에서는 효과적이었습니다. 더 나은 해결책은 프리 커밋 스캔을 사용해 비밀을 감지하고 마스킹한 뒤, 결과를 안전한 위치에 내보내어 이슈를 제기한 사람이 처리하도록 하는 것이지만, 우리 요구에선 마이그레이션 후 폐기가 더 실용적이라는 결론에 이르렀습니다.

SVN to Git 변환

문제: SVN의 trunk/branches/tags 구조가 Git ref와 깔끔하게 매핑되지 않는다.

해결책: 자동 레이아웃 감지를 지원하는 git‑svn을 사용하여 trunk/branches/tags 구조를 Git 관례에 맞게 변환한다.

권한 혼란

문제: 팀이 접근 권한을 잃고, 잘못된 권한이 할당되며, 가시성이 잘못 구성됩니다.

해결책:

1. 계층형 팀(parent/owner/admin)을 자동으로 생성합니다.
2. 마이그레이션을 허용하기 전에 요청자의 팀 멤버십을 검증합니다.
3. 리포지토리 가시성을 중요도 수준에 따라 설정합니다.

모노레포 분해

문제: 모노레포에서 하나의 폴더를 추출하면 히스토리가 손실되거나 수동으로 git‑filter‑repo 수술이 필요합니다.

해결책: git 필터링을 사용하여 특정 경로를 마이그레이션하면서 관련 커밋 히스토리를 보존하는 only‑folder 매개변수를 추가합니다.

통합 중단

Problem: CI/CD 파이프라인, Azure Boards, 웹훅—모두 이전 저장소를 가리키고 있습니다.

Solution (Azure DevOps migrations):

• 자동으로 파이프라인 재배선하여 GitHub을 가리키게 합니다.
• 보드 통합을 구성합니다.
• 소스 저장소를 읽기 전용으로 잠급니다.

프레임워크 개요

우리는 GitHub Actions와 PowerShell을 사용하여 다음과 같은 간단한 워크플로우로 프레임워크를 구축했습니다:

1. 마이그레이션 매개변수(조직, 팀, 저장소 이름, 소스 URL)를 포함한 GitHub 이슈를 생성합니다.
2. 워크플로우가 팀 멤버십 및 네이밍 규칙을 검증합니다.
3. 저장소를 생성하고 전체 히스토리를 포함하여 코드를 마이그레이션합니다.
4. 팀 계층 구조와 권한을 설정합니다.
5. 파이프라인 및 통합(Azure DevOps 소스)의 연결을 재구성합니다.
6. 성공 또는 실패 세부 정보를 포함한 댓글을 이슈에 남깁니다.

우리가 배운 점

엔터프라이즈 프레임워크에서 요구사항이 변함에 따라 유지보수성을 유지하는 것이 하나의 과제입니다. 우리는 GitHub Copilot을 사용해 이를 해결합니다.

스킬 디렉터리

우리는 일반적인 커스터마이징 작업을 위한 지침을 담은 .github/skills/를 만들었습니다. 예시:

Use the update-app-name skill to update all references with:
App Name: repo-migrate
App ID: 123456789

Copilot은 전체 레포를 스캔하여 여러 파일에 걸친 참조를 업데이트할 수 있습니다.

사용 가능한 스킬

Copilot이 도운 방법

• 새로운 소스‑시스템 지원(BitBucket, SVN)을 훨씬 빠르게 추가했습니다.
• 복잡한 PowerShell 함수들을 적절한 오류 처리와 함께 리팩터링했습니다.
• 워크플로 파일에서 트러블슈팅 문서를 자동 생성했습니다.
• 코드베이스에 대한 질문에 답변함으로써 새로운 기여자를 온보딩했습니다.

이 접근 방식은 다른 사람들이 자신의 특정 요구에 맞게 프레임워크를 보다 쉽게 커스터마이즈할 수 있게 합니다.

알려진 제한 사항 및 향후 작업

우리는 솔직합니다—이 프레임워크는 완벽하지 않습니다. 다음은 우리가 더 개선될 수 있다고 생각하는 영역입니다:

1. Secret Handling – 현재 우리는 비밀 스캔을 일시적으로 비활성화하고 마이그레이션 후 팀이 폐기를 처리하도록 합니다. 보다 정교한 접근 방식은 사전 비밀 탐지, 히스토리에서 비밀 마스킹, 마이그레이션이 완료되기 전에 복구를 위한 안전한 보고서를 제공하는 것을 포함합니다.
2. Pre‑Migration Validation – 저장소 상태 검사(예: LFS 파일, 대용량 바이너리, 잘못된 브랜치 이름 감지)를 추가하고 사전에 보고합니다.
3. Post‑Migration Verification – 소스와 마이그레이션된 저장소를 자동으로 비교(커밋 수, 파일 체크섬, 브랜치 구조)하여 우리가 놓칠 수 있는 엣지 케이스를 포착합니다.

이 영역에서 개선을 구현한다면, 여러분의 접근 방식을 보고 싶습니다!

시작하기

프레임워크는 오픈 소스이며 계속 발전하고 있습니다. 엔터프라이즈 GitHub 마이그레이션을 진행 중이라면 한 번 시도해 보세요:

• 저장소: (link to repo)
• 저장소 템플릿을 사용하여 자체 인스턴스를 만드세요.
• GitHub App 인증을 구성하세요 (README 참조).
• 소스 시스템(ADO, BitBucket 등)을 위한 시크릿을 설정하세요.
• 마이그레이션 요청 템플릿을 사용하여 이슈를 생성하세요.

대규모 마이그레이션을 위한 도전 과제 및 팁

모든 조직의 요구 사항은 다르지만, 다음 가이드는 일반적인 함정을 피하는 데 도움이 될 수 있습니다.

기여 및 도움 받기

• 버그를 발견했나요? – 이슈 열기
• 기능 요청이 있나요? – 이슈를 열어 알려 주세요.
• 새로운 소스 시스템 지원을 추가했나요? – PR을 제출하세요.
• 조직에 맞게 커스터마이징했나요? – 성공 사례를 공유해 주세요.

.github/skills/에 있는 Copilot skills는 커스터마이징을 더 쉽게 해 줍니다—새 소스 시스템, 사용자 정의 속성, 또는 검증 규칙을 필요에 따라 설명만 하면 추가할 수 있습니다.

마이그레이션 모범 사례

• 파일럿 레포로 충분히 테스트 – 대규모 마이그레이션은 복잡성을 숨기기 쉽습니다; 작은 파일럿을 통해 숨겨진 문제를 조기에 발견할 수 있습니다.
• 가능한 한 자동화 – 수동 마이그레이션은 규모를 키우기 어렵습니다; 자동화에 투자하면 장기적으로 큰 이득을 얻습니다.
• 권한을 신중히 계획 – 팀 구조의 실수는 나중에 고치기 어렵습니다.
• 예외 케이스 문서화 – 앞으로의 마이그레이션에서 반드시 다시 등장하게 됩니다.
• 솔루션 공유 – 오픈 소스는 모두에게 이득이 됩니다; 여러분의 수정 사항을 기여하고 다른 사람들의 경험을 배워 보세요.

질문이나 전쟁 이야기가 있나요?

프레임워크 레포지토리에서 이슈를 열어 주세요. 여러분의 마이그레이션이 어떻게 작동했는지(또는 작동하지 않았는지) 듣고 싶습니다!