GitLab, dünya genelinde binlerce ekip tarafından kullanılan popüler bir kod depolama ve DevOps süreçlerini yönetme platformudur. Ancak, GitLab'a erişim sağlayıcının, kurumsal ağın veya bir ülkenin düzeyinde engellendiyse ne yapmalısınız? Daha da kötüsü, CI/CD boru hattı gece yarısı çöküyorsa, çünkü runner, depoya ulaşamıyor.
Bu makalede, Git istemcisi, GitLab Runner ve kurumsal sunucu düzeyinde GitLab için proxy nasıl ayarlanacağını inceleyeceğiz — böylece tüm ekip dünyanın herhangi bir yerinden istikrarlı bir şekilde çalışabilir.
GitLab için proxy neden gereklidir: gerçek senaryolar
Proxy ayarlamadan önce, hangi sorunu çözmeye çalıştığınızı anlamak önemlidir. Farklı durumlar vardır ve bu, proxy türü ve bağlantı yöntemini seçmenizi etkiler.
Senaryo 1: GitLab sağlayıcı tarafından veya ülke düzeyinde engellendi
Bazı ülkelerde ve kurumsal ağlarda gitlab.com'a erişim kısıtlanmıştır. Geliştirici terminali açar, git pull yazar — ve zaman aşımına uğrar. Bu durumda proxy, aracı olarak çalışır: trafik doğrudan gitlab.com'a değil, kısıtlamaların olmadığı bir ülkedeki ara sunucu üzerinden gider.
Senaryo 2: Farklı ülkelerde dağıtılmış ekip
Hayal edin: ekibin bir kısmı Rusya'dan, bir kısmı Kazakistan'dan, bir kısmı Avrupa'dan çalışıyor. Herkesin farklı ağ koşulları ve kısıtlamaları var. Herkesin istikrarlı ve aynı hızda çalışabilmesi için şirketler, tüm trafiğin GitLab'a tek bir kanaldan gitmesi için kurumsal bir proxy sunucusu kurar.
Senaryo 3: CI/CD runner dış bağımlılıklara ulaşamıyor
GitLab Runner bir boru hattı başlatır ve npm install veya pip install aşamasında her şey çöküyor — çünkü runner'ın çalıştığı sunucu, internete doğrudan erişimi olmayan kapalı bir ağda bulunuyor. Proxy, runner'ın dış bağımlılıkları almasına olanak tanır, tüm sunucu için internete tam erişim açmadan.
Senaryo 4: Kurumsal güvenlik duvarının arkasında kendi barındırdığınız GitLab
Şirket, kendi GitLab sunucusunu iç ağda tutuyor. Uzaktan çalışan geliştiricilerin buna bağlanması gerekiyor. Tüm trafik için VPN yerine yalnızca GitLab trafiği için proxy ayarlamak — daha hızlı ve yönetimi daha kolaydır.
Senaryo 5: Trafiği izleme ve denetleme
Büyük şirketler, etkinliği kaydetmek, kimin neyi pushladığını kontrol etmek ve istenmeyen işlemleri engellemek için tüm trafiği kurumsal proxy üzerinden yönlendirir. Bu, bir güvenlik gereksinimidir, engelleri aşmak için değil.
Ayarlamadan önce anlamak önemlidir:
GitLab için proxy, aynı anda üç düzeyde gerekli olabilir: geliştirici makinesinde (Git istemcisi), GitLab Runner ile sunucuda (CI/CD) ve kendi GitLab sunucusunda (eğer kendi barındırıyorsanız). Her düzey ayrı ayrı ayarlanır.
GitLab için hangi proxy türü uygundur
GitLab, HTTPS ve SSH protokolleri üzerinden çalışır. Bu, hangi proxy türlerinin uygulanabilir olduğunu hemen belirler. Seçenekleri inceleyelim.
| Proxy Türü | Protokol | GitLab için Uygun | Ne Zaman Kullanmalı |
|---|---|---|---|
| HTTP/HTTPS Proxy | HTTP, HTTPS | ✓ Evet | Git over HTTPS, GitLab web arayüzü |
| SOCKS5 Proxy | TCP (herhangi) | ✓ Evet (en iyi seçenek) | Git over HTTPS ve SSH, CI/CD |
| SOCKS4 Proxy | TCP | ~ Kısmen | Yalnızca SOCKS5 yoksa |
| Şeffaf Proxy | HTTP | ✗ Hayır | Uygun değil — engelleri aşmaz |
GitLab ile çalışmak için en iyi seçim SOCKS5'dir. TCP düzeyinde çalıştığı için hem HTTPS bağlantılarını (web arayüzü, HTTPS üzerinden git clone) hem de SSH bağlantılarını (SSH üzerinden git push/pull, 22 veya 443 numaralı portta) eşit derecede iyi bir şekilde proxy'ler.
Yerleşik vs veri merkezi proxy'leri için GitLab
Burada her şey amaca bağlıdır. Amaç, GeoIP engelini aşmak veya kimlik doğrulama için kararlı bir IP almaksa, veri merkezi proxy'leri uygundur — daha hızlı, daha ucuz ve düşük gecikme sağlar, bu da büyük depolarla çalışırken kritik öneme sahiptir.
Ancak, kurumsal IP'niz GitLab'ın engel listesine düştüyse (agresif tarama veya güvenlik olayları sonrası olabilir), o zaman yerleşik proxy'leri düşünmelisiniz — IP adresleri gerçek ev kullanıcılarına aittir ve platformlar tarafından çok nadir engellenir.
Git istemcisi için proxy ayarlama (genel)
Bu en yaygın senaryodur: geliştirici kendi makinesinde GitLab'a bağlanamaz. Ayar, Git'in kendi yapılandırması aracılığıyla yapılır — bir kez ve tüm depolar için geçerlidir.
Seçenek A: Git için HTTPS proxy
Eğer GitLab ile HTTPS üzerinden çalışıyorsanız (depo adresi https:// ile başlıyorsa), terminalde şu komutları çalıştırın:
# HTTP proxy'yi genel olarak ayarlayın git config --global http.proxy http://PROXY_IP'NİZ:PORT # Eğer proxy kimlik doğrulama gerektiriyorsa git config --global http.proxy http://KULLANICI_ADI:ŞİFRE@PROXY_IP'NİZ:PORT # SOCKS5 proxy için (önerilir) git config --global http.proxy socks5://PROXY_IP'NİZ:PORT # Ayarın uygulandığını kontrol edin git config --global --get http.proxy
Seçenek B: Sadece gitlab.com için proxy (diğer depoları etkilemez)
Eğer proxy'nin tüm Git işlemlerine uygulanmasını istemiyorsanız (örneğin, GitHub veya Bitbucket düzgün çalışıyorsa), yalnızca belirli bir alan adı için proxy ayarlayabilirsiniz:
# Sadece gitlab.com için proxy git config --global http.https://gitlab.com.proxy socks5://PROXY_IP'NİZ:PORT # Veya kendi barındırdığınız GitLab için git config --global http.https://git.yourcompany.com.proxy socks5://PROXY_IP'NİZ:PORT
Seçenek C: Proxy üzerinden SSH (SSH ile çalışanlar için)
Eğer depoları SSH üzerinden klonluyorsanız ([email protected]:...), proxy ayarı SSH yapılandırmasında yapılır, Git'te değil. ~/.ssh/config dosyasını açın ve ekleyin:
# Linux/macOS için — nc (netcat) üzerinden
Host gitlab.com
HostName gitlab.com
User git
ProxyCommand nc -X 5 -x PROXY_IP'NİZ:PORT %h %p
# Windows için — connect.exe (Git for Windows) üzerinden
Host gitlab.com
HostName gitlab.com
User git
ProxyCommand connect -S PROXY_IP'NİZ:PORT %h %p
Ayarladıktan sonra bağlantıyı ssh -T [email protected] komutuyla kontrol edin. Her şey doğru ayarlandıysa, GitLab'dan bir hoş geldin mesajı göreceksiniz.
Proxy artık gerekli olmadığında nasıl devre dışı bırakılır
# Genel proxy'yi kaldır git config --global --unset http.proxy # Belirli bir alan adı için proxy'yi kaldır git config --global --unset http.https://gitlab.com.proxy
GitLab Runner ve CI/CD boru hatları için proxy
GitLab Runner, .gitlab-ci.yml dosyasındaki görevleri yerine getiren bir ajandır. Eğer runner kapalı bir ağda veya sınırlı internet erişimi olan bir sunucuda bulunuyorsa, proxy'yi ayrı olarak ayarlamak gerekir. Geliştiricinin Git istemcisi ayarları burada işe yaramaz — runner başka bir makinede çalışır.
Yöntem 1: Runner yapılandırmasında ortam değişkenleri
GitLab Runner yapılandırma dosyasını açın (genellikle /etc/gitlab-runner/config.toml) ve [runners.env] bölümüne ortam değişkenlerini ekleyin:
[[runners]]
name = "my-runner"
url = "https://gitlab.com/"
token = "TOKEN'İNİZ"
executor = "shell"
environment = [
"HTTP_PROXY=http://PROXY_IP'NİZ:PORT",
"HTTPS_PROXY=http://PROXY_IP'NİZ:PORT",
"NO_PROXY=localhost,127.0.0.1,şirketinizin-iç-domeni.com"
]
Yapılandırmayı değiştirdikten sonra runner'ı yeniden başlatın: sudo gitlab-runner restart
Yöntem 2: .gitlab-ci.yml dosyasında değişkenler (boru hattı düzeyinde)
Eğer runner'ın yöneticisi değilseniz veya yalnızca belirli bir proje için proxy ayarlamak istiyorsanız, değişkenleri doğrudan boru hattı dosyasına ekleyin:
variables:
HTTP_PROXY: "http://PROXY_IP'NİZ:PORT"
HTTPS_PROXY: "http://PROXY_IP'NİZ:PORT"
NO_PROXY: "localhost,127.0.0.1,.internal.company.com"
stages:
- build
- test
- deploy
build:
stage: build
script:
- npm install # şimdi proxy üzerinden gidecek
- npm run build
Yöntem 3: GitLab proje ayarlarında değişkenler (depo içinde commit olmadan)
Hassas veriler için en iyi yöntem (kimlik doğrulamalı proxy): projenizin Ayarlar → CI/CD → Değişkenler bölümüne gidin ve HTTP_PROXY, HTTPS_PROXY, NO_PROXY değişkenlerini korumalı (masked) değişkenler olarak ekleyin. Bunlar, tüm boru hatlarında otomatik olarak kullanılabilir olacak, ancak loglarda görünmeyecekler.
NO_PROXY hakkında — unutmayın!
NO_PROXY değişkeni kritik öneme sahiptir. İçeride doğrudan bağlanması gereken tüm iç alan adlarını ve IP'leri eklemelisiniz, aksi takdirde runner, iç hizmetlere bile proxy üzerinden gitmeye çalışacaktır — ve boru hattı çökebilir.
Docker executor için proxy
Eğer runner Docker executor kullanıyorsa, konteynerler varsayılan olarak ana makinenin proxy ayarlarını miras almaz. Ya config.toml dosyasına [runners.docker] bölümüne değişkenler eklemelisiniz ya da runner'ın bulunduğu ana makinede /etc/systemd/system/docker.service.d/proxy.conf dosyasını oluşturmalısınız:
[Service] Environment="HTTP_PROXY=http://PROXY_IP'NİZ:PORT" Environment="HTTPS_PROXY=http://PROXY_IP'NİZ:PORT" Environment="NO_PROXY=localhost,127.0.0.1"
Bunun ardından: sudo systemctl daemon-reload && sudo systemctl restart docker
Kendi barındırdığınız GitLab sunucusu için proxy
Eğer kendi GitLab sunucunuzu (Omnibus veya Helm ile kurduysanız) yönetiyorsanız, proxy, GitLab'ın dış hizmetlere erişebilmesi için gereklidir: bildirim göndermek, dış CI sistemlerine bağlanmak, kullanıcı avatarlarını yüklemek, Jira veya Slack ile entegre olmak.
gitlab.rb dosyasında ayarlama (Omnibus kurulumu)
/etc/gitlab/gitlab.rb dosyasını açın ve aşağıdaki satırları ekleyin veya yorumdan çıkarın:
# GitLab için proxy (Omnibus)
gitlab_rails['env'] = {
"http_proxy" => "http://PROXY_IP'NİZ:PORT",
"https_proxy" => "http://PROXY_IP'NİZ:PORT",
"no_proxy" => "localhost,127.0.0.1,SİZİN_IÇ_DOMENİNİZ"
}
# Eğer proxy kimlik doğrulama gerektiriyorsa:
gitlab_rails['env'] = {
"http_proxy" => "http://KULLANICI_ADI:ŞİFRE@PROXY_IP'NİZ:PORT",
"https_proxy" => "http://KULLANICI_ADI:ŞİFRE@PROXY_IP'NİZ:PORT",
"no_proxy" => "localhost,127.0.0.1"
}
Yapılandırmayı değiştirdikten sonra ayarları uygulayın: sudo gitlab-ctl reconfigure
Yönetici Alanı üzerinden çıkış bağlantıları ayarlama
GitLab 15.0+ sürümünde, proxy'yi doğrudan web arayüzü üzerinden ayarlama imkanı geldi: Yönetici Alanı → Ayarlar → Ağ → Çıkış istekleri bölümüne gidin. Burada, çıkış web kancaları için proxy belirtebilir ve GitLab'ın erişebileceği IP aralıklarını sınırlayabilirsiniz. Bu, güvenlik için faydalıdır — web kancaları üzerinden SSRF saldırılarını önler.
Tüm ekip için proxy üzerinden erişim düzenleme
5–50 kişilik bir ekip için GitLab'a istikrarlı erişim sağlamak gerektiğinde, her makinede bireysel ayar yapmak en iyi yaklaşım değildir. Daha ölçeklenebilir çözümleri inceleyelim.
Yöntem 1: Kurumsal proxy sunucusu
Tek bir proxy sunucusu (örneğin, Squid veya 3proxy) internet erişimi ile kurulur. Tüm geliştiriciler, bu sunucuyu kullanacak şekilde Git'i ayarlar. Avantajları: merkezi yönetim, tek kontrol noktası, trafiği kaydetme imkanı. Dezavantajı: sunucu, tek bir arıza noktası haline gelir.
Yöntem 2: Depo (mirror) yansıtma
GitLab, depo yansıtmayı destekler. Kendi barındırdığınız GitLab'ı iç ağda gitlab.com'un bir yansıması olarak ayarlayabilirsiniz. Geliştiriciler, iç sunucu ile çalışır ve bu sunucu, proxy üzerinden dışarıyla senkronize olur. Bu, her geliştirici için proxy bağlantısının kalitesine olan bağımlılığı azaltır.
Yöntem 3: dotfiles veya onboarding scripti ile otomatik ayarlama
Her geliştiricinin kendi ortamını ayarladığı ekipler için, gerekli Git ayarlarını otomatik olarak yazan bir onboarding scripti oluşturmak uygun olur. Script, kurumsal depoda saklanır ve yeni bir çalışma alanı ayarlanırken çalıştırılır.
#!/bin/bash
# setup-git-proxy.sh — yeni bir çalışma alanı ayarlanırken çalıştırılacak
PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"
echo "GitLab'a erişim için Git proxy ayarlanıyor..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "Tamam! Kontrol edin: git config --global --list | grep proxy"
Ekip dağıtımı için kontrol listesi
- Geliştiriciler, runner'lar veya GitLab sunucusu düzeyinde proxy'ye ihtiyaç olup olmadığını belirleyin (veya üçünü de)
- Proxy türünü seçin: maksimum uyumluluk için SOCKS5
- Tüm iç alan adları ve hizmetler için
NO_PROXYayarlayın - Proxy üzerinden SSH anahtarlarının çalıştığını kontrol edin (ayrı bir adım!)
- Ayarları kurumsal wiki'de belgeleyin
- Yeni çalışanlar için bir onboarding scripti oluşturun
- Proxy sunucusunun erişilebilirliğini izleyin
Sık karşılaşılan sorunlar ve çözümleri
Doğru ayar yapıldıktan sonra bile bazen bir şeyler yolunda gitmez. İşte en yaygın sorunlar ve bunların teşhis yöntemleri.
Sorun 1: SSL sertifika sorunu: yerel yetkilinin sertifikası alınamıyor
Bu hata, proxy sunucusu (özellikle kurumsal olan) SSL denetimi yapıyorsa — GitLab'ın sertifikasını kendi sertifikasıyla değiştiriyorsa ortaya çıkar. Git bu sertifikaya güvenmez. Çözüm: kurumsal kök sertifikayı güvenilirler listesine eklemektir.
# Geçici çözüm (hata ayıklama için, üretim için değil!) git config --global http.sslVerify false # Doğru çözüm: kurumsal sertifikayı ekleyin git config --global http.sslCAInfo /yol/kurumsal-ca-bundle.crt
Sorun 2: Proxy HTTPS için çalışıyor, ama SSH çalışmıyor
Bu klasik bir durumdur: Git'te http.proxy~/.ssh/config dosyasını, Git istemcisi bölümünde açıklandığı gibi ayrı olarak ayarlamanız gerekir.
Alternatif: GitLab ile HTTPS üzerinden çalışmaya geçin. Bunun için uzak URL'yi değiştirin:
# Mevcut uzak bağlantıyı kontrol et git remote -v # SSH'den HTTPS'ye değiştir git remote set-url origin https://gitlab.com/kullanıcı_adı/depo.git
Sorun 3: CI/CD boru hattı, depo klonlama aşamasında takılıyor
Runner, GitLab'dan doğrudan depo klonluyor ve token kullanıyor. Eğer runner proxy'nin arkasındaysa, bu klonlama da proxy üzerinden gitmelidir. HTTP_PROXY ve HTTPS_PROXY değişkenlerinin config.toml dosyasında ayarlandığından emin olun, sadece .gitlab-ci.yml dosyasında değil — CI dosyasındaki değişkenler, klonlamadan sonra uygulanır, öncesinde değil.
Sorun 4: Proxy çalışıyor, ama çok yavaş
Eğer push/pull işlemleri çalışıyorsa ama normalden 5–10 kat daha uzun sürüyorsa, sorun proxy sunucusunun bant genişliğinde veya coğrafi konumunda olabilir. Büyük depolarla (100+ MB) çalışırken, düşük gecikme ve yüksek bant genişliği olan proxy'leri seçmek önemlidir. Bu durumda veri merkezi proxy'leri, yerleşik olanlara göre tercih edilir — daha kararlı bir kanal sağlarlar.
Sorun 5: Proxy üzerinden kimlik doğrulama, parolanın tekrar girilmesini gerektiriyor
Eğer proxy, Temel kimlik doğrulama gerektiriyorsa ve Git her seferinde parolayı soruyorsa, kimlik bilgisi yardımcı programını ayarlayın:
# macOS — Anahtar Zinciri kullanın git config --global credential.helper osxkeychain # Windows — Windows Kimlik Bilgisi Yöneticisi kullanın git config --global credential.helper manager # Linux — 1 saat boyunca önbelleğe al git config --global credential.helper "cache --timeout=3600"
Proxy ile ilgili bir sorunu hızlıca teşhis etme:
Aşağıdaki komutu kullanın GIT_TRACE=1 GIT_CURL_VERBOSE=1 git clone https://gitlab.com/... — bu, tüm HTTP isteklerinin ve yanıtlarının ayrıntılı bir kaydını verecektir, proxy ile ilgili bilgileri de içerecektir.
Sonuç ve öneriler
GitLab için proxy ayarlamak, aynı anda birkaç düzeyde çözülebilecek bir görevdir. Geliştiricinin çalışma makinesinde yalnızca birkaç satır yazması yeterlidir. CI/CD için, runner yapılandırmasına veya proje ayarlarına ortam değişkenleri eklemeniz gerekir. Kendi barındırdığınız GitLab için ise gitlab.rb dosyasını güncelleyip yapılandırmayı yeniden oluşturmalısınız.
Çoğu sorunu önlemeye yardımcı olacak ana kurallar:
- SOCKS5 kullanın — hem HTTPS hem de SSH ile çalışır
- Her zaman iç hizmetler için
NO_PROXYayarlayın - Üretimde SSL doğrulamasını devre dışı bırakmayın — kurumsal sertifikayı ekleyin
- CI/CD için proxy'yi
config.tomldosyasında ayarlayın, yalnızca.gitlab-ci.ymldosyasında değil - Ayarları belgeleyin — ekipteki yeni bir geliştirici teşekkür edecektir
Eğer dünyanın herhangi bir yerinden GitLab'a istikrarlı erişim sağlamak için güvenilir bir proxy arıyorsanız, veri merkezi proxy'lerini düşünmenizi öneririz — yüksek veri aktarım hızı ve düşük gecikme sağlarlar, bu da büyük depolar ve yoğun CI/CD boru hatları ile çalışırken özellikle önemlidir. Maksimum anonimlik veya GeoIP engellerini aşmak isteyen ekipler için, gerçek ev kullanıcılarına ait IP'lerle yerleşik proxy'ler uygundur.
```