- 새 주 버전으로 업그레이드
- 모든 버전에 대한 지침
- 버전별 변경 사항
- 문제 해결
자체 컴파일 설치 업그레이드
GitLab 문서 페이지의 오른쪽 상단의 드롭다운 목록에서 필요한 버전의 문서를 선택할 수 있습니다.
다음의 각 예제에서, BRANCH를 설치할 버전의 브랜치(예: 16.0의 경우 16-0-stable)로 교체합니다. PREVIOUS_BRANCH는 업그레이드할 버전의 브랜치 (예: 15.11의 경우 15-11-stable)로 교체합니다.
가장 높은 숫자의 stable 브랜치가 불분명한 경우, 설치 가이드 링크를 확인하기 위해 GitLab 블로그를 참조하세요.
GitLab Community Edition에서 GitLab Enterprise Edition로 변경하는 경우 CE에서 EE로 업그레이드 문서를 참조하세요.
새 주 버전으로 업그레이드
주 버전은 하위 호환되지 않는 변경을 위해 예약됩니다. 현재 주 버전의 최신 마이너 버전으로 우선 업그레이드해야 합니다. 이상적인 업그레이드 경로를 식별하기 위해 업그레이드 권장사항을 따르세요.
새 주 버전으로 업그레이드하기 전에, 이전 릴리스에서의 백그라운드 마이그레이션 작업이 완료되었는지 확인해야 합니다. background_migration 큐의 현재 크기를 확인하려면 background migrations을 업그레이드하기 전에 확인하기 합니다.
모든 버전에 대한 지침
이 섹션에는 업그레이드에 필요한 모든 단계가 포함되어 있으며, 업그레이드하는 버전과 상관없이 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로 확인할 수 있습니다.
Ruby 설치를 참조하세요.
4. Node.js 업데이트
최소 요구 사항인 Node.js 버전을 확인하려면 Node.js versions를 참조하세요.
GitLab은 JavaScript 종속성을 관리하기 위해 Yarn >= v1.10.0을 사용합니다.
Debian 또는 Ubuntu에서:
sudo apt-get remove yarn
npm install --global yarn
자세한 정보는 Yarn 웹사이트에서 확인할 수 있습니다.
5. Go 업데이트
최소 요구 Go 버전을 확인하려면 Go versions를 참조하세요.
사용 중인 버전은 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 versions를 참조하세요.
GitLab이 필요로 하는 버전이 항상 제공됩니다. 올바른 작동에 필요한 사용자 지정 패치가 포함될 수 있습니다.
# 의존성 설치
sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential
# Gitaly에서 제공하는 Git 버전 사용
sudo git 클론 https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly
# Git 컴파일 및 설치
cd /tmp/gitaly
sudo make git GIT_PREFIX=/usr/local
<X-Y-stable>을 사용하려는 GitLab 버전과 일치하는 stable 브랜치로 교체하세요. 예를 들어, GitLab 16.7을 설치하려면 16-7-stable 브랜치를 사용하세요.
config/gitlab.yml에서 git -> bin_path를 /usr/local/bin/git로 설정하는 것을 잊지 마세요.
7. PostgreSQL 업데이트
경고: GitLab 17.0에서는 적어도 PostgreSQL 14가 필요합니다.
GitLab의 최신 버전은 실행 중인 PostgreSQL 버전보다 더 최신의 PostgreSQL 버전을 필요로 할 수 있습니다. 일부 확장 기능을 사용하도록 설정해야 할 수도 있습니다. 자세한 내용은 PostgreSQL requirements를 참조하세요.
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 Community Edition의 경우:
cd /home/git/gitlab
sudo -u git -H git checkout BRANCH
또는
GitLab Enterprise Edition의 경우:
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 init 스크립트를 사용하는 경우, SysV init 스크립트 구성을 확인하세요.
시스템의 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 init 스크립트 구성
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
최신 init 스크립트 변경 사항을 확인하세요.
cd /home/git/gitlab
sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
systemd를 init으로 사용중인 시스템에서 init 스크립트를 사용할 경우, 아래 명령어를 실행하세요.
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 Shell 업데이트
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 Workhorse 업데이트
GitLab Workhorse를 설치하고 컴파일하세요.
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를 사용하는 경우, Zero-downtime upgrades를 확인하세요.
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를 사용합니다.
리눅스를 사용하지 않는 경우 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=백업_타임스탬프를 추가하세요.
도움말