이 페이지는 GitLab 17의 마이너 및 패치 버전에 대한 업그레이드 정보를 담고 있습니다. 다음 사항에 대해 이 안내를 반드시 검토합니다.

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

Helm 차트 설치에 대한 추가 정보는 Helm 차트 8.0 업그레이드 노트를 참고합니다.

업그레이드 시 알아둘 이슈#

특정 GitLab 버전에서 업그레이드할 때 업그레이드에 영향을 줄 수 있는 이슈를 알아둡니다.

GitLab 16.11에서 업그레이드하는 경우#

GitLab 16.11에서 업그레이드하는 경우:

• 백그라운드 마이그레이션 AlterWebhookDeletedAuditEvent: audit_events는 완료까지 여러 시간이 걸릴 수 있습니다. 자세한 내용은 머지 리퀘스트 161320을 참고합니다.

• GitLab 17.0 이상으로 업그레이드하기 전에 gitlab.rb에서 지금은 폐지된 번들 Grafana 키에 대한 참조를 제거해야 합니다. 업그레이드 이후 gitlab.rb에 이 키에 대한 참조가 남아 있으면 gitlab-ctl reconfigure가 실패합니다.

• GitLab 17.0으로 업그레이드하기 전에 새 러너 등록 워크플로로 마이그레이션해야 합니다.

  GitLab 16.0에서는 러너 인증 토큰을 사용해 러너를 등록하는 새 러너 생성 워크플로가 도입되었습니다. 등록 토큰을 사용하는 레거시 워크플로는 GitLab 17.0부터 기본적으로 비활성화되며 GitLab 20.0에서 제거될 예정입니다. 등록 토큰을 계속 사용 중이라면 GitLab 17.0으로 업그레이드할 때 러너 등록이 실패합니다.

• Gitaly 스토리지는 다음 예시처럼 더 이상 동일한 경로를 공유할 수 없습니다.

  gitaly['configuration'] = {
    storage: [
      {
         name: 'default',
         path: '/var/opt/gitlab/git-data/repositories',
      },
      {
         name: 'duplicate-path',
         path: '/var/opt/gitlab/git-data/repositories',
      },
    ],
  }
  

  이 예시에서는 duplicate-path 스토리지를 제거하거나 새 경로로 옮겨야 합니다. Gitaly 노드가 둘 이상인 경우 해당 노드에 대응하는 스토리지만 그 노드의 gitlab.rb 파일에 나열되어 있는지 반드시 확인합니다.

  노드의 gitlab.rb 파일에서 스토리지를 제거한 경우, 그 스토리지와 연결된 모든 프로젝트는 GitLab 데이터베이스에서 스토리지 정보를 갱신해야 합니다. Rails 콘솔을 사용해 스토리지를 갱신할 수 있습니다. 예:

  $ sudo gitlab-rails console
  Project.where(repository_storage: 'duplicate-path').update_all(repository_storage: 'default')
  

• GitLab 16.x에서 GitLab 17.1.0 또는 17.1.1로 직접 업그레이드할 때 발생하는 마이그레이션 실패. 이 버그는 GitLab 17.1.2에서 수정되었습니다. GitLab 16.x에서 17.1.2로 직접 업그레이드하는 경우에는 이 문제가 발생하지 않습니다.

  GitLab 17.1.0 및 17.1.1의 버그로 인해 백그라운드 작업 완료가 올바르게 반영되지 않아 17.1.0 및 17.1.1로 직접 업그레이드할 때 실패가 발생할 수 있습니다. 업그레이드 마이그레이션 중 발생하는 오류는 다음과 같이 표시됩니다.

  main: == [advisory_lock_connection] object_id: 55460, pg_backend_pid: 8714
  main: == 20240531173207 ValidateNotNullCheckConstraintOnEpicsIssueId: migrating =====
  main: -- execute("SET statement_timeout TO 0")
  main:    -> 0.0004s
  main: -- execute("ALTER TABLE epics VALIDATE CONSTRAINT check_450724d1bb;")
  main: -- execute("RESET statement_timeout")
  main: == [advisory_lock_connection] object_id: 55460, pg_backend_pid: 8714
  STDERR:
  

  업그레이드하려면 다음 중 하나를 수행합니다.

  • GitLab 17.0으로 업그레이드한 뒤 모든 백그라운드 마이그레이션이 완료될 때까지 기다립니다.

  • GitLab 17.1로 업그레이드한 뒤 다음 명령을 실행해 백그라운드 작업과 마이그레이션을 수동으로 실행합니다.

    sudo gitlab-rake gitlab:background_migrations:finalize[BackfillEpicBasicFieldsToWorkItemRecord,epics,id,'[null]']
    

  이제 GitLab 17.1에서 마이그레이션을 완료하고 업그레이드를 마칠 수 있습니다.

• GitLab 17.0.x 및 GitLab 17.1.x와 함께 제공되는 Git 버전의 알려진 이슈로 인해 부하 상태에서 CPU 사용량이 눈에 띄게 증가합니다. 이 회귀의 주요 원인은 GitLab 17.2와 함께 제공되는 Git 버전에서 해결되었으므로, 피크 부하가 큰 시스템이라면 GitLab 17.2로 업그레이드합니다.

Linux 패키지 설치#

Linux 패키지 설치에는 다음 정보가 적용됩니다.

• PostgreSQL 13 바이너리가 제거되었습니다.

  업그레이드하기 전에 설치 환경이 PostgreSQL 14를 사용하고 있는지 반드시 확인합니다.

• Ubuntu 18.04용 패키지는 더 이상 빌드되지 않습니다.

  GitLab을 업그레이드하기 전에 운영체제가 Ubuntu 20.04 이상으로 업그레이드되었는지 확인합니다.

만료되지 않는 액세스 토큰#

만료 날짜가 없는 액세스 토큰은 무기한 유효하며, 이는 액세스 토큰이 유출될 경우 보안 위험이 됩니다.

GitLab 16.0 이상으로 업그레이드하면 만료 날짜가 없는 개인, 프로젝트, 또는 그룹 액세스 토큰에는 업그레이드 시점으로부터 1년 뒤의 만료 날짜가 자동으로 설정됩니다.

이 자동 만료일이 적용되기 전에, 혼란을 최소화하기 위해 다음을 수행합니다.

1. 만료 날짜가 없는 액세스 토큰을 식별합니다.
2. 해당 토큰에 만료 날짜를 지정합니다.

자세한 내용은 다음을 참고합니다.

• 폐지 및 제거 문서.
• 폐지 이슈.

GitLab 17.0 이하에서 업그레이드하는 경우#

Linux 패키지 설치의 경우, GitLab 17.1 이상으로 업그레이드하기 전에 /etc/gitlab/gitlab.rb에서 지금은 폐지된 번들 Grafana 키(grafana[])에 대한 참조를 제거해야 합니다. 업그레이드 이후 /etc/gitlab/gitlab.rb에 이 키에 대한 참조가 남아 있으면 머지 리퀘스트 위젯과 같은 기능이 깨질 수 있습니다.

자세한 내용은 다음 이슈를 참고합니다.

• Grafana 속성 및 폐지 메시지 제거.
• Grafana를 폐지하고 브레이킹 체인지로 비활성화.

GitLab 17.1 이하에서 업그레이드하는 경우#

GitLab 17.1 이하에서 업그레이드하는 경우:

• GitLab Duo를 사용 중이며 GitLab 17.2.3 이하로 업그레이드하는 경우, 다음 두 가지를 모두 수행해야 합니다.
  • 라이선스를 재동기화합니다.
  • 업그레이드 후 서버를 재시작합니다.
• GitLab Duo를 사용 중이며 GitLab 17.2.4 이상으로 업그레이드하는 경우, 다음 중 하나를 수행해야 합니다.
  • 라이선스를 재동기화합니다.
  • 24시간마다 발생하는 다음 예약 라이선스 동기화를 기다립니다.

GitLab 17.2.4 이상으로 업그레이드한 뒤에는 이후 업그레이드에서 이 단계가 필요하지 않습니다.

자세한 내용은 이슈 480328을 참고합니다.

GitLab 17.3에서 업그레이드하는 경우#

GitLab 17.3에서 업그레이드할 때 발생하는 마이그레이션 실패.

17.3에서 17.4로 업그레이드할 때 오류가 발생할 가능성이 약간 있습니다. 마이그레이션 과정에서 다음과 유사한 오류 메시지가 표시될 수 있습니다.

main: == [advisory_lock_connection] object_id: 127900, pg_backend_pid: 76263
main: == 20240812040748 AddUniqueConstraintToRemoteDevelopmentAgentConfigs: migrating
main: -- transaction_open?(nil)
main:    -> 0.0000s
main: -- view_exists?(:postgres_partitions)
main:    -> 0.0181s
main: -- index_exists?(:remote_development_agent_configs, :cluster_agent_id, {:name=>"index_remote_development_agent_configs_on_unique_agent_id", :unique=>true, :algorithm=>:concurrently})
main:    -> 0.0026s
main: -- execute("SET statement_timeout TO 0")
main:    -> 0.0004s
main: -- add_index(:remote_development_agent_configs, :cluster_agent_id, {:name=>"index_remote_development_agent_configs_on_unique_agent_id", :unique=>true, :algorithm=>:concurrently})
main: -- execute("RESET statement_timeout")
main:    -> 0.0002s
main: == [advisory_lock_connection] object_id: 127900, pg_backend_pid: 76263
rake aborted!
StandardError: An error has occurred, all later migrations canceled:

PG::UniqueViolation: ERROR:  could not create unique index "index_remote_development_agent_configs_on_unique_agent_id"
DETAIL:  Key (cluster_agent_id)=(1000141) is duplicated.

이 오류는 마이그레이션이 remote_development_agent_configs 테이블의 cluster_agent_id 칼럼에 고유 제약 조건을 추가하지만, 여전히 중복 항목이 남아 있기 때문에 발생합니다. 이전 마이그레이션이 이 중복 항목을 제거해야 하지만, 드물게 두 마이그레이션 사이에 새 중복 항목이 삽입될 수 있습니다.

이 문제를 안전하게 해결하려면 다음 단계를 따릅니다.

1. 마이그레이션이 실행 중인 Rails 콘솔을 엽니다.
2. Rails 콘솔에서 다음 스크립트를 실행합니다.
3. 마이그레이션을 다시 실행하면 정상적으로 완료됩니다.

# Get the IDs to keep for each cluster_agent_id; if there are duplicates, only the row with the latest updated_at will be kept.
latest_ids = ::RemoteDevelopment::RemoteDevelopmentAgentConfig.select("DISTINCT ON (cluster_agent_id) id")
  .order("cluster_agent_id, updated_at DESC")
  .map(&:id)

# Get the list of remote_development_agent_configs to be removed.
agent_configs_to_remove = ::RemoteDevelopment::RemoteDevelopmentAgentConfig.where.not(id: latest_ids)

# Delete all duplicated agent_configs.
agent_configs_to_remove.delete_all

GitLab 17.4에서 업그레이드하는 경우#

17.4에서 17.5로 업그레이드할 때 발생하는 백그라운드 작업 마이그레이션 실패.

17.4에서 17.5로 업그레이드할 때, 제거된 백그라운드 데이터 마이그레이션과 관련해 Sidekiq 작업에서 오류가 나타날 수 있습니다. 오류 메시지는 다음과 같습니다. uninitialized constant Gitlab::BackgroundMigration::SetProjectVulnerabilityCount.

이 오류는 결국 저절로 사라지지만, Rails 콘솔에서 다음 스크립트를 실행해 오류가 더 이상 나타나지 않게 할 수도 있습니다.

Gitlab::Database::BackgroundMigration::BatchedMigration.for_configuration(
  :gitlab_main, 'SetProjectVulnerabilityCount', :project_settings, :project_id, []
).delete_all

GitLab 17.5에서 업그레이드하는 경우#

GitLab 17.5에서 업그레이드할 때 발생하는 마이그레이션 실패.

17.5에서 17.6으로 업그레이드할 때 오류가 발생할 가능성이 약간 있습니다. 마이그레이션 과정에서 다음과 유사한 오류 메시지가 표시될 수 있습니다.

rake aborted!
StandardError: An error has occurred, all later migrations canceled:

PG::CheckViolation: ERROR: new row for relation "ci_deleted_objects" violates check constraint "check_98f90d6c53"

이 오류는 마이그레이션이 ci_deleted_objects 테이블의 일부 행을 처리 대상으로 갱신하려 하지만, 필수 체크 제약 조건에 대한 값이 없는 오래된 레코드일 수 있기 때문에 발생합니다.

이 문제를 안전하게 해결하려면 다음 단계를 따릅니다.

1. 체크 제약 조건의 영향을 받은 레코드를 수정하기 위해 다음 마이그레이션만 실행합니다.

2. 마이그레이션을 다시 실행하면 정상적으로 완료됩니다.

   gitlab-rake db:migrate:up:ci VERSION=20241028085044
   

17.11.0으로 업그레이드하는 경우#

• 데이터베이스 마이그레이션이 오래 실행되며 CPU를 과도하게 사용하게 만드는 알려진 이슈를 피하려면 GitLab 17.11.3 이상으로 업데이트합니다.

새 암호화 시크릿#

GitLab 17.8에서는 새 암호화 프레임워크(17.9부터 사용 시작)를 지원하기 위해 세 가지 새 시크릿이 추가되었습니다.

• active_record_encryption_primary_key
• active_record_encryption_deterministic_key
• active_record_encryption_key_derivation_salt

다중 노드 구성인 경우 이 시크릿이 모든 노드에서 동일한지 반드시 확인해야 합니다.

Geo 설치 17.11.0#

• GitLab 17.11부터 18.1까지는 보조 Geo 사이트에서 프록시된 Git 작업이 HTTP 500 오류로 실패하는 알려진 이슈가 있습니다. 이 문제를 해결하려면 GitLab 17.11.5 이상으로 업그레이드합니다.

17.10.0으로 업그레이드하는 경우#

• GitLab 17.10으로 업그레이드할 때 러너 태그가 누락되는 문제는 이슈 524402를 참고합니다. 먼저 GitLab 17.6으로 업그레이드하면 이 문제를 피할 수 있습니다. 이 버그는 GitLab 17.11에서 수정되었습니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  17.8	17.8.0 - 17.8.6	17.8.7
  17.9	17.9.0 - 17.9.4	17.9.5
  17.10	17.10.0 - 17.10.4	17.10.5

  표에 언급된 패치 릴리스보다 오래된 버전에서 17.5를 거쳐 업그레이드하는 경우, 러너 태그 테이블이 비어 있게 될 가능성이 있습니다.

  영향을 받는지 확인하려면 ci 데이터베이스에서 다음 PostgreSQL 쿼리를 실행해 러너 태그 테이블을 확인합니다.

  SELECT 'OK, ci_runner_taggings is populated.' FROM ci_runner_taggings LIMIT 1;
  

  쿼리가 OK, ci_runner_taggings is populated. 대신 빈 결과를 반환하면, 관련 이슈의 워크어라운드를 참고합니다.

새 암호화 시크릿#

GitLab 17.8에서는 새 암호화 프레임워크(17.9부터 사용 시작)를 지원하기 위해 세 가지 새 시크릿이 추가되었습니다.

• active_record_encryption_primary_key
• active_record_encryption_deterministic_key
• active_record_encryption_key_derivation_salt

다중 노드 구성인 경우 이 시크릿이 모든 노드에서 동일한지 반드시 확인해야 합니다.

Geo 설치 17.10.0#

• GitLab 17.10부터 18.1까지는 보조 Geo 사이트에서 프록시된 Git 작업이 HTTP 500 오류로 실패하는 알려진 이슈가 있습니다. 이 문제를 해결하려면 GitLab 17.11.5 이상으로 업그레이드합니다.

17.9.0으로 업그레이드하는 경우#

• GitLab 17.9로 업그레이드할 때 러너 태그가 누락되는 문제는 이슈 524402를 참고합니다. 먼저 GitLab 17.6으로 업그레이드하면 이 문제를 피할 수 있습니다. 이 버그는 GitLab 17.11에서 수정되었습니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  17.8	17.8.0 - 17.8.6	17.8.7
  17.9	17.9.0 - 17.9.4	17.9.5
  17.10	17.10.0 - 17.10.4	17.10.5

  표에 언급된 패치 릴리스보다 오래된 버전에서 17.5를 거쳐 업그레이드하는 경우, 러너 태그 테이블이 비어 있게 될 가능성이 있습니다.

  영향을 받는지 확인하려면 ci 데이터베이스에서 다음 PostgreSQL 쿼리를 실행해 러너 태그 테이블을 확인합니다.

  SELECT 'OK, ci_runner_taggings is populated.' FROM ci_runner_taggings LIMIT 1;
  

  쿼리가 OK, ci_runner_taggings is populated. 대신 빈 결과를 반환하면, 관련 이슈의 워크어라운드를 참고합니다.

새 암호화 시크릿#

GitLab 17.8에서는 새 암호화 프레임워크(17.9부터 사용 시작)를 지원하기 위해 세 가지 새 시크릿이 추가되었습니다.

• active_record_encryption_primary_key
• active_record_encryption_deterministic_key
• active_record_encryption_key_derivation_salt

다중 노드 구성인 경우 이 시크릿이 모든 노드에서 동일한지 반드시 확인해야 합니다.

17.8.0으로 업그레이드하는 경우#

• GitLab 17.8로 업그레이드할 때 발생하는 마이그레이션 실패.

  17.8로 업그레이드할 때 오류가 발생할 가능성이 약간 있습니다. 마이그레이션 과정에서 다음과 유사한 오류 메시지가 표시될 수 있습니다.

  ERROR:  duplicate key value violates unique constraint "work_item_types_pkey"
  DETAIL:  Key (id)=(1) already exists.
  

  오류를 발생시키는 마이그레이션은 db/post_migrate/20241218223002_fix_work_item_types_id_column_values.rb입니다.

  이 오류는 일부 경우 work_item_types 테이블의 레코드가 애플리케이션에 추가된 순서와 다른 순서로 데이터베이스에 생성되었기 때문에 발생합니다.

  이 문제를 안전하게 해결하려면 다음 단계를 따릅니다.

  1. 17.8로 업그레이드하다가 이 오류가 발생한 경우에만 수행합니다. gitlab_main 데이터베이스에서 다음 SQL 쿼리를 실행합니다.

     UPDATE work_item_types set id = (id * 10);
     

  2. 실패한 마이그레이션을 다시 실행합니다. 이제 정상적으로 완료됩니다.

• GitLab 17.8로 업그레이드할 때 러너 태그가 누락되는 문제는 이슈 524402를 참고합니다.

  먼저 GitLab 17.6으로 업그레이드하면 이 문제를 피할 수 있습니다. 이 버그는 GitLab 17.11에서 수정되었습니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  17.8	17.8.0 - 17.8.6	17.8.7
  17.9	17.9.0 - 17.9.4	17.9.5
  17.10	17.10.0 - 17.10.4	17.10.5

  표에 언급된 패치 릴리스보다 오래된 버전에서 17.5를 거쳐 업그레이드하는 경우, 러너 태그 테이블이 비어 있게 될 가능성이 있습니다.

  영향을 받는지 확인하려면 ci 데이터베이스에서 다음 PostgreSQL 쿼리를 실행해 러너 태그 테이블을 확인합니다.

  SELECT 'OK, ci_runner_taggings is populated.' FROM ci_runner_taggings LIMIT 1;
  

  쿼리가 OK, ci_runner_taggings is populated. 대신 빈 결과를 반환하면, 관련 이슈의 워크어라운드를 참고합니다.

새 암호화 시크릿#

GitLab 17.8에서는 새 암호화 프레임워크(17.9부터 사용 시작)를 지원하기 위해 세 가지 새 시크릿이 추가되었습니다.

• active_record_encryption_primary_key
• active_record_encryption_deterministic_key
• active_record_encryption_key_derivation_salt

다중 노드 구성인 경우 이 시크릿이 모든 노드에서 동일한지 반드시 확인해야 합니다.

GitLab agent server for Kubernetes 변경 사항#

GitLab 17.8.0에서는 GitLab Linux 패키지(Omnibus) 및 Docker 설치에서 GitLab agent server for Kubernetes(KAS)가 기본 설정으로 시작되지 않습니다.

이 문제를 해결하려면 /etc/gitlab/gitlab.rb를 편집합니다.

gitlab_kas['env'] = { 'OWN_PRIVATE_API_URL' => 'grpc://127.0.0.1:8155' }

다중 노드 설치에서는 문서에 설명된 설정을 사용해야 합니다.

Workhorse의 S3 오브젝트 스토리지 업로드 변경 사항#

Workhorse의 S3 오브젝트 스토리지 업로드는 이제 Go용 AWS SDK v2만 사용합니다. workhorse_use_aws_sdk_v2 기능 플래그는 제거되었습니다. AWS SDK v2는 Accept-Encoding: identity를 설정하고 이를 서명된 헤더로 포함합니다. 그러나 Cloudflare와 같은 일부 프록시 서비스는 이 헤더를 변경해 서명 불일치 오류를 일으킵니다. SignatureDoesNotMatch 오류가 발생하면 프록시 서버가 서명된 HTTP 헤더를 변경하거나 제거하지 않는지 확인합니다.

17.5에서 17.8로 업그레이드하는 경우#

• GitLab 17.5에서 17.8로 업그레이드할 때, group_type_ci_runner_machines 테이블에 대한 삽입 또는 갱신에서 백그라운드 마이그레이션이 실패합니다.

  UI에서는 마이그레이션 경로 BackfillCiRunnerMachinesPartitionedTable: ci_runner_machines가 진행률 0.00%, 상태 failed로 표시됩니다. 로그에 나타나는 해당 오류에는 외래 키 제약 조건 오류가 포함됩니다.

  ERROR:  insert or update on table "group_type_ci_runner_machines_" violates foreign key constraint "fk_rails_"
  

  이 오류를 해결하려면 UI에서 마이그레이션을 초기화합니다.

17.7.0으로 업그레이드하는 경우#

• Gitaly는 Git 2.47.0 이상을 요구합니다. 자체 컴파일 설치의 경우 Gitaly가 제공하는 Git 버전을 사용해야 합니다.
• FIPS Linux 패키지는 이제 AmazonLinux 2용 FIPS Linux 패키지를 제외하고 시스템 Libgcrypt를 사용합니다. 이전 버전의 FIPS Linux 패키지는 일반 Linux 패키지와 동일한 Libgcrypt를 사용했는데, 이는 버그였습니다. 자세한 내용은 FIPS에 관한 GitLab 개발 문서를 참고합니다.
• Linux gitlab-runner 패키지에서는 gitlab-runner-helper-images가 새로운 필수 의존성으로 분리되었습니다. 업그레이드를 위해 gitlab-runner 패키지를 수동으로 설치하는 경우, 헬퍼 이미지도 수동으로 내려받아야 합니다.

OpenSSL 3 업그레이드#

• Linux 패키지는 OpenSSL을 v1.1.1w에서 v3.0.0으로 업그레이드합니다.
• Cloud Native GitLab(CNG)은 GitLab 16.7.0에서 이미 OpenSSL 3으로 업그레이드되었습니다. Cloud Native GitLab을 사용 중이라면 별도 조치가 필요하지 않습니다. 다만 Cloud Native Hybrid 설치는 Gitaly와 같은 상태 저장(stateful) 구성 요소에 Linux 패키지를 사용합니다. 이 구성 요소에 대해서는 아래 설명에 나오는 보안 수준 변경 사항에 맞춰 사용 중인 TLS 버전, 암호(cipher), 인증서를 확인해야 합니다.

OpenSSL 3으로 업그레이드하면:

• GitLab은 모든 아웃바운드 및 인바운드 TLS 연결에 TLS 1.2 이상을 요구합니다.
• TLS/SSL 인증서는 최소 112비트의 보안 수준을 가져야 합니다. 2048비트보다 짧은 RSA, DSA, DH 키와 224비트보다 짧은 ECC 키는 금지됩니다.

LDAP, Webhook 서버 등 오래된 서비스는 여전히 TLS 1.1을 사용할 수 있습니다. 그러나 TLS 1.0과 1.1은 수명 종료(end-of-life)에 도달했으며 더 이상 안전하다고 간주되지 않습니다. GitLab은 TLS 1.0 또는 1.1을 사용하는 서비스에 연결하지 못하고 no protocols available 오류 메시지를 표시합니다.

또한 OpenSSL 3은 기본 보안 수준을 레벨 1에서 레벨 2로 높여, 최소 보안 비트 수를 80에서 112로 올렸습니다. 그 결과 2048비트보다 짧은 RSA 및 DSA 키와 224비트보다 짧은 ECC 키로 서명된 인증서는 금지됩니다.

GitLab은 비트 수가 불충분한 인증서로 서명된 서비스에 연결하지 못하고 certificate key too weak 오류 메시지를 표시합니다. 자세한 내용은 인증서 요구 사항을 참고합니다.

Linux 패키지와 함께 제공되는 모든 구성 요소는 OpenSSL 3과 호환됩니다. 따라서 GitLab 패키지에 포함되지 않고 "외부"에 해당하는 서비스 및 통합만 확인하면 됩니다.

SSH 키는 이 업그레이드의 영향을 받지 않습니다. OpenSSL은 TLS에 대한 보안 요구 사항을 설정하며 SSH에는 적용되지 않습니다. OpenSSH와 gitlab-sshd는 허용되는 암호화 알고리즘에 대해 자체 설정을 가지고 있습니다.

자세한 내용은 설치 환경을 보호하는 방법에 관한 GitLab 문서를 확인합니다.

17.5.0으로 업그레이드하는 경우#

• GitLab Runner 분산 캐시의 S3 오브젝트 스토리지 액세스는 이제 MinIO 클라이언트 대신 Go용 AWS SDK v2가 처리합니다. FF_USE_LEGACY_S3_CACHE_ADAPTER GitLab Runner 기능 플래그를 true로 설정하면 MinIO 클라이언트를 다시 활성화할 수 있습니다.
• Gitaly가 GitLab에 인증할 때 사용하는 토큰은 이제 별도의 설정이 되었습니다. 즉 Gitaly는 셸 디렉터리 안의 기본 시크릿 파일을 실행하고 채우기 위해 GitLab Rails와 Shell 레시피가 필요하지 않으며, 자체 시크릿 파일을 가질 수 있습니다. 일부 커스터마이즈된 환경에서는 시크릿 불일치를 피하기 위해 인증 설정을 업데이트해야 할 수 있습니다.

17.4.0으로 업그레이드하는 경우#

• GitLab 17.4부터 새 GitLab 설치는 ID 칼럼에 대해 다른 데이터베이스 스키마를 사용합니다.

  • 이전의 모든 정수형(32비트) ID 칼럼(예: id, %_id, %_ids 같은 칼럼)은 이제 bigint(64비트)로 생성됩니다.
  • 기존 설치는 이 변경을 수행하는 데이터베이스 마이그레이션이 제공되는 이후 릴리스에서 32비트에서 64비트 정수로 마이그레이션됩니다.
  • 업그레이드 테스트를 위해 새 GitLab 환경을 구축하는 경우, 기존 환경과 동일한 정수 타입을 얻으려면 GitLab 17.3 이하를 설치합니다. 이후 이후 릴리스로 업그레이드하면 기존 환경과 동일한 데이터베이스 마이그레이션을 실행할 수 있습니다. 백업에서 새 환경으로 복원하는 경우에는 데이터베이스 복원 과정에서 기존 데이터베이스 스키마 정의가 제거되고 백업에 저장된 정의가 사용되므로 이 작업이 필요하지 않습니다.

• Gitaly는 Git 2.46.0 이상을 요구합니다. 자체 컴파일 설치의 경우 Gitaly가 제공하는 Git 버전을 사용해야 합니다.

• Workhorse의 S3 오브젝트 스토리지 업로드는 이제 기본적으로 Go용 AWS SDK v2가 처리합니다. S3 오브젝트 스토리지 업로드에 문제가 발생하면 workhorse_use_aws_sdk_v2 기능 플래그를 비활성화해 v1으로 다운그레이드할 수 있습니다.

• GitLab 17.4로 업그레이드하면 Web IDE용 OAuth 애플리케이션이 생성됩니다. GitLab.rb 파일의 GitLab 서버 외부 URL 설정에 대문자가 포함되어 있으면 Web IDE 로딩이 실패할 수 있습니다. 이 문제를 해결하려면 OAuth 콜백 URL 업데이트를 참고합니다.

• RFC 7540에 따라 Gitaly와 Praefect는 ALPN을 지원하지 않는 TLS 연결을 거부합니다. Praefect 앞단에 TLS를 활성화한 로드 밸런서를 사용하는 경우, ALPN이 사용되지 않으면 FAIL: 14:connections to all backends failing 오류가 발생할 수 있습니다. Praefect 환경에서 GRPC_ENFORCE_ALPN_ENABLED=false를 설정하면 이 강제 적용을 비활성화할 수 있습니다. Linux 패키지에서는 /etc/gitlab/gitlab.rb를 편집합니다.

  praefect['env'] = { 'GRPC_ENFORCE_ALPN_ENABLED' => 'false' }
  

  그런 다음 gitlab-ctl reconfigure를 실행합니다.

  ALPN 강제 적용은 GitLab 17.5.5 및 그 이후 일부 버전에서 다시 비활성화되었습니다. 이 버전 중 하나로 업그레이드하면 GRPC_ENFORCE_ALPN_ENABLED를 설정할 필요가 없어집니다.

17.3.0으로 업그레이드하는 경우#

• Gitaly는 Git 2.45.0 이상을 요구합니다. 자체 컴파일 설치의 경우 Gitaly가 제공하는 Git 버전을 사용해야 합니다.

Geo 설치 17.3.0#

• 보조 사이트의 Geo Replication Details 페이지는 Geo 복제가 정상 동작 중이더라도 비어 있는 것처럼 보일 수 있습니다. 이슈 468509를 참고합니다. 알려진 워크어라운드는 없습니다. 이 버그는 GitLab 17.4에서 수정되었습니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  16.11	16.11.5 - 16.11.10	None
  17.0	All	17.0.7
  17.1	All	17.1.7
  17.2	All	17.2.5
  17.3	All	17.3.1

17.2.1로 업그레이드하는 경우#

• GitLab 17.2.1로 업그레이드할 때 데이터베이스의 알 수 없는 시퀀스로 인해 실패할 수 있습니다. 이 이슈는 GitLab 17.2.2에서 수정되었습니다.

• GitLab 17.2.1로의 업그레이드가 다음 오류와 함께 실패할 수 있습니다.

  PG::DependentObjectsStillExist: ERROR: cannot drop desired object(s) because other objects depend on them
  

  이 이슈에서 설명하듯, 이 데이터베이스 시퀀스 소유권 이슈는 GitLab 17.2.1에서 수정되었습니다. 그러나 17.2.0의 마이그레이션이 완료되지 않은 상태에서 Linux 패키지가 손상된 JSON 파일 때문에 17.2.1 이상으로의 업그레이드를 막는 경우 이 문제를 겪을 수 있습니다. 예를 들어 다음과 같은 오류가 표시될 수 있습니다.

  Malformed configuration JSON file found at /opt/gitlab/embedded/nodes/gitlab.example.com.json.
  This usually happens when your last run of `gitlab-ctl reconfigure` didn't complete successfully.
  This file is used to check if any of the unsupported configurations are enabled,
  and hence require a working reconfigure before upgrading.
  Please run `sudo gitlab-ctl reconfigure` to fix it and try again.
  

  현재 워크어라운드는 다음과 같습니다.

  1. /opt/gitlab/embedded/nodes에 있는 JSON 파일을 제거합니다.

     rm /opt/gitlab/embedded/nodes/*.json
     

  2. GitLab 17.2.1 이상으로 업그레이드합니다.

Geo 설치 17.2.1#

• GitLab 16.11부터 GitLab 17.2까지는 PostgreSQL 인덱스 누락으로 인해 CPU 사용량이 높아지고, 작업 아티팩트 검증 진행이 느려지며, Geo 메트릭 상태 업데이트가 느려지거나 타임아웃될 수 있습니다. 이 인덱스는 GitLab 17.3에서 추가되었습니다. 수동으로 인덱스를 추가하려면 Geo 문제 해결 - 작업 아티팩트 검증 중 프라이머리의 높은 CPU 사용량을 참고합니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  16.11	All	None
  17.0	All	17.0.7
  17.1	All	17.1.7
  17.2	All	17.2.5

• 보조 사이트의 Geo Replication Details 페이지는 Geo 복제가 정상 동작 중이더라도 비어 있는 것처럼 보일 수 있습니다. 이슈 468509를 참고합니다. 알려진 워크어라운드는 없습니다. 이 버그는 GitLab 17.4에서 수정되었습니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  16.11	16.11.5 - 16.11.10	None
  17.0	All	17.0.7
  17.1	All	17.1.7
  17.2	All	17.2.5
  17.3	All	17.3.1

17.1.0으로 업그레이드하는 경우#

• 신뢰할 수 없는 extern_uid를 가진 Bitbucket 아이덴티티는 삭제됩니다. 자세한 내용은 이슈 452426을 참고합니다.
• 기본 체인지로그 템플릿은 GitLab 고유 참조 대신 전체 URL 형태의 링크를 생성합니다. 자세한 내용은 머지 리퀘스트 155806을 참고합니다.
• Gitaly는 Git 2.44.0 이상을 요구합니다. 자체 컴파일 설치의 경우 Gitaly가 제공하는 Git 버전을 사용해야 합니다.
• GitLab 17.1.0 또는 17.1.1로 업그레이드하거나 GitLab 17.0에서 백그라운드 마이그레이션이 완료되지 않은 상태로 남아 있으면 마이그레이션 실행 중 실패가 발생할 수 있습니다. 이는 버그 때문입니다. 이슈 468875는 GitLab 17.1.2에서 수정되었습니다.

장시간 실행되는 파이프라인 메시지 데이터 변경#

GitLab 17.1은 ci_pipeline_messages 테이블에 레코드가 많은 대규모 GitLab 인스턴스에서 반드시 거쳐야 하는 버전입니다.

대규모 GitLab 인스턴스에서는 데이터 변경이 완료되기까지 시간당 150만~200만 건 처리 속도로 여러 시간이 걸릴 수 있습니다. 인스턴스가 영향을 받는 경우:

1. 17.1로 업그레이드합니다.
2. 모든 배치 마이그레이션이 성공적으로 완료되었는지 확인합니다.
3. 17.2 또는 17.3으로 업그레이드합니다.

영향을 받는지 확인하려면:

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

2. 다음을 실행합니다.

   SELECT relname as table,n_live_tup as rows FROM pg_stat_user_tables
   WHERE relname='ci_pipeline_messages' and n_live_tup>1500000;
   

3. 쿼리가 ci_pipeline_messages에 대한 개수를 포함한 결과를 반환하면 해당 인스턴스는 이 필수 정거장(required stop)의 기준을 충족하는 것입니다. 0 rows가 보고되는 인스턴스는 17.1 업그레이드 정거장을 건너뛸 수 있습니다.

GitLab 17.1에서는 ci_pipeline_messages 테이블의 모든 레코드가 올바른 파티셔닝 키를 갖도록 보장하는 배치 백그라운드 마이그레이션이 도입되었습니다. CI 테이블을 파티셔닝하면 CI 데이터가 많은 인스턴스에서 성능 개선이 예상됩니다.

GitLab 17.2로의 업그레이드는 17.1 백그라운드 마이그레이션이 완료되었는지 확인하는 Finalize 마이그레이션을 실행하며, 필요한 경우 업그레이드 중 17.1 변경 사항을 동기적으로 실행합니다.

GitLab 17.2는 또한 파티셔닝 키가 채워져 있어야 하는 외래 키 데이터베이스 제약 조건을 추가합니다. 이 제약 조건은 GitLab 17.3으로의 업그레이드 과정 중에 검증됩니다.

업그레이드 경로에서 17.1이 생략되면(또는 17.1 마이그레이션이 완료되지 않은 경우):

• 영향받는 인스턴스는 업그레이드가 완료되는 동안 다운타임이 길어집니다.

• 앞으로 나아가며 고치는(fixing forward) 방식은 안전합니다.

• 환경을 더 빨리 사용 가능하게 하려면, 다음 Rake 작업으로 마이그레이션을 실행할 수 있습니다.

  sudo gitlab-rake gitlab:background_migrations:finalize[BackfillPartitionIdCiPipelineMessage,ci_pipeline_messages,id,'[]']
  

모든 데이터베이스 마이그레이션이 완료될 때까지, GitLab은 부분적으로 업그레이드된 데이터베이스 스키마와 실행 중인 Sidekiq 및 Puma 프로세스 간의 호환성 문제로 인해 500 오류를 발생시키며 사용할 수 없는 상태가 될 가능성이 높습니다.

Linux 패키지(Omnibus) 또는 Docker 업그레이드는 한 시간 후 타임아웃으로 실패할 가능성이 높습니다.

FATAL: Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails]
[..]
Mixlib::ShellOut::CommandTimeout: Command timed out after 3600s:

이를 해결하려면:

1. 앞서 소개한 Rake 작업을 실행해 배치 마이그레이션을 완료합니다.
2. 타임아웃된 나머지 작업을 완료합니다. 이 과정이 끝나면 Sidekiq과 Puma가 재시작되어 500 오류가 해결됩니다.

업그레이드 경로상의 이 조건부 정거장에 대한 피드백은 해당 이슈에서 제공할 수 있습니다.

Geo 설치 17.1.0#

• GitLab 16.11부터 GitLab 17.2까지는 PostgreSQL 인덱스 누락으로 인해 CPU 사용량이 높아지고, 작업 아티팩트 검증 진행이 느려지며, Geo 메트릭 상태 업데이트가 느려지거나 타임아웃될 수 있습니다. 이 인덱스는 GitLab 17.3에서 추가되었습니다. 수동으로 인덱스를 추가하려면 Geo 문제 해결 - 작업 아티팩트 검증 중 프라이머리의 높은 CPU 사용량을 참고합니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  16.11	All	None
  17.0	All	17.0.7
  17.1	All	17.1.7
  17.2	All	17.2.5

• 보조 사이트의 Geo Replication Details 페이지는 Geo 복제가 정상 동작 중이더라도 비어 있는 것처럼 보일 수 있습니다. 이슈 468509를 참고합니다. 알려진 워크어라운드는 없습니다. 이 버그는 GitLab 17.4에서 수정되었습니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  16.11	16.11.5 - 16.11.10	None
  17.0	All	17.0.7
  17.1	All	17.1.7
  17.2	All	17.2.5
  17.3	All	17.3.1

17.0.0으로 업그레이드하는 경우#

Geo 설치 17.0.0#

• GitLab 16.11부터 GitLab 17.2까지는 PostgreSQL 인덱스 누락으로 인해 CPU 사용량이 높아지고, 작업 아티팩트 검증 진행이 느려지며, Geo 메트릭 상태 업데이트가 느려지거나 타임아웃될 수 있습니다. 이 인덱스는 GitLab 17.3에서 추가되었습니다. 수동으로 인덱스를 추가하려면 Geo 문제 해결 - 작업 아티팩트 검증 중 프라이머리의 높은 CPU 사용량을 참고합니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  16.11	All	None
  17.0	All	17.0.7
  17.1	All	17.1.7
  17.2	All	17.2.5

• 보조 사이트의 Geo Replication Details 페이지는 Geo 복제가 정상 동작 중이더라도 비어 있는 것처럼 보일 수 있습니다. 이슈 468509를 참고합니다. 알려진 워크어라운드는 없습니다. 이 버그는 GitLab 17.4에서 수정되었습니다.

  영향받는 릴리스:

  영향받는 마이너 릴리스	영향받는 패치 릴리스	수정된 버전
  16.11	16.11.5 - 16.11.10	None
  17.0	All	17.0.7
  17.1	All	17.1.7
  17.2	All	17.2.5
  17.3	All	17.3.1

새 암호화 시크릿 통일#

GitLab 17.8에서 세 가지 새 시크릿이 도입되어, GitLab 17.9에서 도입된 새 암호화 프레임워크를 지원합니다.

• active_record_encryption_primary_key
• active_record_encryption_deterministic_key
• active_record_encryption_key_derivation_salt

다중 노드 구성인 경우 이 시크릿이 모든 노드에서 동일한지 반드시 확인해야 합니다. 그렇지 않으면 애플리케이션이 시작 시 누락된 시크릿을 자동으로 생성합니다.