• 설치 방법에 따른 업그레이드
• 업그레이드 계획 수립
• 업그레이드 전 백그라운드 마이그레이션 확인
• 실행 중인 CI/CD 파이프라인 및 작업 다루기
• 보류 중인 고급 검색 마이그레이션 확인
  • 만약 고급 검색 마이그레이션이 막혔다면 어떻게 해야 합니까?
  • ‘Elasticsearch version not compatible’ 오류에 대해 해결 방법
• 다운타임 없이 업그레이드하기
• 새 주요 버전으로 업그레이드하기
• 업그레이드 경로
  • 필수 업그레이드 중지점
  • 이전 GitLab 버전
• 에디션 간 업그레이드
  • 커뮤니티 에디션에서 엔터프라이즈 에디션으로
  • 기업에서 커뮤니티 에디션으로 변경
• 특정 버전에 따른 업그레이드 지침
  • GitLab 16
  • GitLab 15
  • GitLab 14
• 기타

GitLab 업그레이드

GitLab을 업그레이드하는 것은 비교적 간단한 프로세스입니다. 그러나 설치 방법, GitLab 버전의 오래 된 정도, 주요 버전으로 업그레이드하는 경우 등에 따라 복잡성이 증가할 수 있습니다.

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

유지보수 정책 설명서에는 다음과 같은 추가 정보가 포함되어 있습니다:

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

설치 방법에 따른 업그레이드

설치 방법과 GitLab 버전에 따라, GitLab을 업그레이드하는 데 공식적으로 여러 방법이 있습니다:

업그레이드 계획 수립

GitLab 업그레이드 계획 수립 안내를 참조하세요.

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

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

자세한 정보는 백그라운드 마이그레이션을 참조하세요.

실행 중인 CI/CD 파이프라인 및 작업 다루기

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

아티팩트의 경우 GitLab Runner는 세 번 시도한 후 작업이 최종적으로 실패합니다.

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

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 version not compatible’ 오류에 대해 해결 방법

Elasticsearch 또는 OpenSearch 버전이 GitLab 버전과 호환되는지 확인하십시오.

다운타임 없이 업그레이드하기

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

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

새로운 주요 버전으로 업그레이드하는 것은 더 많은 주의를 요구합니다. 하위 호환성 변경 사항은 주요 버전에 보존됩니다. 주요 업그레이드를 진행할 때 주의 깊게 지침을 따르십시오. 주요 업그레이드에는 다음 단계가 필요합니다:

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

업그레이드 경로

한 번에 여러 GitLab 버전 간의 업그레이드는 다운타임을 허용하는 것으로만 가능합니다. 다운타임을 허용하지 않으려면 다운타임 없이 업그레이드하는 방법을 읽어보세요.

지원되는 업그레이드 경로의 동적 예제를 확인하기 위해 Upgrade Path 도구

을 사용해보세요. 이는 GitLab 지원 팀이 유지보수하는 도구입니다. 도구를 개선하기 위해 피드백을 공유하고 도움을 주려면 upgrade-path 프로젝트 에서 이슈를 생성하거나 MR을 만들어주세요.

업그레이드 시:

1. 업그레이드 경로에서 자신의 버전이 위치한 곳을 찾으십시오:

   • GitLab 14: 14.0.12 > 14.3.6 > 14.9.5 > 14.10.5.
   • GitLab 15: 15.0.5 > 15.1.6 (다중 웹 노드가 있는 GitLab 인스턴스의 경우) > 15.4.6 > 15.11.13.
   • GitLab 16: 16.0.8 (오직 많은 사용자나 큰 파이프라인 변수 히스토리가 있는 경우) > 16.1.6 (패키지 레지스트리에 NPM 패키지가 있는 경우) > 16.2.9 (오직 큰 파이프라인 변수 히스토리가 있는 경우) > 16.3.7 > 16.7.z > 최신 16.Y.Z.
2. 필수 업그레이드 중지점을 확인하십시오.
3. 버전별 업그레이드 지침을 참고하십시오.
4. GitLab을 해당 지침에 따라 업그레이드하십시오.

필수 업그레이드 중지점

필수 업그레이드 중지점은 이후 버전으로 업그레이드하기 전에 반드시 업그레이드해야 하는 GitLab 버전입니다. 필수 업그레이드 중지점을 통해 필요한 백그라운드 마이그레이션이 완료되도록 합니다.

GitLab 16.x 동안은 필수 업그레이드 중지점을 미리 예약하여 적절한 업그레이드 중지점과 필요한 경우 다운타임을 더 잘 계획할 수 있도록 합니다. 업그레이드를 계획할 때는 이를 고려하십시오.

이전 GitLab 버전

이전 GitLab 버전으로의 업그레이드에 대한 정보는 문서 아카이브를 참조하십시오. 아카이브 문서에는 GitLab의 이전 버전에 대한 버전별 정보가 포함되어 있습니다.

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

에디션 간 업그레이드

GitLab은 커뮤니티 에디션(MIT 라이선스) 및 엔터프라이즈 에디션(커뮤니티 에디션을 기반으로 추가 기능 포함) 두 가지 버전으로 제공됩니다.

GitLab 에디션을 변경하는 데 도움이 되는 몇 가지 가이드가 있습니다.

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

GitLab 설치를 커뮤니티 에디션에서 엔터프라이즈 에디션으로 업그레이드하려면, 설치 방법에 따라 아래 가이드를 따르십시오:

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

기업에서 커뮤니티 에디션으로 변경

기업 에디션 설치를 커뮤니티 에디션으로 다운그레이드하려면 이 가이드를 따라 프로세스를 가능한 한 원활하게 진행할 수 있습니다.

특정 버전에 따른 업그레이드 지침

매월 GitLab의 주요 또는 마이너 버전 및 때로는 패치 릴리스가 릴리스 포스트와 함께 출시됩니다. 어떤 버전을 건너뛰었는지에 관계없이 해당하는 모든 버전의 릴리스 포스트를 읽어야 합니다. 주요 및 마이너 릴리스 포스트의 끝에는 특히 다음과 같은 세 가지 섹션을 찾아야 합니다:

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

이에는 다음이 포함됩니다:

• 업그레이드의 일부로 수행해야 하는 단계. 예를 들어 8.12에서 Elasticsearch 인덱스를 다시 생성해야 합니다. 8.12 이상으로 업그레이드하는 경우 이전 버전의 GitLab에서 필요합니다.
• 우리가 지원하는 소프트웨어 버전의 변경, 예를 들어 GitLab 13에서 IE11 지원 중단.

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

• Linux 패키지 (Omnibus GitLab)
• Helm 차트

GitLab 16

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

GitLab 15

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

GitLab 14

GitLab 14로 업그레이드하기 전에 GitLab 14 변경 사항을 참조하세요.

기타

• PostgreSQL 익스텐션 관리