- 새로운 주요 버전으로 업그레이드
- 모든 버전의 가이드라인
- 버전별 변경 사항
- 문제 해결
컴파일된 설치 업그레이드
설치하고자 하는 GitLab의 브랜치(버전)에서 이 업그레이드 가이드를 확인하세요 (예: 16.0). GitLab 문서 페이지의 오른쪽 상단 드롭다운 목록에서 필요한 문서 버전을 선택할 수 있습니다.
다음 예제에서는 업그레이드하려는 버전의 브랜치로 BRANCH를 교체하세요 (예: 16-0-stable를 16.0로). 업그레이드하려는 이전 버전의 브랜치는 PREVIOUS_BRANCH로 교체하세요 (예: 15-11-stable를 15.11로).
최고 안정적인 브랜치가 불분명한 경우 GitLab 블로그에서 버전별 설치 가이드 링크를 확인하세요.
GitLab Community Edition에서 GitLab Enterprise Edition으로 변경하는 경우 CE에서 EE로 업그레이드하기 문서를 참조하세요.
새로운 주요 버전으로 업그레이드
주요 버전은 하위 호환성이 없는 변경 사항을 위해 예약되어 있습니다. 현재 주요 버전의 최신 사용 가능한 마이너 버전으로 먼저 업그레이드해야 합니다. 이상적인 업그레이드 경로를 확인하려면 업그레이드 권장 사항을 따르세요.
새로운 주요 버전으로 업그레이드하기 전에 이전 릴리스의 모든 백그라운드 마이그레이션 작업이 완료되었는지 확인해야 합니다. background_migration 대기열의 현재 크기를 보려면 업그레이드 전에 백그라운드 마이그레이션 확인하기를 참고하세요.
모든 버전의 가이드라인
이 섹션은 업그레이드하려는 버전에 관계없이 Community Edition 또는 Enterprise Edition을 업그레이드하는 데 필요한 모든 단계를 포함합니다. 특정 버전의 가이드라인(있는 경우)은 따로 다룹니다.
1. 백업
전제 조건:
-
rsync가 설치되어 있는지 확인하세요.
백업 수행:
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
2. 서버 중지
# systemd를 사용하는 시스템의 경우
sudo systemctl stop gitlab.target
# SysV init을 사용하는 시스템의 경우
sudo service gitlab stop
3. Ruby 업데이트
GitLab 17.5 이상에서는 Ruby 3.2.x만 지원하며 Ruby 3.1에 대한 지원은 중단되었습니다. 필요 시 업그레이드해야 합니다. ruby -v로 현재 실행 중인 버전을 확인할 수 있습니다.
4. Node.js 업데이트
필요한 최소 Node.js 버전을 확인하려면 Node.js 버전을 참조하세요.
GitLab은 JavaScript 종속성을 관리하기 위해 Yarn >= v1.10.0 사용을 요구합니다.
Debian 또는 Ubuntu에서:
sudo apt-get remove yarn
npm install --global yarn
자세한 정보는 Yarn 웹사이트를 참조하세요.
5. Go 업데이트
필요한 최소 Go 버전을 확인하려면 Go 버전을 참조하세요.
go version으로 현재 실행 중인 버전을 확인할 수 있습니다.
Linux, 64비트용 Go를 다운로드하여 설치합니다:
# 이전 Go 설치 폴더 제거
sudo rm -rf /usr/local/go
curl --remote-name --location --progress-bar "https://go.dev/dl/go1.22.5.linux-amd64.tar.gz"
echo '904b924d435eaea086515bc63235b192ea441bd8c9b198c507e85009e6e4c7f0 go1.22.5.linux-amd64.tar.gz' | shasum -a256 -c - && \
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
sudo ln -sf /usr/local/go/bin/{go,gofmt} /usr/local/bin/
rm go1.22.5.linux-amd64.tar.gz
6. Git 업데이트
최소 요구 Git 버전을 확인하려면 Git 버전을 참조하십시오.
Gitaly에서 제공하는 Git 버전을 사용하세요:
- 항상 GitLab에서 요구하는 버전입니다.
- 적절한 작동을 위한 사용자 정의 패치가 포함될 수 있습니다.
# 종속성 설치
sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential
# Gitaly 저장소 클론
git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly
# Git 컴파일 및 설치
cd /tmp/gitaly
sudo make git GIT_PREFIX=/usr/local
설치하려는 GitLab 버전에 맞는 안정적인 브랜치로 <X-Y-stable>를 교체하세요. 예를 들어, GitLab 16.7을 설치하고자 한다면, 브랜치 이름 16-7-stable을 사용하세요.
git -> bin_path를 /usr/local/bin/git로 설정하는 것을 잊지 마세요 config/gitlab.yml에서.
7. PostgreSQL 업데이트
경고: GitLab 17.0은 최소 PostgreSQL 14가 필요합니다.
최신 GitLab 버전은 현재 실행 중인 것보다 더 최근의 PostgreSQL 버전에 의존할 수 있습니다. 또한 일부 확장을 활성화해야 할 수도 있습니다. 더 많은 정보는 PostgreSQL 요구 사항을 참조하세요.
PostgreSQL을 업그레이드하려면 해당 문서를 참조하세요.
8. 최신 코드 가져오기
cd /home/git/gitlab
sudo -u git -H git fetch --all --prune
sudo -u git -H git checkout -- Gemfile.lock db/structure.sql locale
GitLab 커뮤니티 에디션의 경우:
cd /home/git/gitlab
sudo -u git -H git checkout BRANCH
또는
GitLab 엔터프라이즈 에디션의 경우:
cd /home/git/gitlab
sudo -u git -H git checkout BRANCH-ee
9. 구성 파일 업데이트
gitlab.yml의 새로운 구성 옵션
gitlab.yml)에 대한 구성 옵션이 있을 수 있습니다.
아래 명령어로 확인한 후 현재 gitlab.yml에 수동으로 적용하세요:
cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:config/gitlab.yml.example origin/BRANCH:config/gitlab.yml.example
database.yml의 새로운 구성 옵션
- 변경됨 GitLab 16.0에서
config/database.yml.postgresql에ci:섹션을 추가했습니다.
database.yml에 대한 구성 옵션이 있을 수 있습니다.
아래 명령어로 확인한 후 현재 database.yml에 수동으로 적용하세요:
cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:config/database.yml.postgresql origin/BRANCH:config/database.yml.postgresql
NGINX 구성
최신 NGINX 구성 변경 사항이 여전히 반영되었는지 확인하세요:
cd /home/git/gitlab
# HTTPS 구성용
git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab-ssl origin/BRANCH:lib/support/nginx/gitlab-ssl
# HTTP 구성용
git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab origin/BRANCH:lib/support/nginx/gitlab
설치에 Strict-Transport-Security를 사용하고 있는 경우, 이를 계속 사용하려면 NGINX 구성에서 이를 활성화해야 합니다. 이는 GitLab 애플리케이션이 더 이상 이를 설정하지 않기 때문입니다.
NGINX 대신 Apache를 사용하는 경우, 업데이트된 Apache 템플릿을 확인하세요. 또한 Apache는 유닉스 소켓 뒤에 있는 업스트림을 지원하지 않으므로 GitLab Workhorse가 TCP 포트에서 수신 대기하도록 해야 합니다. 이는 /etc/default/gitlab를 통해 할 수 있습니다.
SMTP 설정
SMTP를 사용하여 메일을 전달하는 경우, 다음 줄을 config/initializers/smtp_settings.rb에 추가해야 합니다:
ActionMailer::Base.delivery_method = :smtp
smtp_settings.rb.sample를 예로 참조하세요.
systemd 유닛 구성
SysV 초기화 스크립트를 사용하는 경우, SysV 초기화 스크립트 구성을 참조하세요.
systemd 유닛이 업데이트되었는지 확인하세요:
cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:lib/support/systemd origin/BRANCH:lib/support/systemd
유닛을 복사하세요:
sudo mkdir -p /usr/local/lib/systemd/system
sudo cp lib/support/systemd/* /usr/local/lib/systemd/system/
sudo systemctl daemon-reload
SysV 초기화 스크립트 구성
systemd 유닛을 사용하는 경우, systemd 유닛 구성을 참조하세요.
gitlab.default.example에 사용할 수 있는 새로운 구성 옵션이 있을 수 있습니다.
아래 명령으로 확인하고 현재 /etc/default/gitlab에 수동으로 적용하세요:
cd /home/git/gitlab
git diff origin/PREVIOUS_BRANCH:lib/support/init.d/gitlab.default.example origin/BRANCH:lib/support/init.d/gitlab.default.example
최신 초기화 스크립트 변경 사항이 적용되었는지 확인하세요:
cd /home/git/gitlab
sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
시스템이 systemd를 초기화로 사용 중인 경우, 아직 네이티브 systemd 유닛으로 전환하지 않았다면 다음을 실행하세요:
sudo systemctl daemon-reload
10. 라이브러리, 마이그레이션 등 설치
필요한 PostgreSQL 확장을 확보한 후, 필요한 라이브러리를 설치하세요:
cd /home/git/gitlab
# 설치 중 또는 이전 업그레이드 시에 하지 않았다면
sudo -u git -H bundle config set --local deployment 'true'
sudo -u git -H bundle config set --local without 'development test kerberos'
# 젬 업데이트
sudo -u git -H bundle install
# 선택 사항: 이전 젬 정리
sudo -u git -H bundle clean
# 데이터베이스 마이그레이션 실행
sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
# 노드 종속성 업데이트 및 자산 재컴파일
sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production NODE_OPTIONS="--max_old_space_size=4096"
# 캐시 정리
sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
11. GitLab 셸 업데이트
cd /home/git/gitlab-shell
sudo -u git -H git fetch --all --tags --prune
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION)
sudo -u git -H make build
12. GitLab 워크호스 업데이트
GitLab 워크호스를 설치하고 컴파일하세요.
cd /home/git/gitlab
sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production
13. Gitaly 업데이트
Gitaly 가 자체 서버에 위치하거나 Gitaly Cluster를 사용하는 경우 무중단 업그레이드를 참조하세요.
Gitaly 컴파일하기
빌드 프로세스 중에 Gitaly는 Git 바이너리를 컴파일하고 임베드합니다. 이는 추가적인 의존성이 필요합니다.
# 의존성 설치
sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential
# Git 으로 Gitaly 소스 가져오고 Go로 컴파일
cd /home/git/gitlab
sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production
14. GitLab Pages 업데이트
GitLab Pages를 사용하는 경우에만 필요
GitLab Pages를 설치하고 컴파일하세요. GitLab Pages는 GNU Make를 사용합니다. Linux를 사용하지 않는 경우 아래의 make 대신 gmake를 실행해야 할 수 있습니다.
cd /home/git/gitlab-pages
sudo -u git -H git fetch --all --tags --prune
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make
15. 애플리케이션 시작
# systemd가 실행되는 시스템의 경우
sudo systemctl start gitlab.target
sudo systemctl restart nginx.service
# SysV init가 실행되는 시스템의 경우
sudo service gitlab start
sudo service nginx restart
16. 애플리케이션 상태 확인
GitLab과 그 환경이 올바르게 구성되었는지 확인하세요:
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
누락된 것이 없는지 더 철저한 점검을 실행하세요:
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
모든 항목이 녹색이면 축하합니다. 업그레이드가 완료되었습니다!
버전별 변경 사항
버전 업그레이드는 수동 개입이 필요할 수 있습니다. 자세한 내용은 다음을 참조하세요:
문제 해결
1. 코드 이전 버전으로 롤백하기
이전 버전으로 롤백하려면 이전 버전에 대한 업그레이드 가이드를 따라야 합니다.
예를 들어, GitLab 16.6으로 업그레이드한 후 16.5로 롤백하려면 16.4에서 16.5로의 업그레이드 가이드를 따르세요. 페이지 상단의 버전 드롭다운 목록을 사용하여 적절한 버전을 선택할 수 있습니다.
롤백 시 데이터베이스 마이그레이션 가이드를 따르지 말아야 하며, 왜냐하면 백업이 이미 이전 버전으로 마이그레이션되었기 때문입니다.
2. 백업에서 복원하기
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
백업 *.tar 파일이 여러 개 있는 경우 위에 BACKUP=timestamp_of_backup을 추가하세요.
도움말