혼돈에서 완벽한 흐름으로: GitLab에서 거대한 실제 마이그레이션(4,000개 레포) 자동화한 나의 경험

I’m happy to translate the article for you, but I need the text you’d like translated. Could you please paste the content (or the portion you want translated) here? I’ll keep the source link exactly as you provided and preserve all formatting, markdown, and technical terms.

왜 이 마이그레이션이 필요했는가

GitLab Community Edition은 처음에는 잘 작동합니다. 하지만 팀이 성장하고, 저장소가 늘어나며 파이프라인 양이 폭발하면 명확한 한계가 드러납니다:

• 거버넌스 부재
• 일관성 없는 설정
• 이질적인 러너들
• 불안정한 파이프라인
• 필수 기업 리소스 부재

GitLab Enterprise Edition으로의 마이그레이션은 단순한 기술적 개선을 넘어 조직 성숙도로 가는 한 걸음이었습니다.

도전 과제

모든 것을 올바르게 보존하는 공식 마이그레이션은 존재하지 않는다.

다른 방법이 없어 자체 솔루션을 만들었습니다.

이 마이그레이션이 복잡한 이유는?

4 천 개 프로젝트를 옮기는 것은 폴더를 옮기는 것이 아닙니다. 전체 생태계를 보존해야 하는데, 여기에는 다음과 같은 요소들이 포함됩니다:

• 전체 커밋 히스토리
• 보호된 브랜치
• 릴리즈 태그
• 변수와 시크릿
• 여기저기 흩어져 있는 includes가 포함된 파이프라인
• 이슈와 댓글
• 보관 상태
• 러너와 권한

GitLab의 기본 import/export 도구는 이 과정의 대부분을 깨뜨립니다. 저는 모든 것을 신뢰성 있게 마이그레이션할 수 있는 자동화를 구축해야 했습니다.

다리를 만든 툴킷

마이그레이션의 각 부분에 대한 절대적인 제어를 보장하기 위해 Bash로 작성된 모듈식 스크립트 세트를 개발했습니다. 여기에서 공개됩니다:

👉

2계층 아키텍처

Git 레이어 – 담당 업무:

• 모든 저장소 복제
• 브랜치 재구성
• DAG 무결성 보장
• CE와 동일하게 태그 보존
• 원격 재설정
• 아카이브 상태 재적용

API 레이어 – 담당 업무:

• 변수 및 비밀
• 이슈 및 댓글
• 그룹 계층 구조
• 권한
• 대상에서 프로젝트 재생성

각 스크립트는 한 가지 작업만 수행했지만 정확하게 수행했습니다. 그 중에는:

• clone-projects.sh
• replace_gitlab-ci.sh
• push_projects.sh
• migrar-variaveis.sh
• migrate-issues.sh
• 하위 그룹을 위한 재귀 스크립트
• 러너 전체 인벤토리

목적이 있는 자동화였으며, 마법은 아니었습니다.

나타난 숨겨진 혼돈

공식 문서는 도움이 되었지만 부분적으로만 그랬다. 많은 부분이 일관성이 없고, 불완전하거나 대규모로 적용했을 때 설명대로 작동하지 않았다.

또한 다음과 같은 문제들을 발견했다:

• 마이그레이션 후 깨질 절대 경로를 가진 파이프라인 includes
• 중복된 변수, 범위가 없거나 정리되지 않은 변수
• 예측할 수 없는 설정을 가진 오래된 러너들
• 공식 가져오기에서 보관된 프로젝트가 활성 상태로 다시 나타남
• 태그가 잘못 재생성됨

표준 프로세스를 채택하면 조직 전체에 심각한 운영 영향을 초래했을 가능성이 있다.

파일럿 테스트… 그리고 마이그레이션을 구원한 오류들

모든 것이 정상적으로 작동하도록 보장하기 위해, 격리된 환경에서 여러 파일럿 테스트를 실행했습니다. 예외 없이 모두 초기 단계에서 오류가 발생했습니다.

발견된 실패 사례

include: /old-group/subgroup/template.yml

• 오래된 includes 때문에 파이프라인이 깨짐
• 작업을 중단시키는 누락된 변수
• 실행을 거부하는 러너
• 보이지 않는 세부 사항으로 인한 잘못된 YAML
• 사라지거나 잘못 재생성된 태그
• 순서가 뒤섞인 계층 구조

이러한 오류가 바로 최종 성공의 이유였습니다.

[Image: 파이프라인 오류]

문제를 완화한 방법

오래된 includes 때문에 깨진 파이프라인을 해결하기 위해, 로컬에 복제된 폴더 내에서 각 include를 재귀적으로 분석하고 새로운 GitLab에 새로운 경로가 생성될 때 자동으로 새 경로를 추가하는 스크립트를 만들었습니다.

각 실패는 GitLab의 실제 동작을 드러냈습니다. 오류는 어떤 문서보다도 더 많은 것을 가르쳐 주었습니다. 테스트마다:

• 새로운 검증을 추가함
• 필터를 생성함
• 로그를 강화함
• 특수 사례를 수정함
• 멱등 검사를 추가함

테스트가 최종적으로 깨끗이 통과했을 때, 자동화가 실제로 신뢰할 수 있음을 입증했습니다.

실제 마이그레이션의 날

전체 마이그레이션 파이프라인을 실행했을 때, 결과는 성공적인 엔지니어링 시나리오에서 기대한 바와 정확히 일치했습니다:

• 히스토리 손실 없음
• 태그 깨짐 없음
• 파이프라인 정상 작동
• 올바른 스코프로 변수 재생성
• 계층 구조 보존
• 코드가 목적지에 올바르게 도착
• 보관된 리포지토리는 계속 보관 상태 유지
• 러너가 균일하게 작동

혼란스러운 시스템을 예측 가능하고 표준화된, 관리되는 환경으로 바꾼 것과 같았습니다.

이것이 팀에 미치는 영향

초기에 DORA에 대한 공식 측정이 없었음에도, 마이그레이션 이후의 행동 양상이 뚜렷했습니다.

![Image: Métricas DORA]

관찰된 결과

• Deploys 가 더 자주 이루어짐
• Lead time 이 급격히 감소함
• Pipelines 가 더 안정적으로 변함
• Change Failure Rate 가 감소함
• 표준화된 Runner 로 인해 이상 오류가 줄어듦
• 완전한 히스토리를 바탕으로 복구 속도가 빨라짐

이 이야기는 모듈식, 테스트 주도, 로그 중심 접근 방식이 대규모 마이그레이션을 신뢰할 수 있고 반복 가능한 프로세스로 어떻게 바꿀 수 있는지를 보여줍니다.

![Image: Migrating GitLab Projects]

전체 조직이 더 빠르게 움직이게 되었다

이 경험이 나에게 가르쳐준 것

• 공식 문서는 절대 100 %의 경우를 다루지 않는다
• 표준화는 신뢰성의 기반이다
• 파이프라인은 변수에 깊이 의존한다
• 러너는 CI/CD의 보이지 않는 건강을 정의한다
• 오류는 엔지니어링에서 필수적인 역할을 한다
• 잘 구축된 자동화는 신뢰를 만든다

그리고 가장 큰 교훈:
기반을 재구성하면 개발 흐름 전체가 개선된다.

결론

수천 개의 프로젝트를 마이그레이션하는 것은 단순한 기술적 도전이 아닙니다.
이는 규율, 엔지니어링, 그리고 회복탄력성의 증명입니다.

결정론적 자동화, 실제 파일럿 테스트, 그리고 오류를 통한 학습을 통해 약 4 000개의 저장소를 안전하게 마이그레이션할 수 있었으며, 코드, 파이프라인, 히스토리 및 거버넌스의 무결성을 유지했습니다.

프로젝트의 향후 발전 가능성을 강조하는 것이 중요합니다. Python으로의 재작성은 자연스러운 단계로 간주되며, 코드의 유연성과 흐름성을 높이면서 현재 Bash로 구현된 솔루션의 효율성과 견고함을 무시하지 않습니다.

해당 솔루션은 공개적으로 이용 가능하며, 유사한 도전에 직면한 다른 사람들에게 기반이 될 수 있습니다:

⭐ 프로젝트가 마음에 드셨다면, GitHub에 ⭐ 별 ⭐ 을 남겨 주세요 – 이는 작업을 강화하고 가치를 높이는 데 큰 도움이 됩니다.

👉

대규모 마이그레이션을 계획하고 있다면, 기억하세요:

오류는 적이 아니다.
그들은 안내자이다.

그리고 잘 된 자동화는 두려움을 신뢰로 바꿉니다.

📚 참고 문헌

• GitLab Documentation –
• GitLab Import/Export Guide –
• GitLab API Reference –
• Google Cloud – DORA Research & Four Key Metrics –
• Accelerate: State of DevOps Report (DORA) –
• Martin Fowler – Continuous Delivery & Infrastructure as Code –
• Google SRE Book – Eliminating Toil & Reliability Engineering –
• Pro Git Book – Git Internals –
• Advanced Bash Scripting Guide –
• GitHub Engineering – Migration and Automation Insights