---
title: "Claude Skills로 GitLab 업그레이드 자동화하기"
description: "이 글은 Claude Code의 Skills를 활용해 GitLab 업그레이드를 자동화한 경험을 공유합니다. Skills의 기본 개념부터 설계 원칙, 실제 사용 예시, 마이그레이션 실패 시 AI의 문제 해결 과정까지 자세히 다뤘습니다."
url: https://insight.infograb.net/blog/2026/01/28/claude-skills-gitlab/
source: content/generated/blog/2026-01-28-claude-skills-gitlab.md
---

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

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

```plain text
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로 구성되어 있습니다.

```markdown
---
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](https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/)을 활용하여 현재 버전에서 목표 버전까지 최적의 경로를 계산합니다.
3. **Background Migration 모니터링**(가장 중요!): 다음 단계로 넘어가기 전, 모든 Background Migration이 완료되었는지 5분 간격으로 체크하며 대기합니다.
4. **백업, 롤백 전략**: 업그레이드 직전 스냅샷이나 백업을 생성하여 문제 발생 시 즉시 롤백할 수 있는 안전장치를 마련합니다.
5. **지능적 문제 해결**: 마이그레이션 실패 시 Claude가 에러 메시지를 분석하고, 공식 문서나 이슈 트래커를 검색해 해결책(예: `gitlab-rails console` 명령 실행)을 찾아 적용합니다.

## **실제 사용 예시**

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

### 업그레이드 요청

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

![Claude로 GitLab 업그레이드 요청 화면](/img/blog/2026-01-28-claude-skills-gitlab-inline-01.png)
*Claude로 GitLab 업그레이드 요청 화면*

### 환경 확인, 경로 계산

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

- "어떤 유형의 GitLab을 업그레이드하시나요?(RPM/DEB/Docker/Helm)"

    ![Claude의 설치 유형 질문](/img/blog/2026-01-28-claude-skills-gitlab-inline-02.png)
    *Claude의 설치 유형 질문*

- "`docker-compose.yml` 파일의 경로를 알려주세요."

    ![Claude의 설정 파일 경로 질문](/img/blog/2026-01-28-claude-skills-gitlab-inline-03.png)
    *Claude의 설정 파일 경로 질문*

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

![Claude의 GitLab 업그레이드 경로 확인 결과](/img/blog/2026-01-28-claude-skills-gitlab-inline-04.png)
*Claude의 GitLab 업그레이드 경로 확인 결과*

### 자동 업그레이드

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

1. 백업 생성
2. 첫 번째 중간 버전으로 업그레이드

    ![Claude의 백업 생성, 순차적 업그레이드 과정](/img/blog/2026-01-28-claude-skills-gitlab-inline-05.png)
    *Claude의 백업 생성, 순차적 업그레이드 과정*

3. Background Migration 완료 대기(5분 간격 확인)
4. 다음 버전으로 업그레이드

    ![Claude의 Background Migration 상태 확인, 다음 버전 업그레이드 과정](/img/blog/2026-01-28-claude-skills-gitlab-inline-06.png)
    *Claude의 Background Migration 상태 확인, 다음 버전 업그레이드 과정*

5. 3 ~ 4단계 반복
6. 최종 목표 버전 도달 후 헬스 체크

    ![Claude의 GitLab 업그레이드 완료 확인, 헬스 체크 결과](/img/blog/2026-01-28-claude-skills-gitlab-inline-07.png)
    *Claude의 GitLab 업그레이드 완료 확인, 헬스 체크 결과*

### 업그레이드 완료

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

![18.3.6으로 업그레이드가 완료된 GitLab 상태](/img/blog/2026-01-28-claude-skills-gitlab-inline-08.png)
*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로 자동화를 시도해 보시길 바랍니다.

::cta::

## 참고 자료

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

::faq::

- q: Self-Managed GitLab 업그레이드가 까다로운 이유는 무엇인가요?

    a: GitLab은 목표 버전으로 바로 올릴 수 없고 정해진 중간 버전을 순차적으로 거쳐야 하기 때문입니다. 예를 들어 16.7에서 17.3으로 올리려면 16.11, 17.0, 17.1을 거쳐야 하고, 버전마다 업그레이드, 서비스 재시작, Background Migration 완료 대기, 헬스 체크를 반복해야 합니다. 한 단계라도 빠뜨리면 데이터 정합성이 깨질 수 있고, 마이그레이션이 실패하면 해결책을 찾는 데 시간이 오래 걸립니다.

- q: GitLab 업그레이드를 쉘 스크립트 대신 Claude Code Skills로 자동화하는 이유는 무엇인가요?

    a: 쉘 스크립트로는 업그레이드 중 발생하는 에러 상황에 유연하게 대응하기 어렵기 때문입니다. Claude Code Skills를 쓰면 AI가 실시간으로 상황을 판단하고, 에러가 나면 스스로 웹을 검색해 해결책을 찾아 적용하며 업그레이드를 끝까지 진행합니다. 업그레이드 경로가 길어 몇 시간씩 대기해야 했던 작업도 Skill을 실행해 두고 다른 업무를 보거나 다음 날 결과를 확인하면 됩니다.

- q: Claude Code Skills로 GitLab 업그레이드는 어떤 순서로 진행되나요?

    a: 터미널에서 Claude에게 목표 버전으로 업그레이드해 달라고 자연어로 요청하면, Claude가 설치 유형과 docker-compose.yml 같은 설정 파일 경로를 묻습니다. 답하면 Claude가 현재 버전을 확인하고 GitLab Upgrade Path Tool에서 거쳐야 할 버전 목록을 가져옵니다. 이후 백업 생성, 중간 버전 업그레이드, Background Migration 완료 대기(5분 간격 확인), 다음 버전 업그레이드를 반복하고 목표 버전에 도달하면 헬스 체크까지 자동으로 수행합니다.

- q: GitLab 업그레이드 자동화 Skill에는 어떤 설계 요소가 필요한가요?

    a: 수동 업그레이드의 안전성을 유지하면서 자동화하려면 다섯 가지 요소가 필요합니다. RPM/DEB(Linux 패키지), Docker, Helm 등 설치 유형별 분기, GitLab Upgrade Path Tool을 활용한 공식 업그레이드 경로 자동 계산, Background Migration 완료 확인, 업그레이드 직전 스냅샷·백업과 롤백 전략, 마이그레이션 실패 시 에러 분석과 해결책 적용입니다. 가장 중요한 요소는 모든 Background Migration이 완료된 것을 확인한 뒤에만 다음 버전으로 넘어가게 하는 것입니다.

- q: GitLab Background Migration이 실패하면 Claude는 어떻게 대응하나요?

    a: Claude는 실패한 마이그레이션 항목과 에러 로그를 식별한 뒤, 에러 메시지로 실시간 웹 검색을 해 GitLab 공식 문서에서 해결책을 찾습니다. 그다음 gitlab-rails console 등에서 필요한 명령을 실행해 문제를 해결합니다. AI가 모든 문제를 완벽히 해결하지는 못하지만 해결 방향을 빠르게 제시하므로 트러블슈팅 시간을 크게 줄일 수 있습니다.

::faq-end::

::button::[GitLab 업그레이드와 운영을 더 안정적으로 관리하고 싶으신가요? GitLab 공식 파트너 인포그랩과 상담하세요!](https://insight.infograb.net/contact/)::