.env ve .env.example Kayması: Production Deploy Öncesi Eksik Ortam Değişkenlerini Yakalamak

Neden yerelde çalışan kod deploy'da patlar?

Bir özelliği geliştirirken yeni bir API anahtarı veya feature flag için .env dosyasına yeni bir satır eklemek saniyeler sürer. Aynı satırı .env.example şablonuna ve deploy ortamına eklemeyi unutmak ise çoğu zaman uygulamanın ancak üretim trafiği o kod yoluna girdiğinde KeyError veya boş string hatasıyla çökmesine yol açar.

Sorun yalnızca eksik anahtarlar değildir: zamanla artık kullanılmayan eski değişkenler şablonda birikir, geliştiriciler hangi değişkenin gerçekten zorunlu olduğunu anlayamaz ve onboarding süresi uzar.

1. Adım: .env ve .env.example sözleşmesini CI'da zorunlu kılın

Konfigürasyon kaymasını uyarı olarak bırakmak yerine derleme hatasına çevirmek en temiz çözümdür. Sıfır bağımlılıklı envdoctor-cli aracı .env ile .env.example dosyalarını karşılaştırır ve sözleşme ihlalinde sıfırdan farklı çıkış kodu döndürür.

pip install envdoctor-cli

# .env ile .env.example arasındaki eksik veya fazla anahtarları kontrol et
envdoctor check --strict

# Eksik anahtarları gerçek değerleri sızdırmadan maskeli yer tutucuyla ekle
envdoctor sync

2. Adım: Kodda kullanılıp belgelenmemiş değişkenleri AST ile bulun

Yalnızca iki .env dosyasını kıyaslamak yeterli değildir; bazen geliştirici kod içinde os.getenv("NEW_WEBHOOK_SECRET") çağrısı ekler ama bunu ne .env ne de .env.example dosyasına yazar. Regex tabanlı aramalar yorum satırları ve string birleştirmelerde yanılırken, Python AST analizi gerçek ortam değişkeni okumalarını doğrudan sözdizimi ağacından çıkarır.

# Kaynak kodda os.getenv / os.environ çağrılarını tara ve CI için JSON üret
envdoctor audit --format json

3. Adım: Pull request kapısına 5 satırlık kontrol ekleyin

Her pull request'te hem şablon eşleşmesini hem de kod içi AST denetimini koşturduğunuzda, eksik ortam değişkeni daha merge edilmeden yakalanır. Bu kontrol gizli değerleri dışarı okumaz; yalnızca anahtar isimlerini doğrular.

name: Env Contract Check
on: [pull_request]
jobs:
  envdoctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install envdoctor-cli && envdoctor check --strict && envdoctor audit