• 설치 방법별 업그레이드
• 업그레이드 계획
• 업그레이드 전 백그라운드 마이그레이션 확인
• 실행 중인 CI/CD 파이프라인 및 작업 처리
• 보류 중인 고급 검색 마이그레이션 확인
  • 고급 검색 마이그레이션이 멈춘 경우 어떻게 해야 하나요?
  • Elasticsearch 버전 호환되지 않음 오류가 발생하는 경우 어떻게 해야 하나요?
• 다운타임 없이 업그레이드
• 새 주요 버전으로 업그레이드
• 업그레이드 경로
  • 업그레이드 경로 도구
  • 이전 GitLab 버전
• 에디션 간의 업그레이드
  • 커뮤니티 에디션에서 엔터프라이즈 에디션으로
  • 엔터프라이즈 에디션에서 커뮤니티 에디션으로
• 버전별 업그레이드 지침
  • GitLab 17
  • GitLab 16
  • GitLab 15
• 기타

GitLab 업그레이드

GitLab의 업그레이드는 비교적 간단한 프로세스이지만, 사용한 설치 방법, GitLab 버전의 오래된 정도, 주요 버전으로의 업그레이드 여부 등에 따라 복잡성이 증가할 수 있습니다.

각 업그레이드 방법과 관련된 정보가 포함된 전체 페이지를 읽어보세요.

유지보수 정책 문서에는 업그레이드에 대한 추가 정보가 포함되어 있습니다.

• GitLab 제품 버전 관리 방법 해석.
• 실행할 릴리스에 대한 권장 사항.
• 패치 및 보안 패치 릴리스 사용 방법.
• 코드 변경을 되돌리는 시기.

설치 방법별 업그레이드

설치 방법 및 GitLab 버전에 따라 여러 공식 업그레이드 방법이 있습니다:

업그레이드 계획

GitLab 업그레이드를 위한 계획은 이 가이드를 참조하세요.

업그레이드 전 백그라운드 마이그레이션 확인

특정 릴리스는 새 버전으로 업그레이드하기 전에 다른 마이그레이션 작업을 완료해야 할 수 있습니다.

자세한 내용은 백그라운드 마이그레이션을 확인하세요.

실행 중인 CI/CD 파이프라인 및 작업 처리

GitLab 인스턴스를 업그레이드하는 동안 GitLab Runner가 작업을 처리하는 경우, 추적 업데이트가 실패합니다. GitLab이 다시 온라인 상태가 되면 추적 업데이트가 자체적으로 복구됩니다. 그러나 오류에 따라 GitLab Runner는 작업 처리를 다시 시도하거나 최종적으로 종료됩니다.

아티팩트에 대해서는 GitLab Runner가 3회 시도한 후 작업이 최종적으로 실패합니다.

위 두 시나리오를 해결하려면 다음과 같이 업그레이드 전에 다음을 수행하는 것이 좋습니다:

1. 유지보수 계획 수립.

2. 다음 내용을 /etc/gitlab/gitlab.rb에 추가하여 러너를 일시 중지하거나 새로운 작업이 시작되는 것을 차단하세요.

   nginx['custom_gitlab_server_config'] = "location ^~ /api/v4/jobs/request {\n deny all;\n return 503;\n}\n"
   

   그리고 다음과 같이 GitLab을 재구성하세요.

   sudo gitlab-ctl reconfigure
   

3. 모든 작업이 완료될 때까지 기다립니다.
4. GitLab을 업그레이드하세요.
5. GitLab Runner를 GitLab 버전과 동일하게 업그레이드하세요. 두 버전은 동일해야 합니다.
6. 이전의 /etc/gitlab/gitlab.rb 변경 사항을 되돌려 러너를 재개하고 새로운 작업을 차단하세요.

보류 중인 고급 검색 마이그레이션 확인

이 섹션은 Elasticsearch 통합을 활성화한 경우에만 적용됩니다. 주요 릴리스는 현재 버전의 최신 마이너 릴리스에서 기존 버전으로 업그레이드하기 전에 고급 검색 마이그레이션을 완료해야 합니다. 현재 버전에서 보류 중인 마이그레이션을 찾으려면 아래 명령을 사용하세요.

sudo gitlab-rake gitlab:elastic:list_pending_migrations

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations

고급 검색 마이그레이션이 멈춘 경우 어떻게 해야 하나요?

GitLab 15.0에서 DeleteOrphanedCommit이라는 고급 검색 마이그레이션이 계속해서 보류 중인 상태로 남을 수 있습니다. 이 문제는 GitLab 15.1에서 수정됩니다.

GitLab 15.0을 사용하는 Self-Managed형 고객이 고급 검색을 사용하는 경우 성능 저하를 경험할 것입니다. 이 마이그레이션을 정리하려면 15.1 이상으로 업그레이드하세요.

보류 중인 다른 고급 검색 마이그레이션이 있다면, 멈춘 마이그레이션을 다시 시도하는 방법에 대한 자세한 내용은 멈춘 마이그레이션 다시 시도를 참조하세요.

보류 중인 고급 검색 마이그레이션이 완료되지 않은 채 GitLab을 업그레이드하면 새 버전에서 제거된 보류 중인 마이그레이션이 실행되거나 재시도할 수 없습니다. 이 경우에는 처음부터 인덱스를 다시 생성해야 합니다.

Elasticsearch 버전 호환되지 않음 오류가 발생하는 경우 어떻게 해야 하나요?

Elasticsearch 또는 OpenSearch 버전이 GitLab 버전과 호환되는지 확인하세요.

다운타임 없이 업그레이드

다운타임 없이 업그레이드하는 방법을 읽으세요.

새 주요 버전으로 업그레이드

주요 버전을 업그레이드하는 경우 더 주의해야 합니다. 주요 버전에는 하위 호환되지 않는 변경 사항이 포함됩니다. 주요 업그레이드에는 다음 단계가 필요합니다.

1. 지원되는 업그레이드 경로를 식별합니다. 이전 주요 버전의 마지막 마이너 릴리스는 항상 백그라운드 마이그레이션이 도입되어 필수적인 단계입니다.
2. 새 주요 버전으로의 업그레이드 전에 백그라운드 마이그레이션이 완전히 완료되었는지 확인하세요.
3. Elasticsearch 통합을 활성화한 경우, 새 주요 버전으로 진행하기 전에 모든 고급 검색 마이그레이션이 완료되었는지 확인하세요.
4. GitLab 인스턴스에 연결된 러너가 있는 경우 현재 GitLab 버전과 일치하도록 러너를 업그레이드하는 것이 매우 중요합니다. 이는 GitLab 버전과의 호환성을 보장하기 위함입니다.

업그레이드 경로

여러 GitLab 버전 간의 업그레이드는 다운타임을 수락해야만 가능합니다. 다운타임을 피하고 싶다면 다운타임 없이 업그레이드하는 방법을 읽어보세요.

업그레이드 경로에는 필수 업그레이드 중지가 포함됩니다. 이는 향후 버전으로 업그레이드하기 전에 반드시 업그레이드해야 하는 GitLab 버전입니다. 업그레이드 경로를 이동할 때는 다음 단계를 따릅니다.

1. 현재 버전 이후 필수 업그레이드 중지로 업그레이드합니다.
2. 업그레이드의 백그라운드 마이그레이션을 완료할 때까지 기다립니다.
3. 다음 필수 업그레이드 중지로 업그레이드합니다.

업그레이드 경로를 결정하려면 다음을 수행합니다.

1. 현재 버전이 위치한 업그레이드 경로 참고 및 필수 업그레이드 중지 포함:

   • GitLab 15은 다음 필수 업그레이드 중지를 포함합니다:
     • 15.0.5.
     • 15.1.6. 여러 웹 노드를 가진 GitLab 인스턴스.
     • 15.4.6.
     • 15.11.13. 최신 GitLab 15.11 릴리스.
   • GitLab 16은 다음 필수 업그레이드 중지를 포함합니다:
     • 16.0.8. 많은 사용자를 가진 인스턴스.
     • 16.1.6. 패키지 레지스트리에 NPM 패키지를 가진 인스턴스.
     • 16.2.9. 많은 파이프라인 변수 이력을 가진 인스턴스.
     • 16.3.7.
     • 16.7.z. 최신 GitLab 16.7 릴리스.
     • 16.11.z. 최신 GitLab 16.11 릴리스.
   • GitLab 17: 17.y.z. 최신 GitLab 17 릴리스.

2. 버전별 업그레이드 지침 참조.

명시적으로 지정되지 않은 경우, 업그레이드 경로에서 major.minor 릴리스의 최신 패치 릴리스로 GitLab을 업그레이드합니다. 예를 들어, 16.8.0 대신 16.8.7을 사용합니다.

업그레이드 경로에서 중지해야 하는 major.minor 버전을 포함하는 이유는 업그레이드 프로세스와 관련된 문제에 대한 수정사항이 있을 수 있기 때문입니다.

특히 주요 버전을 다룰 때, 최신 패치 릴리스에 중요한 데이터베이스 스키마 및 마이그레이션 패치가 포함될 수 있습니다.

업그레이드 경로 도구

현재 버전과 원하는 대상 GitLab 버전을 기반으로 필요한 업그레이드 중지를 빠르게 계산하려면 업그레이드 경로 도구를 참조하세요. 이 도구는 GitLab 지원팀에 의해 유지보수됩니다.

도구를 향상시키고 피드백을 공유하려면 upgrade-path 프로젝트에서 이슈를 생성하거나 Merge Request를 만드세요.

이전 GitLab 버전

이전 GitLab 버전으로의 업그레이드에 대한 정보는 문서 아카이브에서 확인하세요. 아카이브 문서에는 이전 GitLab 버전에 대한 특정 정보가 포함되어 있습니다.

예를 들어, GitLab 15.11 문서에는 GitLab 12 이후 버전에 대한 정보가 포함되어 있습니다.

에디션 간의 업그레이드

GitLab은 커뮤니티 에디션(MIT 라이선스)과 엔터프라이즈 에디션(커뮤니티 에디션 기반으로 한 기업용 기능이 추가된 에디션) 두 가지로 제공됩니다.

아래에서 GitLab 에디션을 변경하는 데 도움이 되는 일부 안내서를 찾을 수 있습니다.

커뮤니티 에디션에서 엔터프라이즈 에디션으로

GitLab 설치를 커뮤니티 에디션에서 엔터프라이즈 에디션으로 업그레이드하려면 아래 안내서를 따르세요.

• 소스 CE에서 EE로 업그레이드 가이드 - 단계는 버전 업그레이드와 매우 유사합니다: 서버 중지, 코드 가져오기, 새 기능을 위한 구성 파일 업데이트, 라이브러리 설치 및 마이그레이션, init 스크립트 업데이트, 응용 프로그램 시작 및 상태 확인.
• Omnibus CE에서 EE로 - Omnibus GitLab 커뮤니티 에디션을 엔터프라이즈 에디션으로 업그레이드하려면 이 안내서를 참조하세요.
• Docker CE에서 EE로 - GitLab 커뮤니티 에디션 컨테이너를 엔터프라이즈 에디션 컨테이너로 업그레이드하려면 이 안내서를 참조하세요.
• Helm 차트 (Kubernetes) CE에서 EE로 - GitLab 커뮤니티 에디션 Helm 배포를 엔터프라이즈 에디션으로 업그레이드하려면 이 안내서를 참조하세요.

엔터프라이즈 에디션에서 커뮤니티 에디션으로

엔터프라이즈 에디션 설치를 커뮤니티 에디션으로 다운그레이드하려면 가능한 매끄러운 프로세스를 위해 이 안내서를 따르세요.

버전별 업그레이드 지침

매달 GitLab의 주요 또는 마이너 버전과 패치 릴리스가 발행됩니다. 그리고 릴리스 포스트가 게시됩니다. 커다란 버전 및 마이너 릴리스 포스트 마지막 부분에는 다음과 같은 세 가지 섹션이 있습니다.

• 폐기 예고
• 삭제
• 업그레이드에 대한 중요 사항

여기에는 다음이 포함됩니다.

• 업그레이드의 일환으로 수행해야 하는 단계. 예를 들어, 8.12에서는 Elasticsearch 인덱스를 다시 생성해야 합니다. 따라서 8.12나 이후 버전부터 업그레이드하는 경우 이를 수행해야 합니다.
• GitLab 13에서 IE11 지원 중단과 같이 지원하는 소프트웨어 버전의 변경 사항.

이 섹션에 제시된 지침 외에도 GitLab을 설치한 방법에 따라 설치별 업그레이드 지침을 확인해야 합니다.

• 리눅스 패키지(Omnibus GitLab)
• Helm 차트

GitLab 17

GitLab 17로 업그레이드하기 전에 GitLab 17 변경 내역을 확인하세요.

GitLab 16

GitLab 16로 업그레이드하기 전에 GitLab 16 변경 사항을 참조하십시오.

GitLab 15

GitLab 15로 업그레이드하기 전에 GitLab 15 변경 사항을 참조하십시오.

기타

• PostgreSQL 확장 관리