자체 컴파일 설치 업그레이드

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

GitLab 설치의 브랜치(version)에서 이 업그레이드 가이드를 확인하세요. (예: 16.0). 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 큐의 크기를 보려면 업그레이드 전 백그라운드 마이그레이션 확인을 참조하세요.

모든 버전에 대한 지침

이 섹션에는 버전에 관계없이 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 16.7부터는 Ruby 3.1.x만 지원하며 Ruby 3.0 지원을 중단했습니다. 필요한 경우 업그레이드하세요. 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.20.8.linux-amd64.tar.gz"
echo 'cc97c28d9c252fbf28f91950d830201aa403836cbed702a05932e63f7f0c7bc4  go1.20.8.linux-amd64.tar.gz' | shasum -a256 -c - && \
  sudo tar -C /usr/local -xzf go1.20.8.linux-amd64.tar.gz
sudo ln -sf /usr/local/go/bin/{go,gofmt} /usr/local/bin/
rm go1.20.8.linux-amd64.tar.gz

6. Git 업데이트

최소 필요한 Git 버전을 확인하려면 Git versions을 참조하세요.

GitLab에서 요구하는 버전에 항상 해당하는 Gitaly가 제공하는 Git 버전을 사용합니다. 필요한 경우 올바른 작동을 위해 사용되는 사용자 지정 패치를 포함할 수 있습니다. 

# 의존성 설치
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

<X-Y-stable>을 원하는 GitLab 버전에 맞는 stable 브랜치 이름으로 대체하세요. 예를 들어, GitLab 16.7을 설치하려면 16-7-stable이라는 브랜치 이름을 사용하세요. config/gitlab.yml에서 git -> bin_path를 /usr/local/bin/git로 설정하세요.

7. PostgreSQL 업데이트

caution
GitLab 16.0은 최소 PostgreSQL 13을 필요로 합니다.

최신 버전의 GitLab은 실행 중인 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의 새로운 구성 옵션

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는 Unix 소켓 뒤의 업스트림을 지원하지 않기 때문에 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 이닛 스크립트 구성을 참고하세요.

시스템드 유닛이 업데이트되었는지 확인하세요: 

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 units 구성을 참고하세요.

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

시스템드를 이닛으로 사용 중인 시스템에서 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 클러스터를 사용하고 있다면, Zero-downtime upgrades를 참고하세요.

Gitaly 컴파일 

# 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를 사용하지 않는 경우 아래 명령 대신 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. 애플리케이션 시작 

# 시스템드를 사용하는 시스템
sudo systemctl start gitlab.target
sudo systemctl restart nginx.service

# SysV 이닛을 사용하는 시스템
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

만약 모든 항목이 초록색이라면, 축하합니다. 업그레이드가 완료되었습니다!

버전별 변경 사항

버전 업그레이드에는 몇 가지 매뉴얼 개입이 필요할 수 있습니다. 자세한 정보는 업그레이드하는 버전의 추가 단계를 확인하십시오. 모든 GitLab 설치에 적용되는 단계와 소스로 설치된 설치에 적용되는 단계를 확인하세요.

문제 해결

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을 추가하세요.