Ubuntu veya Debian'a yerleşik Let's Encrypt ile GitLab CE nasıl kurulur

GitLab Community Edition (CE); Git depolarını, merge request'leri, issue'ları, CI/CD hatlarını ve konteyner ile paket kayıtlarını kendi yönettiğiniz tek bir uygulamada bir araya getirir. Resmi Linux paketi GitLab'i PostgreSQL, Redis, Gitaly, Puma, Sidekiq ve NGINX ile birlikte getirir; hepsini tek bir dosya olan /etc/gitlab/gitlab.rb üzerinden yapılandırırsınız.

Bu rehber GitLab CE'yi Ubuntu veya Debian'a GitLab'in kendi paket deposundan kurar, Let's Encrypt sertifikasını GitLab'in kendisine aldırır, root hesabını ve kayıtları güvenceye alır; ardından yedeklemeyi, GitLab'in zorunlu yükseltme duraklarına uygun yükseltmeleri ve tek bir sunucuda en sık karşılaşacağınız sorunları ele alır.

Adım 1 — Güvenlik duvarını açın

GitLab'in kurulum sayfaları SSH'yi etkinleştirir ve ufw'de SSH, HTTP ve HTTPS'i açar. 22 portu SSH üzerinden Git trafiğini de taşır:

sudo systemctl enable --now ssh
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Docker tabanlı uygulamaların aksine GitLab'in NGINX'i doğrudan ana makinede çalışır; bu yüzden ufw kuralları ona normal şekilde uygulanır. SSH servisiniz başka bir portta dinliyorsa ufw'yi etkinleştirmeden önce 22 yerine o porta izin verin.

Adım 2 — GitLab'in paket deposunu ekleyin

GitLab, apt deposunu yapılandıran bir betik sunar. curl kurun, betiği indirin, okuyun ve çalıştırın:

sudo apt update
sudo apt install -y curl
curl --location "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh" -o gitlab-ce-repo.sh
less gitlab-ce-repo.sh
sudo bash gitlab-ce-repo.sh

Betik şunları yapar:

• dağıtımınızı ve kod adını /etc/os-release dosyasından algılar;
• apt-transport-https paketini, gpg yoksa gnupg paketini, Debian'da da debian-archive-keyring paketini kurar;
• sürümünüze ait depo tanımını /etc/apt/sources.list.d/gitlab_gitlab-ce.list dosyasına indirir;
• GitLab'in imza anahtarını indirir, dönüştürür ve /etc/apt/keyrings/gitlab_gitlab-ce-archive-keyring.gpg olarak kaydeder;
• apt-get update çalıştırır ve başarısız olursa hata vererek durur.

apt'nin GitLab CE'yi artık GitLab deposundan sunduğunu kontrol edin:

apt-cache policy gitlab-ce

Candidate satırı en yeni sürümü gösterir; kaynak packages.gitlab.com olmalıdır.

Adım 3 — GitLab CE'yi HTTPS ile kurun

Genel adresinizi EXTERNAL_URL ile verin. Adres https:// ile başladığı için GitLab ilk yapılandırma sırasında bir Let's Encrypt sertifikası ister:

sudo EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ce

Kurulum ve ilk gitlab-ctl reconfigure çalıştırması birkaç dakika sürer. GitLab aynı komut satırında GITLAB_ROOT_EMAIL ve GITLAB_ROOT_PASSWORD (en az 8 karakter) değerlerini de kabul eder; ancak yalnızca ilk kurulumda ve bu durumda parola kabuk geçmişinize düşer. Adım 4'teki üretilmiş parola bunu önler. GitLab geçerli bir ana makine adı algılayamazsa reconfigure kendiliğinden çalışmaz; bu durumda aynı değişkenleri sudo gitlab-ctl reconfigure komutuna verin.

Servisleri ve siteyi kontrol edin:

sudo gitlab-ctl status
curl -I https://gitlab.example.com

Her servis satırı run: ile başlar. curl geçerli bir sertifika üzerinden giriş sayfasına yönlendirme döndürür. Puma başlarken ilk bir iki dakika 502 sayfası görmek normaldir.

Adım 4 — root olarak giriş yapın

GitLab rastgele bir root parolası üretir ve 24 saat boyunca saklar:

sudo cat /etc/gitlab/initial_root_password

https://gitlab.example.com adresini açın, bu parolayla root olarak giriş yapın ve hemen:

1. Kullanıcı ayarlarınızda Password bölümünden yeni ve uzun bir parola belirleyin.
2. root hesabının e-posta adresini okuduğunuz bir adresle değiştirin.
3. Hesap için iki adımlı doğrulamayı açın.

GitLab 24 saat sonra dosyayı kendiliğinden siler. Parolayı kaybederseniz sorun giderme bölümü nasıl sıfırlayacağınızı gösterir.

Adım 5 — Kayıtları kısıtlayın ve sertifika iletişim adresini ayarlayın

Varsayılan olarak GitLab'inize ulaşabilen herkes hesap isteyebilir; yeni instance'lar bu kayıtlar için yönetici onayı ister. Yalnızca davet ettiğiniz kişilerin hesabı olacaksa kaydı kapatın:

1. Sağ üst köşede Admin seçin.
2. Sol kenar çubuğunda Settings ve ardından General seçin.
3. New user account restrictions bölümünü genişletin.
4. Allow new user accounts kutusunun işaretini kaldırın ve Save changes seçin.

Bundan sonra hesapları Admin, Users altından kendiniz oluşturun.

Ardından Let's Encrypt'e süre bitimi uyarılarını nereye göndereceğini bildirin. Yapılandırma dosyasını açın:

sudo nano /etc/gitlab/gitlab.rb

Şu satırı ekleyin veya düzenleyin:

letsencrypt['contact_emails'] = ['[email protected]']

Değişikliği uygulayın:

sudo gitlab-ctl reconfigure

GitLab sertifikayı kendi zamanlamasıyla yeniler (varsayılan olarak her ayın 4'ünde gece yarısından sonra); Certbot çalıştırmanız gerekmez.

GitLab hesap onaylarını, parola sıfırlamalarını, davetleri ve bildirimleri e-postayla gönderir; bunları relay'iniz üzerinden göndermek için aynı gitlab.rb dosyasında GitLab'in SMTP ayarları sayfasında gösterildiği gibi gitlab_rails['smtp_enable'] = true, smtp_address (smtp.example.com), smtp_port (587), smtp_user_name, smtp_password ve smtp_enable_starttls_auto = true değerlerini ayarlayın, ardından sudo gitlab-ctl reconfigure çalıştırın.

Adım 6 — GitLab'i daha küçük bir sunucu için ayarlayın (isteğe bağlı)

Sunucunuzda 16 GB'lık temel değerden az bellek varsa GitLab, kısıtlı bellek ortamları için ayarlar belgeler. En etkili olanlar /etc/gitlab/gitlab.rb dosyasına girer:

puma['worker_processes'] = 0
sidekiq['concurrency'] = 10
prometheus_monitoring['enable'] = false

Ardından sudo gitlab-ctl reconfigure çalıştırın. Bu ayarlarla ilk çalıştırma biraz sürebilir. Daha ileri gitmeniz gerekirse GitLab'in kısıtlı bellek ortamları sayfası Gitaly eşzamanlılık sınırlarını ve bellek ayırıcı ayarlarını da anlatır.

Yedekleme ve geri yükleme

Bir GitLab yedeği iki parçadan oluşur. gitlab-backup aracı veritabanını, depoları ve yüklenen dosyaları /var/opt/gitlab/backups içinde bir .tar dosyasına arşivler. /etc/gitlab içindeki yapılandırmayı ve özellikle veritabanında saklanan değerleri çözen anahtarları tutan gitlab-secrets.json dosyasını içermez. İkisini de yedekleyin:

sudo gitlab-backup create
sudo ls -lh /var/opt/gitlab/backups
sudo mkdir -p /opt/backups
sudo tar czf /opt/backups/gitlab-etc-$(date +%F).tar.gz /etc/gitlab

Yapılandırma arşivini veri yedeklerinden farklı bir yerde saklayın; ikisi birlikte verilerinize tam erişim sağlar. Yoğun instance'larda yedek file changed as we read it hatası verirse, aynı miktarda ek disk alanına kadar ihtiyaç duyan sudo gitlab-backup create STRATEGY=copy komutunu kullanın.

Her gece 02:00'de yedek almak için sudo crontab -e ile root'un crontab'ına şu satırı ekleyin:

0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1

Yerel arşivlerin ne kadar tutulacağını gitlab.rb içinde gitlab_rails['backup_keep_time'] = 604800 (yedi gün) ile sınırlayın. GitLab ayrıca backup_upload_connection ayarlarıyla her arşivi S3 uyumlu depolamaya yükleyebilir. Her durumda yedekleri sunucunun dışına kopyalayın.

Geri yükleme. Yalnızca aynı gitlab-ce paketinden kurulmuş, tam olarak aynı GitLab sürümüne geri yükleme yapabilirsiniz. O sürümü kurun, kayıtlı /etc/gitlab/gitlab-secrets.json ve gitlab.rb dosyalarınızı yerlerine koyun ve sudo gitlab-ctl reconfigure çalıştırın. Ardından arşivi yedek klasörüne kopyalayın ve Puma ile Sidekiq durdurulmuşken geri yükleyin. Kendi arşiv adınızı kullanın; BACKUP değeri, _gitlab_backup.tar olmadan addır.

sudo cp 1791500000_2026_10_09_19.4.1-ce_gitlab_backup.tar /var/opt/gitlab/backups/
sudo chown git:git /var/opt/gitlab/backups/1791500000_2026_10_09_19.4.1-ce_gitlab_backup.tar
sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
sudo gitlab-ctl status
sudo gitlab-backup restore BACKUP=1791500000_2026_10_09_19.4.1-ce
sudo gitlab-ctl reconfigure
sudo gitlab-ctl start
sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor:secrets

Son komut, geri yüklenen secrets dosyasının veritabanındaki değerleri çözebildiğini doğrular.

GitLab yükseltme

GitLab her ay yeni bir ara sürüm yayınlar ve bazı sürümler, ilerlemeden önce kurmanız gereken zorunlu yükseltme duraklarıdır: GitLab 18'de 18.2, 18.5, 18.8 ve 18.11; GitLab 19'da 19.2, 19.5, 19.8 ve 19.11 (sonraki duraklar henüz yayınlanmamış olabilir). GitLab'in Upgrade Path aracı, başlangıç noktanıza göre tam sürümleri listeler. Her durakta devam etmeden önce arka plan geçişlerinin bitmesini bekleyin.

Paket yükseltmeden önce otomatik bir veritabanı yedeği alır; ancak GitLab yine de kendi tam ve güncel yedeğinizi tutmanızı ister. Belirli bir sürüme tipik bir yükseltme şöyledir:

sudo gitlab-backup create
sudo apt update
apt-cache madison gitlab-ce
sudo apt install gitlab-ce=19.4.1-ce.0
sudo gitlab-rake gitlab:background_migrations:list

apt-cache madison depodaki sürümleri listeler; 19.4.1-ce.0 yerine hedef sürümünüzü yazın. Son komut (GitLab 18.9 ve sonrası) bekleyen arka plan geçişlerini gösterir; bunları Admin, Monitoring, Background migrations altından da kontrol edebilirsiniz. Yükseltme sürerken tek düğümlü bir sunucu bir dağıtım mesajı veya 502 sayfası gösterir.

Sorun giderme

Kurulum, yeniden başlatma veya yükseltmeden hemen sonra 502 hatası

Puma hâlâ başlıyor; küçük bir sunucuda bu bir dakika veya daha uzun sürebilir. sudo gitlab-ctl status ile kontrol edin ve logları sudo gitlab-ctl tail puma ile izleyin. 502 sürerse belleği free -h ile kontrol edin. GitLab Workhorse, tek bir istek bir dakikadan uzun sürdüğünde de 502 döndürür; çok yavaş sayfalar için gitlab.rb içinde gitlab_workhorse['proxy_headers_timeout'] değerini artırabilirsiniz.

Let's Encrypt reconfigure sırasında başarısız oluyor

Let's Encrypt sunucuya EXTERNAL_URL içindeki adla 80 ve 443 portlarından ulaşmalıdır. DNS kaydını kontrol edin, iki portu da ufw'de ve varsa sağlayıcı güvenlik duvarında açın, ardından sudo gitlab-ctl reconfigure komutunu yeniden çalıştırın. Daha sonra yenilemeyi sudo gitlab-ctl renew-le-certs ile zorlayabilirsiniz.

Errno::ENOMEM: Cannot allocate memory during backup or upgrade

GitLab bu işler için yaklaşık 2 GB boş belleğe ihtiyaç duyar. Sunucu normal çalışırken zaten swap kullanıyorsa bellek ekleyin; kullanmıyorsa swap eklemek yedeği veya yükseltmeyi tamamlamak için yeterli olabilir.

PostgreSQL could not create shared memory segment hatası veriyor

Paketle gelen PostgreSQL sunucu belleğinin %25'ini ayırmaya çalışır. gitlab.rb içinde postgresql['shared_buffers'] = "100MB" ayarlayın ve sudo gitlab-ctl reconfigure çalıştırın.

reconfigure undefined method for nil:NilClass hatasıyla duruyor

gitlab.rb dosyası, genellikle bir yükseltmeden sonra, geçersiz veya artık kullanılmayan bir ayar içeriyor. Dosyanızı güncel şablonla sudo gitlab-ctl diff-config ile karşılaştırın, ayarı düzeltin ve reconfigure komutunu yeniden çalıştırın.

İlk root parolası çalışmıyor veya dosya silinmiş

Dosya 24 saat sonra silinir. root parolasını GitLab'in Rake göreviyle sıfırlayın ve yeni parolayı iki kez girin:

sudo gitlab-rake "gitlab:password:reset[root]"

Sonraki adımlar

• Daha hafif bir Git sunucusu için Forgejo veya Gitea ile karşılaştırın.
• Uygulamaları depolarınızdan Coolify veya Dokploy ile dağıtın.
• GitLab için boyutlandırılmış sunuculara GitLab hosting sayfasında göz atın.
• Runner'lar, e-posta gönderimi ve konteyner kaydı için resmi GitLab belgelerini okuyun.