CI/CD Pipeline'ları için Proxy: Kapalı Kaynaklara Erişim için GitHub Actions, GitLab CI ve Jenkins Ayarları

Pipeline'ınız, dış bir API'ye erişmeye çalışırken 403 Forbidden veya Connection refused hatası mı alıyor? Muhtemelen, CI/CD sunucunuzun IP adresi hedef kaynak tarafından engellenmiştir. Proxy bu sorunu çözer: trafiği gerekli IP üzerinden yönlendirirsiniz ve pipeline sorunsuz çalışır. Bu makalede, GitHub Actions, GitLab CI ve Jenkins için adım adım talimatlar bulunmaktadır.

CI/CD'de Proxy Neden Gerekli: Gerçek Senaryolar

CI/CD pipeline'ları, GitHub, GitLab gibi bulut koşucularında veya kendi Jenkins ajanlarınızda sabit IP adresleri ile çalışır. Bu IP'ler iyi bilinir ve birçok dış hizmet ya bunları engeller ya da istek sayısını sınırlar. İşte proxy olmadan geçilemeyecek belirli durumlar:

Coğrafi Olarak Kısıtlı Kaynaklara Erişim

Birçok kurumsal npm kayıt defteri, Maven depoları ve dahili API'ler yalnızca belirli ülkelerden veya IP aralıklarından erişilebilir. Eğer GitHub Actions koşucunuz, hedef hizmetin güvenlik duvarı düzeyinde engellenmiş bir bölgede bulunuyorsa, pipeline bağımlılıkları indiremeyecek veya veri gönderemeyecektir. Gerekli coğrafi konumda bir proxy bu sorunu, altyapıyı değiştirmeden çözer.

Rate Limiting ve IP Engellemeleri

GitHub Actions bulut koşucuları, Microsoft Azure aralıklarından IP kullanır. Birçok kamu API'si bu aralıkları bilmektedir ve bunlara sert limitler uygular veya tamamen engeller. Örneğin, kamu verilerinin ayrıştırılması, testler sırasında üçüncü taraf API'lere istekler, sınırlı CDN'lerden dağıtım indirme — bunların hepsi düzenli olarak bulut koşucularının IP'leri nedeniyle bozulur. Proxy üzerinden döngüleme, rate limiting'i aşmanıza olanak tanır.

Gerçek Web Siteleri ile Entegrasyon Testi

Eğer entegrasyon testleriniz gerçek web sitelerine veya pazar yerlerine (Wildberries, Ozon, Avito, Amazon) erişiyorsa, bu siteler her çalıştırmada koşucudan aynı IP'yi görür ve hızlıca engeller. IP döngülemesi olan bir proxy, testlerin captcha ve engellemeler olmadan istikrarlı bir şekilde geçmesini sağlar.

Dahili Kurumsal Kaynaklara Erişim

Kurumsal ağlar genellikle dış dünyadan kapalıdır. Eğer pipeline, dahili bir sunucuya dağıtım yapması veya kapalı bir API'ye erişmesi gerekiyorsa, kurumsal ağ içinde bir proxy (veya SOCKS5 tüneli) bulut koşucusu ile kapalı altyapı arasında bir köprü olur.

Reklam ve Pazarlama Entegrasyonlarının Testi

Facebook Ads API, TikTok Ads API veya Google Ads API ile çalışan ekipler, CI/CD üzerinden kampanya oluşturmayı otomatikleştirir. Bu platformlar, IP ile ilgili katı kurallara sahiptir: veri merkezlerinden gelen istekler engellenebilir veya ek doğrulama gerektirebilir. Pipeline'daki konut proxy'leri, istekleri normal kullanıcı trafiğine benzer hale getirir.

Pipeline için Hangi Proxy Türünü Seçmeli

Proxy türü seçimi, göreve bağlıdır. CI/CD pipeline'ları için üç seçenek geçerlidir — her birinin kendine özgü avantajları ve sınırlamaları vardır:

GitHub Actions'da Proxy Ayarlama

GitHub Actions, günümüzde en popüler CI/CD aracıdır. Burada proxy ayarı, ortam değişkenleri ve depo gizlilikleri aracılığıyla yapılır. Adım adım inceleyelim.

Adım 1: Proxy Verilerini Depo Gizliliklerine Ekleyin

Proxy kullanıcı adı ve şifresini asla YAML iş akışı dosyasına yazmayın. GitHub Gizliliklerini kullanın:

1. Depoyu açın → Ayarlar → Gizlilikler ve değişkenler → Actions
2. Yeni depo gizliliği butonuna tıklayın
3. Şu formatta bir değer ile PROXY_URL gizliliğini oluşturun: http://user:[email protected]:port

Adım 2: İş Akışında Ortam Değişkenlerini Kullanın

Çoğu araç (curl, wget, npm, pip, Maven) otomatik olarak standart ortam değişkenlerini alır: HTTP_PROXY, HTTPS_PROXY ve NO_PROXY. İş akışı örneği:

name: Proxy ile Derleme

on: [push]

env:
  HTTP_PROXY: ${{ secrets.PROXY_URL }}
  HTTPS_PROXY: ${{ secrets.PROXY_URL }}
  NO_PROXY: localhost,127.0.0.1,internal.company.com

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Bağımlılıkları Yükle
        run: npm ci

      - name: Entegrasyon Testlerini Çalıştır
        run: npm test

      - name: Dış API'yi Çağır
        run: |
          curl -v https://api.example.com/data

Adım 3: GitHub Actions'da SOCKS5 Proxy

Eğer SOCKS5 kullanıyorsanız (çoğu görev için önerilir), standart ortam değişkenleri yeterli değildir — yerel bir tünel gereklidir. proxychains aracını kullanın veya microsocks ayarlayın:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: SOCKS5 proxy tünelini kur
        run: |
          sudo apt-get install -y proxychains4
          echo "socks5 proxy.host 1080 user password" >> /etc/proxychains4.conf

      - name: SOCKS5 üzerinden komut çalıştır
        run: proxychains4 curl https://restricted-resource.com/api

Belirli Araçlar için Proxy Ayarlama

Bazı araçlar sistem değişkenlerini görmezden gelir ve ayrı bir ayar gerektirir:

GitLab CI'da Proxy Ayarlama

GitLab CI, ortam değişkenlerini ayarlamak için proje, grup veya örnek düzeyinde birkaç seviye sunar. Bu, proxy yönetimini GitHub Actions'a göre daha esnek hale getirir.

Adım 1: GitLab CI/CD Değişkenlerine Değişken Ekleyin

1. Projeyi açın → Ayarlar → CI/CD → Değişkenler bölümüne gidin
2. Değişken ekle butonuna tıklayın
3. Gizli bir değişken olarak PROXY_URL ekleyin ve Masked (loglarda değeri gizler) türünü seçin
4. Değer: http://user:[email protected]:port

Adım 2: .gitlab-ci.yml Dosyasında Değişkenleri Kullanın

variables:
  HTTP_PROXY: $PROXY_URL
  HTTPS_PROXY: $PROXY_URL
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  image: node:20-alpine
  script:
    - npm ci
    - npm run build

integration_tests:
  stage: test
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - pytest tests/integration/

deploy:
  stage: deploy
  script:
    - curl -X POST https://api.external-service.com/deploy
      -H "Authorization: Bearer $DEPLOY_TOKEN"
      -d '{"version": "$CI_COMMIT_SHA"}'

Proxy Sadece Belirli İşler İçin

Eğer proxy her yerde gerekli değilse (örneğin, sadece entegrasyon testleri için ama derleme için değilse), değişkenleri belirli bir iş düzeyinde ayarlayın, küresel olarak değil:

integration_tests:
  stage: test
  variables:
    HTTP_PROXY: $PROXY_URL
    HTTPS_PROXY: $PROXY_URL
  script:
    - pytest tests/integration/

build:
  stage: build
  # Burada proxy tanımlanmadı — doğrudan bağlantı
  script:
    - npm ci && npm run build

Kendi Barındırılan GitLab Runner: Proxy'yi Runner Düzeyinde Ayarlama

Eğer kendi GitLab Runner'ınızı kullanıyorsanız, proxy'yi runner yapılandırmasında küresel olarak ayarlayabilirsiniz. /etc/gitlab-runner/config.toml dosyasını açın ve [runners.env] bölümüne ekleyin:

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "TOKEN"
  executor = "docker"
  environment = [
    "HTTP_PROXY=http://user:[email protected]:port",
    "HTTPS_PROXY=http://user:[email protected]:port",
    "NO_PROXY=localhost,127.0.0.1"
  ]

Bu, bu runner'daki tüm pipeline'ların proxy kullanması gerektiğinde kullanışlıdır — her .gitlab-ci.yml dosyasında bunu belirtmek zorunda kalmazsınız.

Jenkins'de Proxy Ayarlama

Jenkins, üç araçtan en esnek olanıdır, ancak ayarları en karmaşık olanıdır. Burada proxy, Jenkins için küresel olarak, belirli bir Pipeline için veya ayrı bir adım için ayarlanabilir.

Yöntem 1: Jenkins'de Küresel Proxy Ayarları

1. Jenkins'i Yönet → Sistem bölümünü açın
2. HTTP Proxy Yapılandırması bölümünü bulun
3. Sunucu, Port, Kullanıcı Adı, Şifre alanlarını doldurun
4. No Proxy Host alanında dahili adresleri virgülle ayırarak belirtin
5. Kontrol etmek için Test URL butonuna tıklayın ve kaydedin

Bu ayar, Jenkins'in eklentileri ve güncellemeleri yüklemesini etkiler, ancak otomatik olarak pipeline'ların çalışma ortamına geçmez. Pipeline'lar için ayrı bir yapılandırma gereklidir.

Yöntem 2: Declarative Pipeline'da Proxy Ayarı Ortam Değişkenleri ile

pipeline {
    agent any

    environment {
        HTTP_PROXY  = credentials('proxy-url-credential')
        HTTPS_PROXY = credentials('proxy-url-credential')
        NO_PROXY    = 'localhost,127.0.0.1,internal.company.com'
    }

    stages {
        stage('Build') {
            steps {
                sh 'npm ci'
                sh 'npm run build'
            }
        }

        stage('Entegrasyon Testleri') {
            steps {
                sh 'pytest tests/integration/'
            }
        }

        stage('Dağıtım') {
            steps {
                sh '''
                    curl -X POST https://api.external-service.com/deploy \
                    -H "Authorization: Bearer ${DEPLOY_TOKEN}" \
                    -d "version=${GIT_COMMIT}"
                '''
            }
        }
    }
}

Adım 3: Jenkins Kimlik Bilgilerine Proxy Kimlik Bilgilerini Ekleyin

1. Jenkins'i Yönet → Kimlik Bilgileri → Sistem → Küresel kimlik bilgileri bölümüne gidin
2. Kimlik Bilgisi Ekle butonuna tıklayın
3. Tür: Gizli metin
4. ID: proxy-url-credential
5. Gizli: http://user:[email protected]:port

Yöntem 3: Java Projeleri için JVM Parametreleri ile Proxy Ayarlama

Eğer pipeline'ınız bir Java projesi (Maven, Gradle) inşa ediyorsa, sistem ortam değişkenleri çalışmayabilir — JVM kendi sistem özelliklerini kullanır. Bunları JAVA_OPTS içine ekleyin:

environment {
    JAVA_OPTS = '-Dhttps.proxyHost=proxy.host -Dhttps.proxyPort=8080 -Dhttps.proxyUser=user -Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.internal.com'
}

Pipeline'da Docker Konteynerleri İçinde Proxy

Modern CI/CD pipeline'larının çoğu, adımları Docker konteynerleri içinde çalıştırır. Konteynere proxy iletmek, birkaç yöntemle çözülebilecek ayrı bir görevdir.

Docker Görüntüsü Oluşturma Sırasında --build-arg ile Proxy İletme

Eğer proxy yalnızca Docker görüntüsü oluşturma sırasında (örneğin, Dockerfile içinde paket yüklemek için) gerekli ise, build argümanlarını kullanın:

# .github/workflows/build.yml veya .gitlab-ci.yml içinde
docker build \
  --build-arg HTTP_PROXY=$HTTP_PROXY \
  --build-arg HTTPS_PROXY=$HTTPS_PROXY \
  --build-arg NO_PROXY=$NO_PROXY \
  -t myapp:latest .

# Dockerfile içinde
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

RUN apt-get update && apt-get install -y curl
RUN npm ci

Docker Daemon için Proxy'yi Küresel Olarak Ayarlama

Kendi barındırılan koşucularda, tüm Docker daemon için proxy ayarlayabilirsiniz — böylece tüm konteynerler, Dockerfile'da değişiklik yapmadan otomatik olarak proxy alır:

# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:port"
Environment="HTTPS_PROXY=http://user:[email protected]:port"
Environment="NO_PROXY=localhost,127.0.0.1,registry.internal.com"

# Değişiklikleri uygulamak için:
# systemctl daemon-reload
# systemctl restart docker

Güvenlik: Proxy Kimlik Bilgilerini Nasıl Saklamalı

Proxy kimlik bilgileri, API anahtarları veya veritabanı şifreleri gibi gizli bilgilerdir. Sızması, herkesin proxy'nizi sizin adınıza kullanabileceği anlamına gelir. İşte güvenli saklama kuralları:

Güvenlik Kontrol Listesi

• ✅ Asla proxy kullanıcı adı/şifresini doğrudan pipeline YAML dosyalarına yazmayın
• ✅ GitLab'da Masked variables ve GitHub'da Encrypted secrets kullanın — loglarda gizlenirler
• ✅ Jenkins'te Secret text veya Username with password türünü Kimlik Bilgileri Deposu'nda kullanın
• ✅ Dahili adresler için NO_PROXY ekleyin — kendi altyapınıza giden trafik proxy üzerinden gitmemelidir
• ✅ Proxy şifrelerini düzenli olarak döndürün — yalnızca gizlilik deposunda güncelleyin, pipeline kodunu değiştirmeden
• ✅ Proxy için IP kimlik doğrulaması kullanın (runner IP'sini beyaz listeye alın) — bu şifreden daha güvenlidir
• ✅ Proxy loglarını olağandışı etkinlikler için kontrol edin

Proxy URL Formatı: Nereye Ne Yerleştirilir

Sık Karşılaşılan Hatalar ve Çözüm Yolları

Doğru ayarlara rağmen sorunlar ortaya çıkabilir. İşte en yaygın hatalar ve çözümleri:

Hata: Proxy Authentication Required (407)

Hata: SSL Sertifika Doğrulaması Başarısız

Hata: Proxy Üzerinden Bağlantı Zaman Aşımı

Hata: Araç HTTP_PROXY Değişkenlerini Görmezden Geliyor

Hata: Dahili Hizmetler de Proxy Üzerinden Geçiyor

Sonuç

CI/CD pipeline'ında proxy ayarlamak, tek seferlik bir görev değil, otomasyonun doğru mimarisinin bir parçasıdır. Üç ana aracı inceledik: GitHub Actions (Gizlilikler ve ortam değişkenleri aracılığıyla), GitLab CI (Maskelenmiş değişkenler aracılığıyla) ve Jenkins (Kimlik Bilgileri Deposu ve Declarative Pipeline aracılığıyla). Tüm araçlar için ana prensipler aynıdır: kimlik bilgilerini asla kodda saklamamak, dahili adresler için NO_PROXY kullanmak ve proxy türünü belirli bir göreve göre seçmektir.

Doğru proxy türünü seçmek, pipeline'ın kararlılığı için kritik öneme sahiptir. Bağımlılıkları indirmek ve standart API'lere erişmek için hızlı veri merkezi proxy'leri yeterlidir. Ancak, pipeline'ınız gerçek web sitelerinde entegrasyon testleri yapıyorsa, reklam platformları (Facebook Ads API, TikTok Ads API) ile çalışıyorsa veya pazar yerlerine erişiyorsa — konut proxy'leri kullanın: IP'leri normal kullanıcı trafiği olarak algılanır ve nadiren engellenir veya rate limiting'e tabi tutulur.

Ana kural: proxy'yi pipeline'ın başında ayrı bir adımda test edin — bu, sorunları hızlı bir şekilde teşhis etmenizi sağlar ve uzun bir derlemenin sonunda hata aramak için zaman kaybetmenizi önler. Proxy ayarlarından hemen sonra curl -v https://api.ipify.org adımını ekleyin — bu, isteklerin gittiği IP'yi gösterecek ve proxy'nin düzgün çalıştığını doğrulayacaktır.