GitHub Actions ve CI/CD'de Proxy Kurulumu

GitHub Actions ve CI/CD'de proxy kurulumu, HTTP_PROXY, HTTPS_PROXY ve NO_PROXY gibi standart proxy ortam değişkenlerinin workflow tanımınızda —genellikle job veya step seviyesinde— yapılandırılması anlamına gelir. Böylece CI/CD hattı içinde çalışan action'lar, script'ler ve araçlar ağ trafiklerini belirtilen bir proxy sunucusu üzerinden yönlendirir.

Kurumlar giden ağ erişimini denetlemek, güvenlik politikalarını uygulamak, içerik filtrelemek ve sık erişilen kaynakları önbelleğe almak için sıklıkla proxy sunucuları kullanır. Bu tür ortamlarda çalışan CI/CD hatlarında, build araçlarının, bağımlılık yöneticilerinin ve test script'lerinin dış servislere, paket depolarına veya API'lere ulaşabilmesi için proxy ayarları şarttır. GitHub Actions runner'ları, özellikle de self-hosted runner'lar, GitHub'ın kendisine veya diğer internet kaynaklarına erişmek için proxy yapılandırması gerektirebilir.

Proxy ortam değişkenlerini tanımlama

Linux tabanlı bir ortamda (GitHub tarafından barındırılan runner'lar ağırlıklı olarak bunu kullanır) proxy yapılandırmanın en yaygın ve evrensel olarak tanınan yöntemi ortam değişkenleridir.

• HTTP_PROXY: HTTP istekleri için proxy sunucusunu belirtir.
• HTTPS_PROXY: HTTPS istekleri için proxy sunucusunu belirtir.
• NO_PROXY: Proxy'yi atlaması gereken host adlarının, alan adlarının veya IP adreslerinin virgülle ayrılmış listesi. Dahili kaynaklara doğrudan erişim için kritiktir.

HTTP_PROXY ve HTTPS_PROXY için biçim genellikle http://[user:password@]host:port şeklindedir.
Bu değişkenlerin hem büyük harfli (HTTP_PROXY) hem de küçük harfli (http_proxy) sürümleri çoğu araç tarafından dikkate alınır; ortam değişkenlerinde büyük harf kullanmak standart uygulamadır.

Workflow seviyesinde proxy yapılandırması

Proxy ayarlarını job seviyesinde uygulamak, o job içindeki tüm step'lerin yapılandırmayı devralmasını sağlar.

name: CI with Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com,github.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node.js dependencies
        run: npm install

      - name: Download a file via curl
        run: curl -v https://api.example.com/data

      - name: Access internal service (bypasses proxy)
        run: curl -v http://internal-service.internal.company.com/status

Step seviyesinde proxy yapılandırması

Belirli step'ler için farklı proxy ayarları gerektiğinde veya job seviyesindeki ayarları geçersiz kılmak istediğinizde, ortam değişkenleri step seviyesinde tanımlanabilir.

name: CI with Specific Step Proxy
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env: # Job için varsayılan proxy (varsa)
      HTTP_PROXY: http://default-proxy:8080
      HTTPS_PROXY: http://default-proxy:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Step using default proxy
        run: curl https://external-api.com/v1

      - name: Step using a different proxy
        env:
          HTTP_PROXY: http://special-proxy:3128
          HTTPS_PROXY: http://special-proxy:3128
          NO_PROXY: localhost,127.0.0.1,api.special-domain.com
        run: curl https://api.special-domain.com/v2

Secret'larla proxy kimlik doğrulaması

Proxy'niz kimlik doğrulama gerektiriyorsa kullanıcı adını ve parolayı doğrudan proxy URL'sine ekleyin. Güvenlik için kimlik bilgilerini GitHub Actions secret'ı olarak saklayın ve workflow içinde bunlara referans verin.

Önce GitHub depo ayarlarınızda depo secret'larını oluşturun (örneğin PROXY_USER, PROXY_PASS).

name: Authenticated Proxy Workflow
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      HTTPS_PROXY: http://${{ secrets.PROXY_USER }}:${{ secrets.PROXY_PASS }}@proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1,.internal.company.com
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Perform network operation
        run: npm install # veya curl vb.

Yaygın araçlar ve proxy etkileşimi

HTTP_PROXY ve HTTPS_PROXY geniş ölçüde dikkate alınsa da bazı araçlar kendine özgü yapılandırma yöntemleri sunar.

git komutları

git, uzak işlemlerde genellikle HTTP_PROXY ve HTTPS_PROXY değişkenlerine uyar. Açık yapılandırma için veya ortam değişkenlerinin yetersiz kaldığı durumlarda git config kullanılabilir.

# HTTP ve HTTPS git işlemleri için proxy ayarla
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy http://proxy.example.com:8080

# Belirli bir remote için özel proxy yapılandır
git config http.https://github.com/.proxy http://github-proxy:8080

npm, yarn

npm ve yarn gibi Node.js paket yöneticileri HTTP_PROXY ve HTTPS_PROXY ortam değişkenlerine uyar. Ayrıca kalıcı ayarlar için kendi yapılandırma komutlarını da sunarlar.

# npm config ile
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080
npm config set no-proxy localhost,127.0.0.1,.internal.com

# yarn config ile
yarn config set proxy http://proxy.example.com:8080
yarn config set httpsProxy http://proxy.example.com:8080
yarn config set no-proxy localhost,127.0.0.1,.internal.com

docker (imaj derleme ve konteyner çalışma zamanı)

Docker'da proxy ayarları hem imaj derleme hem de konteyner çalışma zamanı için ayrı ayrı ele alınmalıdır.

Docker derleme zamanı proxy'si

docker build sırasında çalışan komutlar için (örneğin RUN apk add, RUN apt-get update) proxy ayarlarının build argümanı olarak geçilmesi gerekir.

Dockerfile örneği:

FROM alpine:latest

# Proxy ayarları için build argümanlarını tanımla
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Sonraki RUN komutları için ortam değişkenlerini ayarla
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

# Örnek: paket kurulumunda proxy kullanımı
RUN apk add --no-cache curl

# ... Dockerfile'ınızın geri kalanı

GitHub Actions workflow step'i:

- name: Build Docker image with proxy
  run: |
    docker build . \
      --build-arg HTTP_PROXY=${{ env.HTTP_PROXY }} \
      --build-arg HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      --build-arg NO_PROXY=${{ env.NO_PROXY }} \
      -t my-app:latest

Docker konteyner çalışma zamanı proxy'si

Workflow'unuz bir Docker konteyneri çalıştırıyorsa (örneğin container: anahtarı veya docker run ile), proxy ayarlarının konteynere ortam değişkeni olarak geçilmesi gerekir.

container: anahtarını kullanma:

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: my-custom-image:latest
      env:
        HTTP_PROXY: ${{ env.HTTP_PROXY }}
        HTTPS_PROXY: ${{ env.HTTPS_PROXY }}
        NO_PROXY: ${{ env.NO_PROXY }}
    steps:
      - name: Run command inside container
        run: curl https://external-api.com/data

Bir step'te docker run kullanma:

- name: Run Docker container with proxy
  run: |
    docker run \
      -e HTTP_PROXY=${{ env.HTTP_PROXY }} \
      -e HTTPS_PROXY=${{ env.HTTPS_PROXY }} \
      -e NO_PROXY=${{ env.NO_PROXY }} \
      my-app:latest /app/script.sh

Java uygulamaları (Maven, Gradle)

Maven ve Gradle gibi build araçları dahil olmak üzere Java uygulamaları, proxy ayarlarının Java sistem özellikleri olarak geçilmesini gerektirir. Bu genellikle MAVEN_OPTS veya _JAVA_OPTIONS ortam değişkenleriyle yapılır.

# Maven için
export MAVEN_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

# Gradle için (JVM tabanlı diğer araçlar için de geçerlidir)
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='localhost|127.0.0.1|*.internal.com'"

Alternatif olarak Maven ~/.m2/settings.xml ile, Gradle ise projedeki veya kullanıcının ana dizinindeki gradle.properties ile yapılandırılabilir.

Proxy sorunlarını giderme

• Ortam değişkenlerini doğrulayın: Proxy ortam değişkenlerinin doğru ayarlandığını ve runner'ın shell'inden görülebildiğini teyit etmek için bir step'te run: env | grep -i proxy çalıştırın.
• NO_PROXY'yi kontrol edin: Gereksiz proxy kullanımını veya yönlendirme sorunlarını önlemek için dahili host'ların ve GitHub alan adlarının NO_PROXY içinde doğru listelendiğinden emin olun.
• Proxy sunucusu logları: Mümkünse proxy sunucusunun loglarında GitHub Actions runner'ının IP adresinden gelen bağlantı denemelerini inceleyin. Bu, isteğin proxy'ye ulaşıp ulaşmadığını ve neden reddedilmiş olabileceğini (kimlik doğrulama hatası, erişim reddi vb.) anlamaya yardımcı olur.
• Ağ bağlantısı: Proxy üzerinden bilinen bir dış uç noktaya bağlantıyı açıkça test etmek için bir workflow step'i içinde curl -v --proxy <your-proxy-url> <target-url> kullanın.
• SSL/TLS sertifika sorunları: HTTPS proxy kullanıyorsanız veya HTTP proxy üzerinden HTTPS sitelere erişiyorsanız ve proxy SSL denetimi yapıyorsa, runner sertifika doğrulama hatalarıyla karşılaşabilir. Bu durumda proxy'nin kök CA sertifikasının runner'ın güven deposuna eklenmesi gerekir. Bu, genellikle self-hosted runner kurulumlarında yönetilen karmaşık bir yapılandırmadır.

Proxy yapılandırma özeti