이 페이지에는 GitLab 18의 마이너 및 패치 버전에 대한 업그레이드 정보가 포함되어 있습니다. 다음에 대한 지침을 검토하세요:

• 설치 유형.
• 현재 버전과 대상 버전 사이의 모든 버전.

Helm 차트 설치에 대한 추가 정보는 Helm 차트 9.0 업그레이드 참고 사항을 참조하세요.

필수 업그레이드 중지점#

인스턴스 관리자에게 예측 가능한 업그레이드 일정을 제공하기 위해, 다음 버전에서 필수 업그레이드 중지점이 발생합니다:

• 18.2
• 18.5
• 18.8
• 18.11

업그레이드 참고 사항 레퍼런스#

다음은 각 마이너 GitLab 버전에 대한 업그레이드 참고 사항의 레퍼런스 목록입니다. 각 항목은 더 자세한 정보가 있는 특정 섹션을 가리킵니다.

(Geo) 또는 (Linux 패키지)와 같이 설치 방법이 표시된 항목은 해당 방법에만 적용됩니다. 다른 모든 항목은 모든 설치 방법에 적용됩니다.

18.11로 업그레이드#

GitLab 18.11로 업그레이드하기 전에 다음을 검토하세요:

• [18.11.0 - 18.11.2] - 파일 스토리지에서 log_error NoMethodError로 인한 Geo blob 동기화 실패 (Geo)
• [18.11.0 - 18.11.1] - 내부 및 공개 프로젝트에서 컨테이너 이미지를 pull하는 CI 잡 토큰 회귀
• [18.11.0] - 18.11로 업그레이드 시 PostgreSQL 17.7 버전 업그레이드 트리거 (Linux 패키지, Docker, Geo)
• [18.11.0] - SLES 12.5 패키지에서 Mattermost 및 Spamcheck 제거 (Linux 패키지)

18.10으로 업그레이드#

GitLab 18.10으로 업그레이드하기 전에 다음을 검토하세요:

• [18.10.0 - 18.10.3] - SLES 12.5 RPM 패키지 설치 실패 (Linux 패키지)
• [18.10.0 - 18.10.5] - 파일 스토리지에서 log_error NoMethodError로 인한 Geo blob 동기화 실패 (Geo)
• [18.10.0 - 18.10.3] - 아웃바운드 필터링 사용 시 Geo 사이트 URL 차단 (Geo)
• [18.10.0 - 18.10.4] - Geo blob 다운로드 실패 (Geo)
• [18.10.0 - 18.10.3] - Geo 보조 사이트 스로틀된 잡이 드레이닝되지 않음 (Geo)
• [18.10.0 - 18.10.3] - Sidekiq 동시성 제한기가 Helm 차트 및 Operator 배포에서 잡 적체를 유발함 (Helm 차트, Operator)

18.9로 업그레이드#

GitLab 18.9로 업그레이드하기 전에 다음을 검토하세요:

• [18.9.1 - 18.9.5] - SLES 12.5 RPM 패키지 설치 실패 (Linux 패키지)
• [18.9.0 - 18.9.5] - 아웃바운드 필터링 사용 시 Geo 사이트 URL 차단 (Geo)
• [18.9.0 - 18.9.5] - Geo 보조 사이트 스로틀된 잡이 드레이닝되지 않음 (Geo)
• [18.9.0 - 18.9.5] - Sidekiq 동시성 제한기가 Helm 차트 및 Operator 배포에서 잡 적체를 유발함 (Helm 차트, Operator)
• [18.9.0] - 18.9로 업그레이드 시 PostgreSQL CheckViolation으로 실패

18.8로 업그레이드#

GitLab 18.8로 업그레이드하기 전에 다음을 검토하세요:

• [18.8.2] - 차단된 사용자의 배포 키 및 개인 액세스 토큰이 무효화됨
• [18.8.0] - 머지 리퀘스트 머지 데이터에 대한 배치된 백그라운드 마이그레이션
• [18.8.0] - ClickHouse 딕셔너리 생성 오류
• [18.8.0] - CI 데이터에 대한 배치된 백그라운드 마이그레이션 재도입

18.7로 업그레이드#

GitLab 18.7로 업그레이드하기 전에 다음을 검토하세요:

• [18.7.2] - 차단된 사용자의 배포 키 및 개인 액세스 토큰이 무효화됨
• [18.7.0] - CI 빌드 메타데이터 마이그레이션
• [18.7.0] - Geo ActionCable 허용 출처 설정 (Geo)

18.6으로 업그레이드#

GitLab 18.6으로 업그레이드하기 전에 다음을 검토하세요:

• [18.6.5] - Geo VerificationStateBackfillWorker 느린 쿼리 수정 (Geo)
• [18.6.4] - 차단된 사용자의 배포 키 및 개인 액세스 토큰이 무효화됨
• [18.6.2] - 커밋 및 파일 API 크기 및 속도 제한
• [18.6.2] - Duo Agent Platform 러너 제한

18.5로 업그레이드#

GitLab 18.5로 업그레이드하기 전에 다음을 검토하세요:

• [18.5.4] - 커밋 및 파일 API 크기 및 속도 제한
• [18.5.0 - 18.5.1] - Geo 로그 커서 마이그레이션 수정 (Geo)
• [18.5.0] - design management designs 백필 완료
• [18.5.0] - NGINX 라우팅 변경으로 인한 404 오류 (Linux 패키지)

18.4로 업그레이드#

GitLab 18.4로 업그레이드하기 전에 다음을 검토하세요:

• [18.4.6] - 커밋 및 파일 API 크기 및 속도 제한
• [18.4.2 - 18.4.3] - 배치된 백그라운드 마이그레이션 nil 오류
• [18.4.1] - 서비스 거부 방지를 위한 JSON 입력 제한
• [18.4.0 - 18.4.3] - Geo 로그 커서 마이그레이션 수정 (Geo)
• [18.4.0 - 18.4.1] - Geo 복제 TypeError (Geo)

18.3으로 업그레이드#

GitLab 18.3으로 업그레이드하기 전에 다음을 검토하세요:

• [18.3.3] - 서비스 거부 방지를 위한 JSON 입력 제한
• [18.3.0] - LdapAddOnSeatSyncWorker가 Duo 시트를 제거함
• [18.3.0] - Geo Rake 체크 수정 (Geo)
• [18.3.0 - 18.3.2] - Geo Pages 파일명 수정 (Geo)

18.2로 업그레이드#

GitLab 18.2로 업그레이드하기 전에 다음을 검토하세요:

• [18.2.7] - 서비스 거부 방지를 위한 JSON 입력 제한
• [18.2.0] - 18.1과 18.2 사이의 무중단 업그레이드 push 오류
• [18.2.0 - 18.2.1] - Geo VerificationStateBackfillService ci_job_artifact_states (Geo)
• [18.2.0 - 18.2.6] - Geo Pages 파일명 수정 (Geo)

18.1로 업그레이드#

GitLab 18.1로 업그레이드하기 전에 다음을 검토하세요:

• [18.1.0] - Elasticsearch strict_dynamic_mapping_exception
• [18.1.0 - 18.1.1] - PostgreSQL ci_job_artifacts 오류
• [18.1.0] - 머지 리퀘스트 almost ready 버그
• [18.1.0] - Geo HTTP 500 프록시 오류 (Geo)
• [18.1.0 - 18.1.3] - Geo VerificationStateBackfillService ci_job_artifact_states (Geo)
• [18.1.0] - Geo Pages 파일명 수정 (Geo)

18.0으로 업그레이드#

GitLab 18.0으로 업그레이드하기 전에 다음을 검토하세요:

• [18.0.0] - PostgreSQL 14 미지원
• [18.0.0] - pg_dump 바이너리 호환성
• [18.0.0] - 17.11에서 무중단 업그레이드 중 파이프라인 실패
• [18.0.0] - git_data_dirs에서 storage로 Gitaly 구성 마이그레이션 (Linux 패키지)
• [18.0.0 - 18.0.1] - Geo CE에서 EE로 되돌리기 마이그레이션 오류 (Geo)
• [18.0.0 - 18.0.2] - Geo HTTP 500 프록시 오류 (Geo)
• [18.0.0 - 18.0.5] - Geo VerificationStateBackfillService ci_job_artifact_states (Geo)
• [18.0.0] - Docker 설치에서 PRNG가 시드되지 않음 오류 (Docker)
• [17.11.0] - Bitnami PostgreSQL 및 Redis 이미지 지원 중단 (Helm 차트)

업그레이드 참고 사항#

GitLab 18에 대한 구체적인 업그레이드 참고 사항입니다.

파일 스토리지에서 log_error NoMethodError로 인한 Geo blob 동기화 실패 {#geo-blob-sync-failures-with-log_error-nomethoderror-on-file-storage}#

• 영향 대상: Geo (파일 스토리지만 해당)

• 영향받는 버전:

파일 스토리지(오브젝트 스토리지가 아닌)에 blob을 저장하는 Geo 보조 사이트에서 blob 복제(Pipeline Artifacts, LFS 객체, 업로드, 잡 아티팩트 등)가 오해를 불러일으키는 오류와 함께 실패할 수 있습니다:

Error while attempting to sync: undefined method `log_error' for an instance of Gitlab::Geo::Replication::BlobDownloader

자세한 내용은 이슈 598565를 참조하세요.

내부 및 공개 프로젝트에서 컨테이너 이미지를 pull하는 CI 잡 토큰 회귀 {#ci-job-token-regression-pulling-container-images-from-internal-and-public-projects}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전:

GitLab 18.11.0의 회귀로 인해 CI 잡이 CI_JOB_TOKEN을 사용하여 내부 또는 공개 프로젝트에서 컨테이너 이미지를 pull할 수 없습니다. 영향받는 파이프라인은 denied: requested access to the resource is denied와 함께 실패합니다. 수정 사항이 18-11-stable-ee에 백포트되었지만 18.11.1 태그가 생성된 후 반영되었으므로, 18.11.0과 18.11.1 모두 영향을 받습니다.

이미 업그레이드한 운영자를 위한 해결 방법:

• 각 소비하는 프로젝트를 소스 프로젝트의 CI 잡 토큰 허용 목록에 추가합니다. CI/CD 잡 토큰 보안을 참조하세요.
• CI_JOB_TOKEN 대신 개인, 그룹 또는 프로젝트 액세스 토큰으로 컨테이너 pull을 인증합니다.
• 백포트 커밋 e3c0f308을 GitLab 인스턴스에 적용합니다.

자세한 내용은 이슈 597223을 참조하세요.

SLES 12.5 RPM 패키지 설치 실패 {#sles-125-rpm-package-installation-failure}#

• 영향 대상: Linux 패키지

• 영향받는 버전:

SLES 12.5용 GitLab Linux 패키지는 rpm 또는 zypper 명령을 사용할 때 error: install failed와 함께 설치에 실패합니다. 근본 원인은 SLES 12 SP5에 포함된 RPM 4.11.2 버전의 16 MiB RPM 헤더 데이터 크기 제한(HEADER_DATA_MAX)입니다. GitLab 패키지의 파일 수가 증가함에 따라 직렬화된 RPM 헤더가 이 제한을 초과하여 설치 중 RPM 데이터베이스 트랜잭션이 자동으로 실패했습니다.

이 문제는 Linux 패키지의 파일 수를 줄여 특정 패치 릴리스에서 해결되었습니다(머지 리퀘스트 9215 참조). 그러나 파일 수가 다시 증가하면 후속 패치 릴리스에서 회귀가 발생할 수 있습니다. SLES 12.5에 GitLab을 설치하려면 위에 나열된 설치 가능한 패치 수준만 사용하세요.

SUSE 배포판은 GitLab 18.9에서 지원 중단되었으며 GitLab 19.0에서 제거 예정입니다. 지원되는 운영 체제로의 마이그레이션을 고려하세요.

자세한 내용은 이슈 9647을 참조하세요.

SLES 12.5 패키지에서 Mattermost 및 Spamcheck 제거 {#mattermost-and-spamcheck-removed-from-sles-125-packages}#

• 영향 대상: Linux 패키지

• 영향받는 버전: 18.11.0 이상

RPM 패키지 크기 제한으로 인해 Mattermost와 Spamcheck가 SLES 12.5 Linux 패키지에서 제거되었습니다.

SUSE 배포판은 GitLab 18.9에서 지원 중단되었으며 GitLab 19.0에서 제거 예정이며, Mattermost와 Spamcheck 모두 GitLab 19.0에서 모든 배포판에서 제거 예정입니다.

SLES 12.5에서 Mattermost에 의존하는 경우 Mattermost를 독립형 배포로 마이그레이션할 수 있습니다. SLES 12.5에서 Spamcheck를 사용하는 경우 Docker를 사용하여 배포할 수 있습니다.

Geo 보조 사이트 스로틀된 잡이 드레이닝되지 않음 {#geo-secondary-throttled-jobs-not-draining}#

• 영향 대상: Geo

• 영향받는 버전:

Geo 보조 사이트가 ConcurrencyLimit::ResumeWorker를 비활성화하여 스로틀된 Geo::EventWorker 및 Geo::SyncWorker 잡이 드레이닝 없이 Redis에 누적되었습니다. 이로 인해 Geo 복제가 중단되고 Redis 메모리 사용량이 증가할 수 있습니다.

자세한 내용은 이슈 595824를 참조하세요.

아웃바운드 필터링 사용 시 Geo 사이트 URL 차단 {#geo-site-url-blocked-when-using-outbound-filtering}#

• 영향 대상: Geo

• 영향받는 버전:

아웃바운드 요청 필터링이 활성화된 경우 Geo 사이트 URL이 잘못 차단됩니다. 이로 인해 Url is blocked: Requests to hosts and IP addresses not on the Allow List are denied와 같은 메시지로 Geo 사이트를 저장할 때 유효성 검사 오류가 발생합니다.

이 문제는 아웃바운드 필터링이 구성될 때 Geo 사이트 URL이 아웃바운드 로컬 요청 허용 목록에 자동으로 추가되지 않아 발생합니다.

자세한 내용은 이슈 544821을 참조하세요.

Geo blob 다운로드 실패 {#geo-blob-download-failures}#

• 영향 대상: Geo

• 영향받는 버전:

모든 Geo blob 유형(업로드, LFS 객체, 잡 아티팩트 등)이 보조 사이트에서 지속적으로 동기화에 실패할 수 있습니다. 일시적인 네트워크 오류와 달리 이 실패는 모든 blob 레코드에 영향을 미치며 재시도 시 복구되지 않습니다. 영향받는 보조 사이트는 blob이 "failed" 상태로 표시되고, Sidekiq 로그에 segfault, HPE_USER Span callback error in on_header_field 오류 또는 예상치 못한 HTTP 상태 코드(예: status_code: 32 또는 status_code: 34)가 포함될 수 있습니다.

근본 원인은 rugged 1.9.0(GitLab 18.10에서 업그레이드)과 llhttp-ffi gem 간의 심볼 충돌입니다. rugged.so의 정적으로 연결된 llhttp 심볼이 llhttp-ffi 콜백을 재정의하여 HTTP 응답 파싱을 손상시킵니다. 자세한 내용은 이슈 598564를 참조하세요.

GitLab 18.10.5에서 rugged가 충돌하는 심볼을 포함하지 않는 1.7.2로 다운그레이드됩니다. 업그레이드 후 별도의 조치가 필요하지 않습니다.

GitLab 18.10.4를 위한 기능 플래그 해결 방법#

GitLab 18.10.4에 있고 GitLab 18.10.5로 업그레이드할 수 없는 경우 geo_blob_download_with_gitlab_http 기능 플래그를 활성화하세요. 이 플래그는 blob 다운로드가 FFI 의존 http gem 대신 Gitlab::HTTP(Net::HTTP)를 사용하도록 전환합니다:

• 기능 플래그를 활성화합니다:

  sudo gitlab-rails console
  Feature.enable(:geo_blob_download_with_gitlab_http)
  exit
  

• Sidekiq를 재시작합니다:

  sudo gitlab-ctl restart sidekiq
  

자세한 내용은 이슈 595139를 참조하세요.

18.9로 업그레이드 시 PostgreSQL CheckViolation으로 실패 {#upgrade-to-189-fails-with-postgresql-checkviolation}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.9.0, 18.9.1

Self-managed GitLab 인스턴스를 GitLab 18.9.0 또는 18.9.1로 업그레이드할 때 다음과 같은 데이터베이스 마이그레이션 중에 업그레이드가 실패합니다:

PG::CheckViolation: ERROR: check constraint "check_xxxxxxxx" of relation "tablename" is violated by some row

이 문제는 GitLab 18.10에서 수정된 버그로 인해 발생했습니다(머지 리퀘스트 224446 참조). 수정 사항이 백포트되어 다음 GitLab 18.9 패치 릴리스에 포함될 예정입니다(머지 리퀘스트 225026 참조).

그러나 이 버그는 단일 레코드 버그로 인해 배치된 백그라운드 마이그레이션이 조용히 건너뛰어질 수 있습니다. v18.8로 업그레이드할 때 단일 레코드가 있는 테이블을 대상으로 하는 배치된 백그라운드 마이그레이션이 실행되지 않고 잘못되게 finished로 표시되었습니다. 이로 인해 데이터가 백필되지 않아 self-managed 인스턴스에서 업그레이드 실패가 발생했습니다.

제안된 수정 사항(머지 리퀘스트 225461 참조)은 min_value = max_value 또는 min_cursor = max_cursor인 18.5에서 18.8 사이의 queued_migration_version을 가진 마이그레이션에만 적용하여 영향을 받은 배치된 백그라운드 마이그레이션을 finished/finalized에서 paused로 재설정하여 스케줄러가 다시 실행합니다.

두 가지 옵션이 있습니다:

• 지금 해결 방법을 적용하여 업그레이드를 즉시 완료합니다.
• 완전한 수정을 기다려 릴리스가 포함된 후 업그레이드합니다.

다음 기술 자료 문서는 5가지 알려진 증상에 대한 해결 방법을 설명합니다:

• PG::CheckViolation: ERROR: check constraint "check_96233d37c0" of relation "pool_repositories" is violated by some row
• PG::CheckViolation: ERROR: check constraint "check_f6590fe2c1" of relation "gpg_key_subkeys" is violated by some row
• PG::CheckViolation: ERROR: check constraint "check_17a3a18e31" of relation "user_agent_details" is violated by some row
• PG::CheckViolation: ERROR: check constraint "check_ddd6f289f4" of relation "commit_user_mentions" is violated by some row
• PG::CheckViolation: ERROR: check constraint "check_e69372e45f" of relation "suggestions" is violated by some row

차단된 사용자의 배포 키 및 개인 액세스 토큰이 무효화됨 {#deploy-keys-and-personal-access-tokens-for-blocked-users-are-invalidated}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전:

GitLab 18.8.2, 18.7.2, 18.6.4는 이제 차단된 사용자와 관련된 배포 키를 사용하는 API 요청을 거부합니다. 차단된 사용자와 관련된 배포 키가 있는 경우, 위에 언급된 버전으로 업그레이드한 후에는 더 이상 작동하지 않습니다. 이는 차단된 사용자가 키와 토큰을 통해 GitLab 리소스에 접근하지 못하도록 하는 보안 수정입니다.

다음을 수행해야 합니다:

1. 차단된 사용자가 소유한 배포 키 또는 PAT를 식별합니다.
2. 청구 가능한 사용자에게 재할당하거나, 삭제하고 청구 가능한 사용자나 서비스 계정으로 새 키/토큰을 생성합니다.

다음 쿼리를 사용하여 차단된 계정과 관련된 모든 배포 키 중 지난 365일 동안 최소 한 번 사용된 것을 식별할 수 있습니다:

SELECT
  k.id,
  k.user_id,
  u.username,
  u.state as user_state,
  k.title,
  k.fingerprint,
  k.fingerprint_sha256,
  k.usage_type,
  k.last_used_at,
  k.created_at,
  k.updated_at
FROM keys k
INNER JOIN users u ON k.user_id = u.id
WHERE u.state IN ('blocked', 'ldap_blocked', 'blocked_pending_approval', 'banned')
  AND k.type = 'DeployKey'
  AND k.last_used_at >= NOW() - INTERVAL '365 days'
ORDER BY u.state, u.username, k.last_used_at DESC;

ClickHouse 딕셔너리 생성 오류 {#clickhouse-dictionary-creation-error}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.8.0

ClickHouse 통합이 활성화된 GitLab Self-Managed 고객은 누락된 권한(DB::Exception: gitlab: Not enough privileges)으로 인해 업그레이드 프로세스 중에 ClickHouse 데이터베이스 마이그레이션 오류가 발생할 수 있습니다. 이 오류를 해결하려면 데이터베이스 딕셔너리 읽기 지원 문제 해결 문서를 참조하세요.

CI 데이터에 대한 배치된 백그라운드 마이그레이션 재도입 {#batched-background-migration-for-ci-data-reintroduced}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.8.0

CI 빌드 메타데이터 마이그레이션에서 도입된 배치된 백그라운드 마이그레이션은 데이터 구조의 엣지 케이스를 처리하고 완료를 보장하기 위해 재도입되어야 했습니다.

CI 빌드 메타데이터 마이그레이션 {#ci-builds-metadata-migration}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.7.0

배포 후 마이그레이션은 CI 빌드 메타데이터를 새로운 최적화된 테이블(p_ci_job_definitions)로 복사하기 위한 배치된 백그라운드 마이그레이션을 예약합니다. 이 마이그레이션은 궁극적으로 CI 데이터베이스 크기를 줄이기 위한 이니셔티브의 일부입니다(에픽 13886 참조). 수백만 개의 잡이 있는 인스턴스에서 마이그레이션 속도를 높이려면 마이그레이션되는 데이터를 선택할 수 있습니다.

Geo ActionCable 허용 출처 설정 {#geo-actioncable-allowed-origins-setting}#

• 영향 대상: Geo

• 영향받는 버전: 18.7.0

ActionCable 웹소켓 요청에 대한 허용 출처를 구성하는 새로운 action_cable_allowed_origins 설정이 추가되었습니다. 적절한 교차 사이트 WebSocket 연결을 보장하기 위해 기본 사이트를 구성할 때 허용 URL을 지정합니다:

• Linux 패키지를 위한 Geo 문서
• Helm 차트를 위한 Geo 문서

Geo VerificationStateBackfillWorker 느린 쿼리 수정 {#geo-verificationstatebackfillworker-slow-queries-fix}#

• 영향 대상: Geo

• 영향받는 버전: 18.6.5

Geo::VerificationStateBackfillWorker가 merge_request_diff_details 테이블에 대해 큰 느린 쿼리를 생성하는 Geo 이슈 587407이 수정되었습니다.

커밋 및 파일 API 크기 및 속도 제한 {#commits-and-files-api-size-and-rate-limits}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전:

GitLab 18.6.2, 18.5.4, 18.4.6은 다음 엔드포인트에 대한 요청에 크기 및 속도 제한을 도입했습니다:

• POST /projects/:id/repository/commits - 커밋 생성
• POST /projects/:id/repository/files/:file_path - 저장소에 파일 생성
• PUT /projects/:id/repository/files/:file_path - 저장소의 파일 업데이트

GitLab은 크기 제한을 초과하는 요청에 413 Entity Too large 상태로, 속도 제한을 초과하는 요청에 429 Too Many Requests 상태로 응답합니다. 자세한 내용은 커밋 및 파일 API 제한을 참조하세요.

Duo Agent Platform 러너 제한 {#duo-agent-platform-runner-restrictions}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.6.2

Duo Agent Platform과 함께 사용할 수 있는 러너에 관한 몇 가지 러너 제한이 도입되었습니다.

Geo 로그 커서 마이그레이션 수정 {#geo-log-cursor-migration-fix}#

• 영향 대상: Geo

• 영향받는 버전:

보조 사이트에서 Geo 로그 커서 시작을 방지하는 누락된 Geo 마이그레이션이 수정되었습니다.

design management designs 백필 완료 {#finalize-design-management-designs-backfill}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.5.0

배포 후 마이그레이션 20250922202128_finalize_correct_design_management_designs_backfill은 18.4에서 예약된 배치된 백그라운드 마이그레이션을 완료합니다. 업그레이드 경로에서 18.4를 건너뛴 경우 배포 후 마이그레이션이 실행될 때 마이그레이션이 완전히 실행됩니다. 실행 시간은 design_management_designs 테이블의 크기에 비례합니다. 대부분의 인스턴스에서 마이그레이션은 2분을 초과하지 않아야 하지만, 일부 대형 인스턴스에서는 최대 10분이 걸릴 수 있습니다. 마이그레이션 프로세스를 중단하지 말고 기다려 주세요.

NGINX 라우팅 변경으로 인한 404 오류 {#nginx-routing-changes-cause-404-errors}#

• 영향 대상: Linux 패키지

• 영향받는 버전: 18.5.0

GitLab 18.5.0에서 도입된 NGINX 라우팅 변경은 localhost 또는 대체 도메인 이름과 같이 일치하지 않는 호스트명을 사용할 때 서비스에 접근할 수 없게 될 수 있습니다. 이 문제는 다음을 유발합니다:

• /-/health와 같은 상태 확인 엔드포인트가 적절한 응답 대신 404 오류를 반환합니다.
• 구성된 FQDN 이외의 호스트명으로 접근할 때 GitLab 웹 인터페이스에서 404 오류 페이지를 표시합니다.
• GitLab Pages가 다른 서비스를 위한 트래픽을 받을 수 있습니다.
• 이전에 작동했던 대체 호스트명을 사용하는 모든 요청에 문제가 발생합니다.

이 문제는 Linux 패키지의 머지 리퀘스트 8805에서 해결되었으며, 수정 사항은 GitLab 18.5.2 및 18.6.0에서 사용 가능합니다.

clone, push, pull과 같은 Git 작업은 이 문제의 영향을 받지 않습니다.

배치된 백그라운드 마이그레이션 nil 오류 {#batched-background-migration-nil-error}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.4.2, 18.4.3

18.4.2 또는 18.4.3으로 업그레이드하면 다음 배치된 백그라운드 마이그레이션에서 no implicit conversion of nil into String 오류가 발생하여 실패할 수 있습니다:

• FixIncompleteInstanceExternalAuditDestinations
• FinalizeAuditEventDestinationMigrations

이 문제를 해결하려면 최신 패치 릴리스로 업그레이드하거나 이슈 578938의 해결 방법을 사용하세요.

Geo 복제 TypeError {#geo-replication-typeerror}#

• 영향 대상: Geo

• 영향받는 버전:

Geo 보조 사이트에서 버그로 인해 복제 이벤트가 no implicit conversion of String into Array (TypeError) 오류 메시지로 실패합니다. 재검증과 같은 중복성은 궁극적인 일관성을 보장하지만, RPO가 크게 증가합니다.

서비스 거부 방지를 위한 JSON 입력 제한 {#json-input-limits-for-denial-of-service-prevention}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전:

GitLab 18.4.1, 18.3.3, 18.2.7은 서비스 거부 공격을 방지하기 위해 JSON 입력에 대한 제한을 도입했습니다. GitLab은 이러한 제한을 초과하는 HTTP 요청에 400 Bad Request 상태로 응답합니다. 자세한 내용은 HTTP 요청 제한을 참조하세요.

LdapAddOnSeatSyncWorker가 Duo 시트를 제거함 {#ldapaddonseatsyncworker-removes-duo-seats}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.3.0

새로운 워커 LdapAddOnSeatSyncWorker가 도입되어 LDAP가 활성화된 경우 매일 밤 GitLab Duo 시트에서 모든 사용자를 의도치 않게 제거할 수 있습니다. 이 문제는 GitLab 18.4.0 및 18.3.2에서 수정되었습니다. 자세한 내용은 이슈 565064를 참조하세요.

Geo Rake 체크 수정 {#geo-rake-check-fix}#

• 영향 대상: Geo

• 영향받는 버전: 18.3.0

Geo 보조 사이트를 설치할 때 rake gitlab:geo:check가 실패를 잘못 보고하는 문제가 18.3.0에서 수정되었습니다.

Geo Pages 파일명 수정 {#geo-pages-filename-fix}#

• 영향 대상: Geo

• 영향받는 버전:

GitLab 18.3.3 및 18.2.7 이상에는 긴 파일명이 있는 Pages 배포에서 Geo 검증이 실패할 수 있는 이슈 559196에 대한 수정이 포함되어 있습니다. 이 수정은 복제 및 검증 중 일관성을 유지하기 위해 Geo 보조 사이트에서 파일명 트리밍을 방지합니다.

18.1과 18.2 사이의 무중단 업그레이드 push 오류 {#zero-downtime-upgrade-push-errors-between-181-and-182}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.2.0

18.1.x와 18.2.x 사이의 업그레이드는 업그레이드 중에 기존 프로젝트로의 코드 push에 오류가 발생하는 알려진 이슈 567543의 영향을 받습니다. 버전 18.1.x와 18.2.x 사이의 업그레이드 중 다운타임이 없도록 하려면 수정 사항이 포함된 버전 18.2.6으로 직접 업그레이드하세요.

Geo VerificationStateBackfillService ci_job_artifact_states {#geo-verificationstatebackfillservice-ci_job_artifact_states}#

• 영향 대상: Geo

• 영향받는 버전:

영향받는 버전은 ci_job_artifact_states의 기본 키 변경으로 인해 VerificationStateBackfillService가 실행될 때 발생하는 알려진 문제가 있습니다. 해결하려면 수정된 패치 수준 릴리스로 업그레이드하세요.

Elasticsearch strict_dynamic_mapping_exception {#elasticsearch-strict_dynamic_mapping_exception}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.1.0

Elasticsearch 버전 7의 경우 strict_dynamic_mapping_exception 오류로 인해 Elasticsearch 인덱싱이 실패할 수 있습니다. 해결 방법은 이슈 566413의 "가능한 수정 방법" 섹션을 참조하세요.

PostgreSQL ci_job_artifacts 오류 {#postgresql-ci_job_artifacts-error}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.1.0, 18.1.1

GitLab 버전 18.1.0 및 18.1.1은 ERROR: relation "ci_job_artifacts" does not exist at ...와 같은 오류를 PostgreSQL 로그에 표시합니다. 로그의 이러한 오류는 안전하게 무시할 수 있지만 Geo 사이트를 포함한 모니터링 알림을 트리거할 수 있습니다. 이 문제를 해결하려면 GitLab 18.1.2 이상으로 업데이트하세요.

머지 리퀘스트 almost ready 버그 {#merge-request-almost-ready-bug}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.1.0

일부 사용자의 커밋이 있는 머지 리퀘스트가 진행되지 않고 계속 Your merge request is almost ready를 표시할 수 있습니다. 이슈 554613을 참조하세요. 또한 sidekiq/current 로그에서 merge_request_diff_commit.rb에 대한 undefined method 'id' for nil:NilClass 오류가 표시됩니다. 이를 수정하려면:

1. 데이터베이스 콘솔을 시작합니다.

2. 다음 명령을 실행합니다:

   REINDEX TABLE CONCURRENTLY public.merge_request_diff_commit_users;
   

3. 영향을 받은 머지 리퀘스트를 닫고 다시 엽니다.

Geo HTTP 500 프록시 오류 {#geo-http-500-proxy-errors}#

• 영향 대상: Geo

• 영향받는 버전:

위 표의 GitLab 버전은 Geo 보조 사이트에서 프록시된 Git 작업이 HTTP 500 오류로 실패하는 알려진 문제가 있습니다. 해결하려면 수정된 패치 수준 릴리스로 업그레이드하세요.

PostgreSQL 14 미지원 {#postgresql-14-not-supported}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.0.0

GitLab 18부터 PostgreSQL 14는 지원되지 않습니다. GitLab 18.0 이상으로 업그레이드하기 전에 PostgreSQL을 버전 16.5 이상으로 업그레이드하세요. 자세한 내용은 설치 요구 사항을 참조하세요.

pg_dump 바이너리 호환성 {#pg_dump-binary-compatibility}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.0.0

GitLab은 pg_dump 바이너리를 번들로 제공합니다. 외부 PostgreSQL 서버를 사용하는 경우, GitLab 데이터베이스 백업 생성 및 복원 모두에서 pg_dump 클라이언트 버전이 PostgreSQL 서버와 호환되는지 확인하세요.

Bitnami PostgreSQL 및 Redis 이미지 지원 중단 {#bitnami-postgresql-and-redis-image-deprecation}#

• 영향 대상: Helm 차트

• 영향받는 버전: 17.11.0 이하

2025년 9월 29일부터 Bitnami는 태그된 PostgreSQL 및 Redis 이미지 제공을 중단합니다. 번들 Redis 또는 Postgres와 함께 GitLab 차트를 사용하여 GitLab 17.11 이하를 배포하는 경우, 예상치 못한 다운타임을 방지하기 위해 레거시 저장소를 사용하도록 수동으로 값을 업데이트해야 합니다. 자세한 내용은 이슈 6089를 참조하세요.

17.11에서 무중단 업그레이드 중 파이프라인 실패 {#pipeline-failures-during-zero-downtime-upgrades-from-1711}#

• 영향 대상: 모든 설치 방법

• 영향받는 버전: 18.0.0

기능 플래그 ci_only_one_persistent_ref_creation은 Rails가 업그레이드되었지만 Sidekiq가 버전 17.11에 남아 있는 경우 무중단 업그레이드 중에 파이프라인 실패를 유발합니다(이슈 558808의 세부 정보 참조).

예방 조치: Rails 콘솔을 열고 업그레이드하기 전에 기능 플래그를 활성화합니다:

$ sudo gitlab-rails console
Feature.enable(:ci_only_one_persistent_ref_creation)

이미 영향을 받은 경우: 다음 명령을 실행하고 실패한 파이프라인을 재시도합니다:

$ sudo gitlab-rails console
Rails.cache.delete_matched("pipeline:*:create_persistent_ref_service")

git_data_dirs에서 storage로 Gitaly 구성 마이그레이션 {#migrate-gitaly-configuration-from-git_data_dirs-to-storage}#

• 영향 대상: Linux 패키지

• 영향받는 버전: 18.0.0

GitLab 18.0 이상에서는 git_data_dirs 설정을 사용하여 Gitaly 저장 위치를 구성할 수 없습니다.

아직 git_data_dirs를 사용하고 있다면 GitLab 18.0으로 업그레이드하기 전에 Gitaly 구성을 마이그레이션해야 합니다.

Geo CE에서 EE로 되돌리기 마이그레이션 오류 {#geo-ce-to-ee-revert-migration-errors}#

• 영향 대상: Geo

• 영향받는 버전: 18.0.0

GitLab Enterprise Edition을 배포했다가 GitLab Community Edition으로 되돌린 경우, 데이터베이스 스키마가 GitLab 애플리케이션이 기대하는 스키마와 다를 수 있어 마이그레이션 오류가 발생할 수 있습니다. 해당 버전의 마이그레이션이 해당 열의 기본값을 변경하기 때문에 18.0.0으로 업그레이드 시 네 가지 특정 오류가 발생할 수 있습니다.

오류는 다음과 같습니다:

• No such column: geo_nodes.verification_max_capacity
• No such column: geo_nodes.minimum_reverification_interval
• No such column: geo_nodes.repos_max_capacity
• No such column: geo_nodes.container_repositories_max_capacity

이 마이그레이션은 GitLab 18.0.2에서 해당 열이 없으면 추가하도록 패치되었습니다. 이슈 #543146을 참조하세요.

영향을 받는 릴리스:

Docker 설치에서 PRNG가 시드되지 않음 오류 {#prng-is-not-seeded-error-on-docker-installations}#

• 영향 대상: Docker

• 영향받는 버전: 18.0.0

FIPS가 활성화된 호스트에서 Docker 설치로 GitLab을 실행하는 경우, SSH 키 생성 또는 OpenSSH 서버(sshd) 시작이 다음 오류 메시지로 실패하는 것을 볼 수 있습니다:

PRNG is not seeded

GitLab 18.0은 기본 이미지를 Ubuntu 22.04에서 24.04로 업데이트했습니다. 이 오류는 Ubuntu 24.04가 더 이상 FIPS 호스트가 비-FIPS OpenSSL 제공자를 사용하는 것을 허용하지 않기 때문에 발생합니다.

이 문제를 해결하려면 몇 가지 옵션이 있습니다:

• 호스트 시스템에서 FIPS를 비활성화합니다.
• GitLab Docker 컨테이너에서 FIPS 기반 커널의 자동 감지를 비활성화합니다. GitLab 18.0.2 이상에서 OPENSSL_FORCE_FIPS_MODE=0 환경 변수를 설정하여 수행할 수 있습니다.
• GitLab Docker 이미지를 사용하는 대신 호스트에 네이티브 FIPS 패키지를 설치합니다.

FIPS 요구 사항을 충족하려면 마지막 옵션을 권장합니다. 레거시 설치의 경우 처음 두 옵션을 임시 방편으로 사용할 수 있습니다.

GitLab 18.11의 PostgreSQL 버전 17.7 업그레이드 {#postgresql-version-177-upgrade-on-gitlab-1811}#

• 영향 대상: Linux 패키지, Docker, Geo

• 영향받는 버전: 18.11.0

GitLab 18.11로 업그레이드하면 단일 노드 Linux 패키지 설치에 대해 PostgreSQL 17.7로의 자동 업그레이드가 트리거됩니다.

Sidekiq 동시성 제한기가 Helm 차트 및 Operator 배포에서 잡 적체를 유발함 {#sidekiq-concurrency-limiter-causes-job-backlogs-on-helm-chart-and-operator-deployments}#

• 영향 대상: Helm 차트, Operator

• 영향받는 버전:

GitLab 18.9에서 GitLab Helm 차트가 기본적으로 GITLAB_SIDEKIQ_MAX_REPLICAS를 설정하기 시작했습니다(charts/GitLab 머지 리퀘스트 4348). KEDA 기반 자동 확장을 사용하지 않는 GitLab Self-Managed 및 GitLab Dedicated 환경에서 이로 인해 Sidekiq 동시성 제한기가 예상치 않게 활성화되어 Redis 기반 스로틀된 큐에 잡을 지연시킵니다.

이로 인해 다음이 발생할 수 있습니다:

• Sidekiq 잡 적체.
• Redis 메모리 증가.
• 지연된 잡 실행.
• WebHookWorker, AuditEvents::AuditEventStreamingWorker, Geo 복제 워커(Geo::EventWorker, Geo::SyncWorker)와 같은 워커에 영향.

영향을 받는 경우 수정된 버전으로 업그레이드할 때까지 다음 임시 완화 방법 중 하나를 사용할 수 있습니다:

• 특정 워커의 동시성 제한기 비활성화: 기능 플래그를 활성화하여 Sidekiq pod에서 exec로 Rails 콘솔을 엽니다:

  kubectl exec -it <sidekiq-pod-name> -- gitlab-rails console
  

  그런 다음 영향받는 워커에 대해 플래그를 활성화합니다:

  Feature.enable(:"disable_sidekiq_concurrency_limit_middleware_")
  

  를 영향받는 워커 이름(예: WebHookWorker)으로 바꿉니다.

• 모든 기본 동시성 제한 비활성화: Sidekiq pod 환경 구성에서 GITLAB_SIDEKIQ_MAX_REPLICAS=0을 설정합니다. 이렇게 하면 기본 동시성 제한 계산이 완전히 비활성화됩니다.

기본 동시성 제한 계산을 기능 플래그 뒤에 두는 수정 사항이 머지 리퀘스트 230713에 머지되어 18.10.4(머지 리퀘스트 231085)와 18.9.6(머지 리퀘스트 231297)으로 백포트되었습니다.

CI 빌드 메타데이터 마이그레이션 세부 사항#

마이그레이션되지 않은 데이터는 향후 릴리스에서 제거됩니다(에픽 18271 참조).

마이그레이션 기간은 인스턴스의 총 CI 잡 수에 비례합니다. 잡은 최신 데이터를 우선시하기 위해 최신 파티션에서 이전 파티션 순서로 처리됩니다.

업그레이드 전에 대형 프로젝트에서 자동 파이프라인 정리를 활성화하여 이전 파이프라인을 삭제함으로써 마이그레이션할 잡 수를 줄일 수 있습니다.

마이그레이션은 두 가지 유형의 데이터를 복사합니다:

• 잡 처리 데이터: UI나 API가 아닌 잡을 실행할 때 러너에만 필요한 .gitlab-ci.yml의 잡 실행 구성(script, variables 등).
• 사용자에게 보이는 잡 데이터: 모든 잡 데이터 중에서 이 마이그레이션은 잡 타임아웃 값, 잡 종료 코드 값, 노출된 아티팩트, 환경 연결에만 영향을 미칩니다.

대규모 CI 데이터셋이 있는 GitLab Self-Managed 및 GitLab Dedicated 인스턴스의 경우, 마이그레이션할 데이터 범위를 줄여 마이그레이션 속도를 높일 수 있습니다. 범위를 제어하려면 아래에 정의된 설정을 사용합니다.

잡 처리 데이터의 범위 제어#

기본적으로 마이그레이션은 모든 기존 잡의 처리 데이터를 복사합니다. 아래에 설명된 설정 중 하나를 사용하여 범위를 줄일 수 있습니다.

설정의 값은 얼마만큼의 잡 처리 데이터를 유지할지 제어합니다. 예를 들어, 지난 6개월 동안 생성된 잡만 실행될 것으로 예상하는 경우 6mo로 설정합니다 (재시도, 수동 잡 실행, 환경 자동 중지를 통해).

GitLab은 우선순위 순서로 설정을 찾습니다:

1. 파이프라인 아카이브 설정(권장 모범 사례). 아카이브된 파이프라인은 잡을 수동으로 재시도하거나 다시 실행할 수 없다는 신호입니다. 이 설정이 활성화된 경우 아카이브된 잡에 대한 처리 데이터를 마이그레이션할 필요가 없습니다.

   [!note] 파이프라인 아카이브 범위가 나중에 확장되면 처리 데이터가 없는 잡은 실행 불가능한 상태로 남습니다.

2. GITLAB_DB_CI_JOBS_PROCESSING_DATA_CUTOFF 환경 변수, 파이프라인 아카이브가 구성되지 않았거나 이 마이그레이션을 위해 재정의해야 하는 경우. 1y(1년), 6mo(6개월), 90d(90일)와 같은 기간 문자열을 허용합니다.

3. GITLAB_DB_CI_JOBS_MIGRATION_CUTOFF 환경 변수, 위의 설정 중 어느 것도 설정되지 않은 경우. 1y(1년), 6mo(6개월), 90d(90일)와 같은 기간 문자열을 허용합니다. 사용자에게 보이는 잡 데이터의 범위 제어를 참조하세요.

4. 구성이 없으면 모든 데이터가 복사됩니다.

사용자에게 보이는 잡 데이터의 범위 제어#

환경 변수 GITLAB_DB_CI_JOBS_MIGRATION_CUTOFF는 어떤 잡의 보이는 데이터가 마이그레이션될지 제어합니다.

예를 들어, GITLAB_DB_CI_JOBS_MIGRATION_CUTOFF=1y는 가장 최근 1년 동안의 잡에 대한 영향을 받은 보이는 데이터(타임아웃 값, 환경, 종료 코드, 노출된 아티팩트의 메타데이터)를 복사합니다.

기본적으로 마감일이 없으며 모든 잡에 대한 데이터가 마이그레이션됩니다.

마이그레이션 영향 추정#

참고로, GitLab.com에서는 약 2개월 동안 4억 개의 행을 마이그레이션할 것으로 예상합니다.

인스턴스에 대한 마이그레이션 영향을 추정하려면 PostgreSQL 콘솔에서 다음 쿼리를 실행할 수 있습니다:

SELECT n.nspname AS schema_name, c.relname AS partition_name,
       pg_size_pretty(pg_total_relation_size(c.oid)) AS total_size
FROM pg_inherits i
JOIN pg_class c ON c.oid = i.inhrelid
JOIN pg_namespace n ON n.oid = c.relnamespace
JOIN pg_class p ON p.oid = i.inhparent
WHERE p.relname = 'p_ci_builds_metadata'
ORDER BY pg_total_relation_size(c.oid) DESC;

SELECT SUM(c.reltuples)::bigint AS estimated_jobs_count
FROM pg_class c
JOIN pg_inherits i ON c.oid = i.inhrelid
WHERE i.inhparent = 'p_ci_builds'::regclass;

SELECT COUNT(*) FROM p_ci_builds WHERE created_at >= now() - '1 year'::interval;

counts = []
CommitStatus.each_batch(of: 25000) do |batch|
  counts << batch.where(created_at: 1.year.ago...).count
end
counts.sum

머지 리퀘스트 머지 데이터 마이그레이션 세부 사항#

마이그레이션되는 데이터#

마이그레이션은 merge_requests에서 merge_requests_merge_data로 다음 열을 복사합니다:

• merge_commit_sha
• merged_commit_sha
• merge_ref_sha
• squash_commit_sha
• in_progress_merge_commit_sha
• merge_status
• auto_merge_enabled
• squash
• merge_user_id
• merge_params
• merge_error
• merge_jid

마이그레이션은 merge_requests 테이블을 처리하여 merge_requests_merge_data에 해당 항목이 없는 머지 리퀘스트에 대한 데이터만 복사합니다.

GitLab 18.7부터 새로운 머지 리퀘스트는 애플리케이션 레벨의 듀얼 쓰기 메커니즘을 통해 두 테이블 모두에 데이터를 기록합니다(이슈 참조). 이 마이그레이션은 듀얼 쓰기가 구현된 후 생성되거나 수정되지 않은 기존 데이터만 복사합니다.

이 마이그레이션 중에 merge_requests 테이블에서 데이터가 삭제되지 않습니다.

마이그레이션은 GitLab 18.9에서 완료될 예정입니다. 자세한 내용은 이슈를 참조하세요.

마이그레이션 기간 추정#

마이그레이션 기간은 인스턴스의 머지 리퀘스트 수에 비례합니다.

영향을 추정하려면:

PostgreSQL 쿼리:

-- Count total merge requests
SELECT COUNT(*) FROM merge_requests;

-- Estimate table size
SELECT pg_size_pretty(pg_total_relation_size('merge_requests')) AS table_size;

Rails 콘솔:

# Count total merge requests
MergeRequest.count

# Count remaining merge requests to migrate
MergeRequest.left_joins(:merge_data)
  .where(merge_requests_merge_data: { merge_request_id: nil })
  .count

마이그레이션은 배치로 머지 리퀘스트를 처리하며 대부분의 인스턴스에서 몇 시간에서 며칠 이내에 완료됩니다.