GitLab을 Self-Managed 환경에서 운영하는 분이라면 깊이 공감하실 겁니다. 버전 업그레이드가 정말 번거롭고 까다롭다는 사실을요. 단순히 Docker 이미지 태그를 바꾸거나 패키지 버전을 올리면 끝날 것 같지만, 현실은 전혀 그렇지 않습니다.

GitLab 업그레이드의 핵심 난관은 바로 '순차적 버전 경유'입니다. 예를 들어, 16.7에서 17.3으로 올리려면 다음과 같은 경로를 거쳐야 합니다.

16.7.x → 16.11.x → 17.0.x → 17.1.x → 17.3.x

각 버전에서 업그레이드 → 서비스 재시작 → Background Migration 완료 대기 → 헬스 체크를 반복해야 합니다. 특히 마이그레이션이 완료될 때까지 무작정 기다려야 하는데, 이 과정에서 버그나 데이터 문제로 마이그레이션이 실패하기라도 하면 해결책을 찾기 위해 끝없는 구글링의 늪에 빠지게 됩니다.

프로덕션 환경에서 메이저 버전 업그레이드는 그야말로 긴장의 연속입니다. 한 단계라도 빠뜨리면 데이터 정합성이 깨질 수 있으니까요. 다른 업무도 산더미인데 버전 하나 올리자고 반나절 내내 모니터 앞에 붙어 있어야 하는 상황, 소모적입니다. 그래서 생각했습니다.

"이 복잡한 과정을 자동화할 순 없을까?"

자동화를 시도해 봤지만, 기존의 쉘 스크립트로는 GitLab 업그레이드 과정에서 발생하는 에러 상황에 유연하게 대응하는 데 한계가 있었습니다. 하지만 Claude Code와 Skills의 등장으로 새로운 가능성이 열렸습니다. 이제 AI가 실시간으로 상황을 판단하고, 에러가 발생하면 스스로 웹을 검색해 해결책을 찾아 적용하며, GitLab 업그레이드를 자동으로 완료할 수 있습니다.

이 글에서는 Claude Code의 Skills를 활용해 GitLab 업그레이드를 자동화한 경험을 공유합니다. Skills의 기본 개념부터 설계 원칙, 실제 사용 예시, 마이그레이션 실패 시 AI의 문제 해결 과정까지 자세히 살펴보겠습니다.

Claude Code, Skills 개요​

Claude Code는 Anthropic에서 개발한 CLI 기반 AI 코딩 도구입니다. 터미널에서 Claude와 대화하면서 코드 작성, 파일 수정, 명령어 실행 등을 할 수 있죠.

여기에 Skills라는 기능이 있습니다. Skills는 SKILL.md 파일을 포함한 폴더로, 지침뿐만 아니라 실행 스크립트, 템플릿, 참조 문서 등을 함께 포함합니다. "이런 상황에서는 이렇게 해"라고 정의해두면 Claude가 모든 Skill의 description을 컨텍스트에서 확인하고, 작업 맥락에 맞는 Skill이 있다고 판단하면 전체 콘텐츠를 로드하여 그 지침을 따라 작업을 수행합니다.

SKILL.md 구조​

Skills는 SKILL.md 파일 하나로 정의됩니다. YAML frontmatter와 Markdown body로 구성되어 있습니다.

---
name: my-skill
description: 언제 이 스킬을 사용할지 설명
---

# 스킬 제목

여기에 Claude가 따라야 할 지침 작성
  • name: Skill 이름이자 /slash-command(예: /my-skill로 직접 호출 가능). 필수 필드입니다.
  • description: Skill이 무엇을 하고 언제 사용되는지 설명하는 필수 필드입니다. Claude가 자동으로 Skill을 로드할지 판단하는 핵심 정보로 사용됩니다.

GitLab 업그레이드 자동화 Skill 설계​

앞서 설명한 Skills 구조를 바탕으로, GitLab 업그레이드 자동화 Skill을 설계했습니다. 설계 시 가장 중요하게 생각한 점은 ‘수동 업그레이드의 안전성을 유지하면서 자동화하는 것’이었습니다. 이를 중심으로 다음 다섯 가지 핵심 설계 요소를 Skill에 반영했습니다.

핵심 설계 요소​

  1. 다양한 설치 유형 지원: RPM/DEB(Linux 패키지), Docker, Helm 등 각 환경에 맞는 업그레이드 방식을 분기 처리합니다.
  2. 공식 업그레이드 경로 자동 계산: GitLab Upgrade Path Tool을 활용하여 현재 버전에서 목표 버전까지 최적의 경로를 계산합니다.
  3. Background Migration 모니터링(가장 중요!): 다음 단계로 넘어가기 전, 모든 Background Migration이 완료되었는지 5분 간격으로 체크하며 대기합니다.
  4. 백업, 롤백 전략: 업그레이드 직전 스냅샷이나 백업을 생성하여 문제 발생 시 즉시 롤백할 수 있는 안전장치를 마련합니다.
  5. 지능적 문제 해결: 마이그레이션 실패 시 Claude가 에러 메시지를 분석하고, 공식 문서나 이슈 트래커를 검색해 해결책(예: gitlab-rails console 명령 실행)을 찾아 적용합니다.

실제 사용 예시​

앞서 설계한 Skill을 사용해 GitLab을 18.3.6으로 업그레이드한 과정을 단계별로 살펴보겠습니다.

업그레이드 요청​

터미널에서 Claude를 실행하고 자연어로 GitLab 18.3.6으로 업그레이드를 요청합니다.

Claude로 GitLab 업그레이드 요청 화면 | 인포그랩 GitLab
Claude로 GitLab 업그레이드 요청 화면

환경 확인, 경로 계산​

Claude는 다음과 같은 질문으로 환경 정보를 수집합니다.

  • "어떤 유형의 GitLab을 업그레이드하시나요?(RPM/DEB/Docker/Helm)"
    Claude의 설치 유형 질문 | 인포그랩 GitLab
    Claude의 설치 유형 질문

  • "docker-compose.yml 파일의 경로를 알려주세요."
    Claude의 설정 파일 경로 질문 | 인포그랩 GitLab
    Claude의 설정 파일 경로 질문

사용자가 답변하면 Claude가 자동으로 현재 버전을 확인하고, GitLab Upgrade Path Tool에서 거쳐야 할 버전 목록을 가져옵니다.

Claude의 GitLab 업그레이드 경로 확인 결과 | 인포그랩 GitLab
Claude의 GitLab 업그레이드 경로 확인 결과

자동 업그레이드​

이후에는 사람의 개입이 거의 필요 없습니다. Claude가 다음 단계를 자동으로 수행합니다.

  1. 백업 생성
  2. 첫 번째 중간 버전으로 업그레이드
    Claude의 백업 생성, 순차적 업그레이드 과정 | 인포그랩 GitLab
    Claude의 백업 생성, 순차적 업그레이드 과정

  3. Background Migration 완료 대기(5분 간격 확인)
  4. 다음 버전으로 업그레이드
    Claude의 Background Migration 상태 확인, 다음 버전 업그레이드 과정 | 인포그랩 GitLab
    Claude의 Background Migration 상태 확인, 다음 버전 업그레이드 과정

  5. 3 ~ 4단계 반복
  6. 최종 목표 버전 도달 후 헬스 체크
    Claude의 GitLab 업그레이드 완료 확인, 헬스 체크 결과 | 인포그랩 GitLab
    Claude의 GitLab 업그레이드 완료 확인, 헬스 체크 결과

업그레이드 완료​

몇 차례 대화만으로 복잡하고 번거로운 GitLab 18.3.6 업그레이드가 완료됩니다. 다른 업무를 진행하면서도 성공적으로 마무리할 수 있습니다.

18.3.6으로 업그레이드가 완료된 GitLab 상태 | 인포그랩 GitLab
18.3.6으로 업그레이드가 완료된 GitLab 상태

마이그레이션 실패 시 대응​

GitLab 업그레이드 과정에서 가장 골치 아픈 문제는 Background Migration 실패입니다. 예전에는 에러 메시지를 복사해 구글링하고 이슈 트래커를 검색하느라 문제를 해결하는 데 시간이 오래 걸렸습니다.

하지만 Skills를 활용하면 트러블슈팅 시간을 크게 단축할 수 있습니다. Claude는 다음 과정을 수행합니다.

  1. 실패한 마이그레이션 항목과 에러 로그를 식별합니다.
  2. 해당 에러 메시지를 기반으로 실시간 웹 검색을 수행합니다.
  3. GitLab 공식 문서에서 해결책을 찾습니다.
  4. gitlab-rails console 등에서 필요한 명령을 실행해 문제를 해결합니다.

AI가 모든 문제를 완벽히 해결할 수는 없지만, "이 에러는 이렇게 해결하면 된다"는 방향을 빠르게 제시하므로 훨씬 더 수월하게 대응할 수 있습니다.

맺음말​

이 Skill을 만들고 가장 좋았던 점은 더 이상 모니터 앞에 오래 붙어 있지 않아도 된다는 점입니다. 예전에는 업그레이드 경로가 긴 GitLab 버전을 올릴 때, 몇 시간 동안 대기해야 했습니다. 이제는 Skill을 실행해 두고 다른 업무를 보거나, 다음 날 결과를 확인하면 됩니다.

이번 경험을 바탕으로 앞으로는 사내 GitLab 환경에서 업그레이드 후 변경 사항 자동 정리, Slack 알림 연동, 여러 환경의 순차 업그레이드 기능을 추가하고, 내부 운영 자동화를 고도화하고 싶습니다.

지금까지 Skills를 활용해 GitLab 업그레이드를 자동화한 경험을 공유했습니다. 핵심은 단순한 ‘자동화 스크립트’가 아니라, 자율적으로 상황을 판단하고 문제를 해결하는 AI 에이전트 기반 자동화라는 점입니다.

여러분도 반복적이고 번거로운 작업이 있다면, Skills로 자동화를 시도해 보시길 바랍니다.

참고 자료​

  1. Claude Code Skills 공식 기술 문서, https://code.claude.com/docs/en/skills
  2. GitLab 업그레이드 공식 가이드, https://docs.gitlab.com/update/
  3. GitLab Upgrade Path Tool, https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/

완벽한 GitLab 구축부터 성공적인 DevOps 도입까지! 인포그랩과 DevOps 라이프사이클을 함께하세요.