16.11에서 업그레이드할 때 주의해야 할 사항
- 리눅스 패키지 설치
- 만료되지 않는 액세스 토큰
17.1 및 이전 버전에서 업그레이드 시 주의할 사항
17.3에서 업그레이드 시 주의할 사항
17.7.0
- OpenSSL 3 업그레이드
17.5.0
17.4.0
17.3.0
- Geo 설치
17.2.1
- Geo 설치
17.1.0
- Geo 설치
17.0.0
- Geo 설치

GitLab 17 변경 사항

Tier: Free, Premium, Ultimate Offering: Self-managed

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

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

GitLab Helm Chart 업그레이드에 대한 자세한 내용은 8.0 릴리스 노트를 참조하세요.

16.11에서 업그레이드할 때 주의해야 할 사항

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

GitLab 16.0에서는 러너 인증 토큰을 사용하여 러너를 등록하는 새로운 러너 생성 워크플로우를 도입했습니다.
등록 토큰을 사용하는 레거시 워크플로우는 GitLab 17.0에서 기본적으로 비활성화되며 GitLab 18.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.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.0으로 업그레이드하고 모든 백그라운드 마이그레이션이 완료될 때까지 기다립니다.
- GitLab 17.1로 업그레이드한 후 다음 명령어를 실행하여 백그라운드 작업 및 마이그레이션을 수동으로 실행합니다:
```
sudo gitlab-rake gitlab:background_migrations:finalize[BackfillEpicBasicFieldsToWorkItemRecord,epics,id,'[null]']
```
이제 GitLab 17.1에서 마이그레이션을 완료하고 업그레이드를 마칠 수 있어야 합니다.
이 버그는 GitLab 17.1.2에서 수정되었으며 GitLab 16.x에서 직접 17.1.2로 업그레이드하면 이러한 문제가 발생하지 않습니다.

리눅스 패키지 설치

리눅스 패키지 설치에 적용되는 특정 정보:

PostgreSQL 13의 바이너리는 제거되었습니다.

업그레이드를 진행하기 전에 설치가 PostgreSQL 14를 사용하고 있는지 확인해야 합니다.

만료되지 않는 액세스 토큰

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

GitLab 16.0 및 이후 버전으로 업그레이드하면, 만료 날짜가 없는 모든 개인, 프로젝트 또는 그룹 액세스 토큰은 업그레이드 날짜로부터 1년 후에 자동으로 만료 날짜가 설정됩니다.

이 자동 만료 날짜가 적용되기 전에, 중단을 최소화하기 위해 다음을 수행해야 합니다:

자세한 내용은 다음을 참조하세요:

17.1 및 이전 버전에서 업그레이드 시 주의할 사항

고객이 GitLab Duo를 사용하고 GitLab 17.2.3 또는 이전 버전으로 업그레이드하는 경우, 다음 두 가지를 모두 수행해야 합니다:
- 라이센스를 다시 동기화합니다.
- 업그레이드 후 서버를 재시작합니다.
고객이 GitLab Duo를 사용하고 GitLab 17.2.4 또는 이후 버전으로 업그레이드하는 경우, 다음 중 하나를 수행해야 합니다:
- 라이센스를 다시 동기화합니다.
- 매 24시간마다 발생하는 다음 예정된 라이센스 동기화를 기다립니다.

고객이 GitLab 17.2.4 또는 이후 버전으로 업그레이드한 후에는 향후 업그레이드 시 이러한 단계가 필요하지 않습니다.

자세한 내용은 문제 480328을 참조하세요.

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 열에 고유 제약 조건을 추가하는 데 발생하지만, 여전히 중복 항목이 존재하기 때문에 발생합니다. 이전 마이그레이션은 이러한 중복을 제거하기 위한 것이지만, 드문 경우에 두 마이그레이션 사이에 새로운 중복 항목이 삽입될 수 있습니다.

이 문제를 안전하게 해결하려면 다음 단계를 따르세요:

마이그레이션이 실행되는 Rails 콘솔을 엽니다.
아래 스크립트를 콘솔에 복사하여 붙여넣고 실행합니다.
마이그레이션을 다시 실행하면 성공적으로 완료되어야 합니다.

 # 각 cluster_agent_id에 대해 유지할 ID를 가져옵니다. 중복이 있는 경우, 최신 updated_at을 가진 행만 유지됩니다.
 latest_ids = ::RemoteDevelopment::RemoteDevelopmentAgentConfig.select("DISTINCT ON (cluster_agent_id) id")
   .order("cluster_agent_id, updated_at DESC")
   .map(&:id)

 # 제거할 remote_development_agent_configs 목록을 가져옵니다.
 agent_configs_to_remove = ::RemoteDevelopment::RemoteDevelopmentAgentConfig.where.not(id: latest_ids)

 # 모든 중복된 agent_configs를 삭제합니다.
 agent_configs_to_remove.delete_all

17.7.0

OpenSSL 3 업그레이드

GitLab 17.7로 업그레이드하기 전에 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은 TLS에 대한 보안 요구 사항을 설정하며, SSH에는 해당되지 않습니다. OpenSSH와 gitlab-sshd는 허용되는 암호화 알고리즘에 대한 자체 구성 설정을 가지고 있습니다.

자세한 내용은 설치 보안에 관한 GitLab 문서를 확인하세요.

17.5.0

OpenSSL 3 업그레이드는 GitLab 17.7.0으로 연기되었습니다.

GitLab Runner 배포 캐시에 대한 S3 객체 저장소 접근은 이제 MinIO 클라이언트 대신 AWS SDK v2 for Go로 처리됩니다.
FF_USE_LEGACY_S3_CACHE_ADAPTER GitLab Runner 기능 플래그를 true로 설정하면 MinIO 클라이언트를 다시 활성화할 수 있습니다.

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 서버의 외부 URL 구성에서 GitLab.rb 파일에 대문자가 포함된 경우 Web IDE가 로드되지 않을 수 있습니다.

이 문제를 해결하려면 OAuth 콜백 URL을 업데이트하세요.

17.3.0

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

Geo 설치

Geo 복제 세부 정보 페이지는 Geo 복제가 작동 중이라도 빈 것으로 표시됩니다. 이슈 468509 참조. 알려진 해결 방법이 없습니다. 이 버그는 GitLab 17.4에서 수정되었습니다.

영향받는 릴리즈:

영향받는 마이너 릴리즈	영향받는 패치 릴리즈	수정됨
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 설치

GitLab 16.11부터 GitLab 17.2까지, 누락된 PostgreSQL 인덱스가 높은 CPU 사용, 느린 작업 아티팩트 검증 진행 및 느리거나 시간 초과된 Geo 메트릭 상태 업데이트를 유발할 수 있습니다. 인덱스는 GitLab 17.3에서 추가되었습니다. 인덱스를 수동으로 추가하려면 Geo 문제 해결 - 작업 아티팩트 검증 중 기본에서의 높은 CPU 사용을 참조하세요.

영향을 받는 릴리스:

영향을 받는 마이너 릴리스	영향을 받는 패치 릴리스	수정됨
16.11	전체	없음
17.0	전체	17.0.7
17.1	전체	17.1.7
17.2	전체	17.2.5

Geo 복제 세부 정보 페이지는 Geo 복제가 작동하는 경우에도 비어 보입니다. 문제 468509를 참조하세요. 알려진 해결 방법은 없습니다. 이 버그는 GitLab 17.4에서 수정되었습니다.

영향을 받는 릴리스:

영향을 받는 마이너 릴리스	영향을 받는 패치 릴리스	수정됨
17.0	전체	17.0.7
17.1	전체	17.1.7
17.2	전체	17.2.5
17.3	전체	17.3.1

17.1.0

신뢰할 수 없는 extern_uid를 가진 Bitbucket ID가 삭제됩니다.
자세한 내용은 문제 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에서 수정되었습니다.

Geo 설치

영향을 받는 릴리스:

영향을 받는 마이너 릴리스	영향을 받는 패치 릴리스	수정됨
16.11	전체	없음
17.0	전체	17.0.7
17.1	전체	17.1.7
17.2	전체	17.2.5

영향을 받는 릴리스:

영향을 받는 마이너 릴리스	영향을 받는 패치 릴리스	수정됨
17.0	전체	17.0.7
17.1	전체	17.1.7
17.2	전체	17.2.5
17.3	전체	17.3.1

17.0.0

Geo 설치

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

영향받는 릴리즈:

영향받는 마이너 릴리스	영향받는 패치 릴리스	수정됨
16.11	모두	없음
17.0	모두	17.0.7
17.1	모두	17.1.7
17.2	모두	17.2.5

보조 사이트에 대한 Geo 복제 세부 정보 페이지가 빈 것으로 나타나지만, Geo 복제가 작동 중일 때도 발생합니다. 이슈 468509를 참조하세요. 알려진 해결 방법은 없습니다. 버그는 GitLab 17.4에서 수정되었습니다.

영향받는 릴리즈:

영향받는 마이너 릴리스	영향받는 패치 릴리스	수정됨
17.0	모두	17.0.7
17.1	모두	17.1.7
17.2	모두	17.2.5
17.3	모두	17.3.1

GitLab 17 변경 사항

16.11에서 업그레이드할 때 주의해야 할 사항

리눅스 패키지 설치

만료되지 않는 액세스 토큰

17.1 및 이전 버전에서 업그레이드 시 주의할 사항

17.3에서 업그레이드 시 주의할 사항

17.7.0

OpenSSL 3 업그레이드

17.5.0

17.4.0

17.3.0

Geo 설치

17.2.1

Geo 설치

17.1.0

Geo 설치

17.0.0

Geo 설치

도움말

기능 사용 가능성과 제품 평가판

도움받기