16.11에서 업그레이드할 때 주의할 사항
- Linux 패키지 설치
- 기한이 없는 액세스 토큰
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 차트를 업그레이드하는 자세한 정보는 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 16.x에서 직접 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로 직접 업그레이드하면 이러한 문제가 발생하지 않습니다.

Linux 패키지 설치

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

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비트의 보안을 가져야 합니다. RSA, DSA 및 2048비트 미만의 DH 키, 224비트 미만의 ECC 키가 금지됩니다.

LDAP 및 Webhook 서버와 같은 이전 서비스는 아직 TLS 1.1을 사용할 수 있습니다. 그러나 TLS 1.0 및 1.1은 End-of-Life에 도달하여 더 이상 안전하게 간주되지 않습니다. GitLab은 TLS 1.0 또는 1.1을 사용하는 서비스에 연결할 수 없으며 “프로토콜을 사용할 수 없음” 오류 메시지가 표시됩니다.

또한, OpenSSL 3은 기본 보안 수준을 레벨 1에서 2로 증가시켰으며, 최소 보안 비트 수를 80에서 112로 높였습니다. 이로 인해 2048비트 미만의 RSA 및 DSA 키, 그리고 224비트 미만의 ECC 키로 서명된 인증서가 금지되었습니다.

보안 수준이 높아진 OpenSSL 3으로 인해 출시된 Linux 패키지의 모든 구성 요소는 호환됩니다. 따라서 GitLab 패키지의 일부가 아닌 외부 “external” 및 통합을 확인해야 합니다.

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

보다 자세한 내용은 설치 보안 가이드의 GitLab 설치 보안 문서를 확인하세요.

17.5.0

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

GitLab Runner 분산 캐시의 S3 객체 저장소 액세스는 이제 AWS SDK v2 for Go로 처리됩니다. MinIO 클라이언트가 아닙니다. 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 또는 그 이전 버전을 설치하세요. 그런 다음 기존 환경과 동일한 데이터베이스 마이그레이션을 수행하기 위해 나중에 릴리스로 업그레이드하면 됩니다. 새로운 환경으로 복원하는 경우에는 데이터베이스 복원이 기존의 데이터베이스 스키마 정의를 제거하고 백업의 일부로 저장된 정의를 사용하기 때문에 이 단계는 필요하지 않습니다.
Gitaly에는 Git 2.46.0 이상이 필요합니다. 소스에서 설치하는 경우 Gitaly에서 제공하는 Git 버전을 사용해야 합니다.
Workhorse에서의 S3 객체 스토리지 업로드는 이제 기본적으로 AWS SDK v2 for Go를 이용하여 처리됩니다. S3 객체 스토리지 업로드에 문제가 있는 경우 workhorse_use_aws_sdk_v2 기능 플래그를 비활성화하여 v1로 다운그레이드할 수 있습니다.
GitLab 17.4로 업그레이드하면 Web IDE를 위해 OAuth 애플리케이션이 생성됩니다. GitLab 서버의 GitLab.rb 파일에서 외부 URL 구성이 대문자를 포함하고 있다면, Web IDE가 로드되지 않을 수 있습니다. 이 문제를 해결하려면 OAuth 콜백 URL을 업데이트해보세요.

17.3.0

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

Geo 설치

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.0	전체	17.0.7
17.1	전체	17.1.7
17.2	전체	17.2.5
17.3	전체	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부터 17.2까지는 누락된 PostgreSQL 인덱스로 인해 높은 CPU 사용량, 느린 작업 아티팩트 검증 진행, 느린 또는 시간 초과된 Geo 메트릭 상태 업데이트가 발생할 수 있습니다. 이 인덱스는 GitLab 17.3에 추가되었습니다. 수동으로 인덱스를 추가하려면 Geo Troubleshooting - High CPU usage on primary during job artifact verification를 참조하세요.
영향 받는 릴리스:

영향을 받는 소수 릴리스 영향을 받는 패치 릴리스 수정 버전

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

영향을 받는 소수 릴리스	영향을 받는 패치 릴리스	수정 버전
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.1.0

신뢰되지 않는 extern_uid를 가진 Bitbucket 신원은 삭제됩니다. 자세한 내용은 issue 452426를 참조하십시오.
기본 changelog 템플릿은 GitLab 특정 참조 대신 완전한 URL로 링크를 생성합니다. 자세한 내용은 merge request 155806를 참조하십시오.
Gitaly에는 Git 2.44.0 이상이 필요합니다. Self-Compiled 설치의 경우 Gitaly에서 제공하는 Git 버전을 사용해야 합니다.
GitLab 17.1.0 또는 17.1.1로 업그레이드하거나 GitLab 17.0에서 완료되지 않은 백그라운드 마이그레이션이 있는 경우 마이그레이션 실행 중에 실패할 수 있습니다. 이것은 버그 때문입니다. 이슈 468875는 GitLab 17.1.2에서 수정되었습니다.

Geo 설치

GitLab 16.11부터 GitLab 17.2까지 누락된 PostgreSQL 인덱스로 인해 높은 CPU 사용량, 작업 아티팩트 검증 진행이 느려지거나 실패하며 Geo 메트릭 상태 업데이트가 느리거나 타임아웃 될 수 있습니다. 이 인덱스는 GitLab 17.3에 추가되었습니다. 인덱스를 수동으로 추가하려면 Geo Troubleshooting - High CPU usage on primary during job artifact verification를 참조하십시오.
영향을 받는 릴리스:

영향을 받는 마이너 릴리스 영향을 받는 패치 릴리스 수정 버전

16.11 All None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
보조 사이트의 Geo 복제 세부정보 페이지는 Geo 복제가 작동 중이더라도 비어 보일 수 있으며, issue 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

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

영향을 받는 마이너 릴리스	영향을 받는 패치 릴리스	수정 버전
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 설치

GitLab 16.11부터 GitLab 17.2까지 누락된 PostgreSQL 인덱스로 인해 높은 CPU 사용량, 작업 아티팩트 검증 진행이 느려지거나 실패하며 Geo 메트릭 상태 업데이트가 느리거나 타임아웃 될 수 있습니다. 이 인덱스는 GitLab 17.3에 추가되었습니다. 인덱스를 수동으로 추가하려면 Geo Troubleshooting - High CPU usage on primary during job artifact verification를 참조하십시오.
영향을 받는 릴리스:

영향을 받는 마이너 릴리스 영향을 받는 패치 릴리스 수정 버전

16.11 All None
17.0 All 17.0.7
17.1 All 17.1.7
17.2 All 17.2.5
보조 사이트의 Geo 복제 세부정보 페이지는 Geo 복제가 작동 중이더라도 비어 보일 수 있으며, issue 468509를 참조하십시오. 알려진 해결 방법은 없습니다. 이 버그는 GitLab 17.4에서 수정되었습니다.

GitLab 17 변경 사항

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

Linux 패키지 설치

기한이 없는 액세스 토큰

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 설치

도움말

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

도움받기