이 페이지에는 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의 버그로 인해 백그라운드 작업 완료가 올바르게 강제되지 않아 GitLab 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

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

Kubernetes용 GitLab 에이전트 서버 변경#

GitLab 17.8.0에서 Kubernetes용 GitLab 에이전트 서버(KAS)는 GitLab Linux 패키지(Omnibus) 및 Docker 설치의 기본 설정으로 시작되지 않습니다.

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

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

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

Workhorse의 S3 객체 스토리지 업로드 변경#

Workhorse의 S3 객체 스토리지 업로드는 이제 AWS SDK v2 for Go만 사용합니다. 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으로 업그레이드#

• Git 2.47.0 이상이 Gitaly에서 필요합니다. 소스에서 컴파일된 설치의 경우 Gitaly에서 제공하는 Git 버전을 사용해야 합니다.
• FIPS Linux 패키지는 이제 시스템 Libgcrypt를 사용합니다(AmazonLinux 2용 FIPS Linux 패키지 제외). 이전 버전의 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와 같은 상태 저장 구성 요소에 Linux 패키지를 사용합니다. 해당 구성 요소의 경우 다음 설명의 보안 수준 변경 사항과 함께 작동하는 TLS 버전, 암호 및 인증서를 확인해야 합니다.

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은 수명 종료에 도달했으며 더 이상 안전하다고 간주되지 않습니다. GitLab은 no protocols available 오류 메시지와 함께 TLS 1.0 또는 1.1을 사용하는 서비스에 연결하지 못합니다.

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

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

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

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

자세한 내용은 설치 보안에 관한 GitLab 문서를 참조하십시오.

17.5.0으로 업그레이드#

• GitLab Runner 분산 캐시를 위한 S3 객체 스토리지 액세스는 이제 MinIO 클라이언트 대신 AWS SDK v2 for Go로 처리됩니다. 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 이하를 설치하십시오. 그런 다음 이후 릴리스로 업그레이드하여 기존 환경과 동일한 데이터베이스 마이그레이션을 실행할 수 있습니다. 새 환경에 백업에서 복원하는 경우 데이터베이스 복원이 기존 데이터베이스 스키마 정의를 제거하고 백업의 일부로 저장된 정의를 사용하므로 이 작업이 필요하지 않습니다.

• Git 2.46.0 이상이 Gitaly에서 필요합니다. 소스에서 컴파일된 설치의 경우 Gitaly에서 제공하는 Git 버전을 사용해야 합니다.

• Workhorse의 S3 객체 스토리지 업로드는 이제 기본적으로 AWS SDK v2 for Go를 사용하여 처리됩니다. 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 연결을 거부합니다. TLS가 활성화된 상태에서 Praefect 앞에 로드 밸런서를 사용하는 경우 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으로 업그레이드#

• Git 2.45.0 이상이 Gitaly에서 필요합니다. 소스에서 컴파일된 설치의 경우 Gitaly에서 제공하는 Git 버전을 사용해야 합니다.

Geo 설치 17.3.0#

• 보조 사이트의 Geo 복제 세부 정보 페이지가 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 복제 세부 정보 페이지가 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 ID가 삭제됩니다. 자세한 내용은 이슈 452426을 참조하십시오.
• 기본 변경 로그 템플릿은 GitLab 특정 참조 대신 전체 URL로 링크를 생성합니다. 자세한 내용은 머지 리퀘스트 155806을 참조하십시오.
• Git 2.44.0 이상이 Gitaly에서 필요합니다. 소스에서 컴파일된 설치의 경우 Gitaly에서 제공하는 Git 버전을 사용해야 합니다.
• GitLab 17.1.0 또는 17.1.1로 업그레이드하거나 GitLab 17.0에서 완료되지 않은 백그라운드 마이그레이션이 있으면 마이그레이션 실행 시 실패가 발생할 수 있습니다. 이는 버그로 인한 것입니다. 이슈 468875는 GitLab 17.1.2에서 수정되었습니다.

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

GitLab 17.1은 ci_pipeline_messages 테이블에 많은 레코드가 있는 대규모 GitLab 인스턴스의 필수 중지 지점입니다.

데이터 변경은 시간당 처리되는 150만~200만 레코드 속도로 대규모 GitLab 인스턴스에서 완료하는 데 많은 시간이 걸릴 수 있습니다. 인스턴스가 영향을 받는 경우:

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에 대한 카운트와 함께 출력을 반환하면 인스턴스가 이 필수 중지 지점의 임계값을 충족합니다. 0 rows를 보고하는 인스턴스는 17.1 업그레이드 중지를 건너뛸 수 있습니다.

GitLab 17.1은 ci_pipeline_messages 테이블의 모든 레코드에 올바른 파티셔닝 키가 있는지 확인하는 일괄 백그라운드 마이그레이션을 도입했습니다. CI 테이블 파티셔닝은 대량의 CI 데이터가 있는 인스턴스에 대한 성능 향상을 제공할 것으로 예상됩니다.

GitLab 17.2로 업그레이드는 필요한 경우 업그레이드 중에 17.1 변경 사항을 동기적으로 실행하여 17.1 백그라운드 마이그레이션이 완료되도록 하는 Finalize 마이그레이션을 실행합니다.

GitLab 17.2는 파티셔닝 키가 채워져야 하는 외래 키 데이터베이스 제약 조건도 추가합니다. 제약 조건은 GitLab 17.3으로 업그레이드의 일부로 검증됩니다.

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

• 업그레이드가 완료되는 동안 영향을 받는 인스턴스에 대한 다운타임이 연장됩니다.

• 앞으로 수정하는 것이 안전합니다.

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

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

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

Linux 패키지(Omnibus) 또는 Docker 업그레이드는 1시간 후 타임아웃과 함께 실패할 가능성이 높습니다:

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

이 문제를 해결하려면:

1. 이전 Rake 작업을 실행하여 일괄 마이그레이션을 완료합니다.
2. 시간 초과된 작업의 나머지를 완료합니다. 이 프로세스 끝에서 500 오류를 수정하기 위해 Sidekiq와 Puma가 재시작됩니다.

이 업그레이드 경로에 대한 조건부 중지에 대한 피드백은 이슈에서 제공할 수 있습니다.

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 복제 세부 정보 페이지가 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 복제 세부 정보 페이지가 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

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