EnvDoctor ile .env denetimi: check, sync ve audit

EnvDoctor neyi kontrol ediyor?

EnvDoctor, geliştirdiğim açık kaynak Python komut satırı aracıdır. check iki yapılandırma dosyasındaki anahtarları karşılaştırır; sync yerel dosyadaki eksik anahtarları örnek dosyaya ekler; audit ise kaynak kodunda bulduğu ortam değişkenlerini seçtiğiniz .env dosyasıyla karşılaştırır. Bu üç işlemin kapsamı farklıdır.

Kurulum için Python 3.12 veya üzeri gerekir. Rehberde CLI sürümü 0.2.0 kullanılıyor. Aşağıdaki örnekler 6 Ekim 2026'da depodaki kaynak koduyla, ayrı bir yerel klasörde çalıştırıldı. Dosyalardaki bütün değerler deneme içindir; bir üretim sisteminden alınmış sonuçlar değildir.

python -m pip install envdoctor-cli==0.2.0
python -m envdoctor --version
# envdoctor 0.2.0

İki dosyada bilinçli bir uyuşmazlık oluşturun

Boş bir deneme klasöründe aşağıdaki .env ve .env.example dosyalarını ayrı ayrı oluşturun. Yerel dosyada LOG_LEVEL var ama şablonda yok. Şablon REDIS_URL istiyor fakat yerel dosyada bu anahtar eksik. API_TOKEN değeri gerçek bir anahtar değildir.

Bu dosyaların amaçları farklıdır: .env yerel değerleri taşır; .env.example projede hangi anahtarların gerektiğini belgeler. Gerçek gizli değerleri Git'e eklemeyin. Aşağıdaki yerel adresler yalnızca anahtar denetimini göstermek içindir; EnvDoctor bu adreslere bağlanmaz.

# .env
DATABASE_URL=postgresql://localhost:5432/demo
API_TOKEN=demo_token_not_a_real_secret
LOG_LEVEL=info

# .env.example
DATABASE_URL=postgresql://localhost:5432/demo
API_TOKEN=
REDIS_URL=redis://localhost:6379/0

check: eksik anahtarları ve strict modunu okuyun

Deneme klasöründe python -m envdoctor --format json check --strict komutunu çalıştırın. --format genel bir seçenektir; check alt komutundan önce yazılmalıdır. Çalıştırmada aşağıdaki JSON üretildi ve çıkış kodu 1 oldu.

missing_in_env, şablonda bulunup yerel dosyada eksik olan REDIS_URL anahtarını gösteriyor. missing_in_example ise yerel dosyadaki LOG_LEVEL anahtarının şablonda belgelenmediğini söylüyor. Varsayılan check yerel dosyadaki gerekli anahtarların eksikliğinde başarısız olur; --strict ayrıca şablonda eksik anahtarlar ve boş yerel değerler için de başarısız olur.

{
  "valid": false,
  "strict": true,
  "env_file": ".env",
  "example_file": ".env.example",
  "total_env_keys": 3,
  "total_example_keys": 3,
  "missing_in_env": [
    "REDIS_URL"
  ],
  "missing_in_example": [
    "LOG_LEVEL"
  ],
  "empty_in_env": []
}

sync --dry-run: yazmadan önce değişikliği görün

python -m envdoctor --format json sync --dry-run komutu bu örnekte yalnızca LOG_LEVEL anahtarının ekleneceğini raporladı ve çıkış kodu 0 oldu. --dry-run, .env.example dosyasını değiştirmeden yapılacak eklemeleri gösterir.

Yönü doğru okumak önemli: sync, .env dosyasından .env.example dosyasına çalışır. Şablonun istediği REDIS_URL anahtarını yerel dosyaya eklemez. Anahtarları eşitlemek, eksik bağlantı değerlerini kendiliğinden bulmak değildir.

{
  "source_env": ".env",
  "target_example": ".env.example",
  "dry_run": true,
  "added_count": 1,
  "added_keys": [
    "LOG_LEVEL"
  ]
}

sync: şablonu güncelleyin, sonra tekrar kontrol edin

Önizlemeden sonra python -m envdoctor --format json sync çalıştırıldı. Komut çıkış kodu 0 ile döndü ve şablonun sonuna aşağıdaki satırları ekledi. LOG_LEVEL=info değerini kopyalamak yerine your_log_level_here yer tutucusunu üretti.

sync mevcut şablon anahtarlarını yeniden yazmaz veya kaldırmaz. Yeniden çalıştırılan strict kontrol yine çıkış kodu 1 verdi: LOG_LEVEL uyuşmazlığı giderilmişti fakat .env içindeki REDIS_URL hâlâ eksikti. Ayrıca sync mevcut şablon içeriğini ve yorumları korur; dosyanın tamamını gizli bilgilerden arındıran bir araç değildir.

# .env.example dosyasına eklenen satırlar
# Synchronized by EnvDoctor
LOG_LEVEL=your_log_level_here

Eksik yerel ayarı tamamlayın

Bu deneme için .env dosyasına REDIS_URL=redis://localhost:6379/0 satırı eklendi. Kendi projenizde gerçek değeri yetkili yapılandırma kaynağından almalısınız. Sonrasında python -m envdoctor --format json check --strict komutu aşağıdaki çıktıyı verdi; çıkış kodu 0 oldu.

valid: true dosyalardaki anahtarların bu kontrolü geçtiğini ifade eder. Veritabanının erişilebilir olduğunu, token'ın geçerli olduğunu veya uygulamanın sorunsuz açılacağını kanıtlamaz. Bunlar ayrı bağlantı ve uygulama testleri gerektirir.

{
  "valid": true,
  "strict": true,
  "env_file": ".env",
  "example_file": ".env.example",
  "total_env_keys": 4,
  "total_example_keys": 4,
  "missing_in_env": [],
  "missing_in_example": [],
  "empty_in_env": []
}

audit için küçük bir Python örneği

Deneme klasöründe src/app.py dosyasını aşağıdaki içerikle oluşturun. SENTRY_DSN kodda kullanılıyor fakat .env dosyasında bulunmuyor. LOG_LEVEL ise .env içinde var ama bu küçük kaynak dosyada kullanılmıyor.

Dosyayı uygulama olarak çalıştırmanız gerekmez. audit kaynak metnini tarar; ortam değişkenlerini kullanarak dış servislere bağlantı kurmaz. Bu örnek, dosya anahtarları eşleşse bile kod tarafında başka bir eksik bulunabileceğini gösterir.

import os

DATABASE_URL = os.getenv("DATABASE_URL")
API_TOKEN = os.getenv("API_TOKEN")
REDIS_URL = os.getenv("REDIS_URL")
SENTRY_DSN = os.getenv("SENTRY_DSN")

audit: kodu seçtiğiniz .env dosyasıyla karşılaştırın

python -m envdoctor --format json audit ./src komutunun çalıştırılmasında dört kullanım bulundu; eksik SENTRY_DSN nedeniyle çıkış kodu 1 oldu. Aşağıda raporun özet alanları gösteriliyor. Tam JSON ayrıca her kullanımın dosya yolunu, satır numarasını ve kısa kod parçasını içerir.

Bu sürümde audit varsayılan olarak .env ile karşılaştırır; .env.example dosyasını otomatik referans almaz. Şablona karşı taramak için python -m envdoctor --format json audit ./src --env .env.example kullanın. --env burada karşılaştırılacak dosyayı seçer.

stale_in_env içindeki LOG_LEVEL, taranan kapsamda kullanım bulunmadığını gösterir. Başka bir servis, dağıtım betiği veya dinamik erişim bu anahtarı kullanıyor olabilir. Bu rapora bakıp anahtarı otomatik silmeyin.

{
  "scanned_paths": [
    "src"
  ],
  "total_usages": 4,
  "referenced_keys_count": 4,
  "known_keys_count": 4,
  "missing_from_env": [
    "SENTRY_DSN"
  ],
  "stale_in_env": [
    "LOG_LEVEL"
  ]
}

Çıkış kodları: başarı, uyuşmazlık ve kullanım hatası

Bu örneklerde 0 kontrolün geçtiğini veya sync işleminin tamamlandığını, 1 check/audit tarafından uyuşmazlık bulunduğunu, 2 ise eksik dosya ya da hatalı komut kullanımı gibi bir sorunu ifade ediyor. Var olmayan missing.env dosyasıyla çalıştırılan check, çıkış kodu 2 ve dosya bulunamadı mesajı döndürdü.

PowerShell'de komutun hemen ardından $LASTEXITCODE ile sonucu okuyabilirsiniz. CI tarafında yalnızca açıklama metnini değil çıkış kodunu değerlendirin. Çıktıyı güvenli bir rapora dönüştürmeden paylaşmayın: audit raporu kod satırlarından parçalar içerir.

python -m envdoctor --format json check --strict
$LASTEXITCODE

python -m envdoctor --format json audit ./src
$LASTEXITCODE

Regex taramasının sınırlarını bilin

Bu yazının önceki sürümündeki AST analizi ifadesi yanlıştı. İncelenen auditor.py, düzenli ifadelerle ve satır bazında tarama yapıyor. Python'da os.getenv ve os.environ gibi doğrudan erişimler; JavaScript/TypeScript'te process.env, Go'da os.Getenv ve Rust'ta env::var için kalıplar var. Dosya uzantısının tarama listesinde olması, o dilin bütün erişim biçimlerinin desteklendiği anlamına gelmez.

Aşağıdaki örnekte doğrudan os.getenv("API_TOKEN") kullanımı tanınır; anahtar adının değişkenden gelmesi ve getenv'in ayrı içe aktarılması aynı şekilde tanınmaz. Bu nedenle temiz bir audit raporu, hiçbir eksik değişken olmadığının garantisi değildir. Dinamik erişimleri ve tarama dışında kalan dosyaları ayrıca inceleyin.

Bu rehberin amacı üretim kesintilerini ortadan kaldırdığını iddia etmek değil; hangi kontrolün neyi bulduğunu tekrar çalıştırılabilir bir örnekle göstermek. Kaynak kodu ve proje açıklaması aşağıdaki bağlantılarda bulunuyor. İçerik 6 Ekim 2026'da güncellendi; ilk yayın tarihi korunmuştur.

import os
from os import getenv

key = "API_TOKEN"
direct = os.getenv("API_TOKEN")
dynamic = os.getenv(key)
aliased = getenv("API_TOKEN")