Netlify Environment Variables ve Secret Yönetimi Rehberi

Netlify environment variables, build komutunu, Functions ve Edge Functions çalışma zamanını veya farklı deploy context’lerinin davranışını kaynak kodu değiştirmeden yapılandırmak için kullanılan anahtar-değer çiftleridir. Production, Deploy Preview, Branch Deploy ve yerel geliştirme için aynı key’e farklı değer atanabilir. Ancak bir değerin Netlify dashboard’da maskelenmesi, browser bundle’a eklendiğinde gizli kalacağı anlamına gelmez.

Güvenli yönetim üç soruyla başlar: Değeri hangi deploy context kullanacak, hangi scope gerçekten erişmeli ve değer server tarafında mı yoksa ziyaretçinin browser’ında mı çalışacak? Bu ayrımlar yapılmadan eklenen API key’ler, preview ortamına yanlış production erişimi veya public JavaScript bundle’a secret sızıntısı yaratabilir.

Öne Çıkanlar

• Netlify’de site-specific ve team genelinde shared environment variables bulunur.
• Site variable, aynı key’e sahip shared variable’ı ilgili context ve scope’ta override edebilir.
• Production, Deploy Preview, Branch Deploy, belirli branch, Preview Server ve Local Development için contextual values tanımlanabilir.
• Pro ve Enterprise planlarında variable erişimi Builds, Functions, Runtime ve Post processing scope’larına sınırlandırılabilir.
• netlify.toml içindeki aynı key, UI/CLI/API ile tanımlanan değeri override eder.
• Vite VITE_, Next.js NEXT_PUBLIC_ ve Create React App REACT_APP_ önekleriyle client’a açılan değerler secret değildir.
• Secret değiştiğinde yeni deploy veya runtime yenilemesi gerekebilir; eski deploy’un içeriği geriye dönük değişmez.

Netlify Environment Variable Nedir?

Environment variable, uygulama koduna doğrudan sabit yazmak istemediğiniz konfigürasyonu dışarıdan sağlar. Örnekler:

• API origin,
• CMS environment adı,
• Feature flag,
• Analytics property ID,
• Database connection string,
• Ödeme sağlayıcısı secret’ı,
• E-posta servis token’ı,
• Build sırasında kullanılacak Node sürümü.

Public ve private değerler aynı şey değildir. SITE_NAME=Ortak Alan gibi bir değer browser’da görülebilir. PAYMENT_SECRET=... yalnız server-side kodda kullanılmalıdır.

Netlify iki temel variable türü sunar:

1. Site environment variable: Yalnız belirli bir proje için tanımlanır. 2. Shared environment variable: Team içindeki birden fazla projeye sunulur.

Shared variable, ortak API endpoint veya organizasyon genelinde kullanılan konfigürasyon için yararlı olabilir. Buna karşılık tek bir yüksek yetkili secret’ı onlarca projeye açmak, olası bir sızıntının etki alanını büyütür. Shared kullanım kararını kolaylık kadar blast radius açısından da değerlendirin.

UI Üzerinden Variable Nasıl Eklenir?

Netlify dashboard’da project configuration içindeki environment variables bölümünden yeni key eklenebilir. Arayüz adları değişebilse de karar sırası şöyledir:

1. Key adını belirleyin. 2. Site veya shared türünü seçin. 3. Değerin secret içerip içermediğini işaretleyin. 4. Gerekli scope’ları seçin. 5. Tek genel değer veya context-specific values tanımlayın. 6. Değişikliği kaydedin. 7. Gerekliyse yeni deploy başlatın.

Key adları yalnız harf, rakam ve underscore içerebilir; ilk karakter harf olmalıdır. Örneğin:

``text API_KEY geçerli PUBLIC_URL geçerli 1API_KEY geçersiz _PRIVATE geçersiz ``

Netlify’nin güncel dokümanında key için 255 karakter, value için 5. 000 karakter sınırı belirtiliyor. Functions gibi çalışma zamanlarında altyapı sağlayıcısının toplam environment boyutu sınırları da geçerli olabilir. Çok büyük JSON veya sertifika zincirini tek variable içine koymak yerine uygun secret/file yönetimi kullanın.

Secret değerli variable’ları “Contains secret values” olarak işaretlemek ek erişim kısıtları ve Secrets Controller özellikleri sağlayabilir. Bu ayar, yanlışlıkla client bundle’a eklenen değeri korumaz; yalnız Netlify içindeki görüntüleme ve yönetim katmanını güçlendirir.

CLI ve .env Dosyasıyla Nasıl Çalışılır?

Netlify CLI, dashboard’daki variables üzerinde işlem yapabilir. Güncel komutları sürümünüzde doğrulayın:

``bash netlify env:list netlify env:get API_ORIGIN netlify env:set DEMO_MODE true ``

Komut çıktısını paylaşırken secret value, site ID ve team bilgilerini redakte edin. Gerçek secret’ı shell command içine açık yazmak terminal history’ye girebilir. Interactive prompt, CI secret store veya güvenli yönetim akışı kullanın.

Yerel . env örneği:

``env PUBLIC_API_ORIGIN=http://localhost:9999 SERVER_API_TOKEN=dummy-local-value ``

. gitignore:

``gitignore .env .env.* !.env.example ``

. env. example yalnız gereken key’leri gösterir:

``env PUBLIC_API_ORIGIN=https://replace-me.example SERVER_API_TOKEN=replace-with-local-secret ``

Netlify UI’daki context values ile yerel . env aynı kaynağın eş anlamlısı değildir. Framework ve Netlify Dev’in hangi dosyayı hangi sırada okuduğunu test edin. “Yerelde çalışıyor” sonucu production variable’ın tanımlı olduğunu göstermez.

UI, CLI ve API üzerinden yapılan variable değişiklikleri Netlify team audit log’una kaydedilebilir. Bu, secret’ın değerini loglamak değil, kim tarafından oluşturulduğunu veya değiştirildiğini izlemek için yararlıdır.

Scope Nasıl Seçilir?

Netlify environment variables varsayılan olarak tüm scope’lara açık olabilir. Pro ve Enterprise planlarında erişim şu alanlarla sınırlandırılabilir:

Scope	Kullanım alanı	Örnek
Builds	Site ve Function build adımları	Node sürümü, build-time CMS token
Functions	Functions, Edge Functions, On-demand Builders	API secret, database connection
Runtime	Forms ve signed proxy redirects	Form token, proxy signing secret
Post processing	Snippet injection	Kontrollü analytics config

Minimum yetki ilkesi uygulayın. Yalnız Function runtime’da gereken ödeme secret’ını Builds ve Post processing scope’larına açmayın. Build sırasında gerçekten gereken CMS token ise yalnız Functions scope’unda bulunursa static generation başarısız olabilir.

Scope seçimi erişim yüzeyini daraltır; uygulama kodundaki yetkilendirme sorununu çözmez. Function secret’a erişebiliyorsa Function endpoint’inin authentication, input validation ve rate limiting kontrolleri yine gerekir.

Planınız scope seçimini desteklemiyorsa variable’ın hangi ortamlarda erişilebilir olduğunu daha dikkatli threat model edin. Kritik secret için ayrı team/proje, dış secret manager veya mimari değişiklik gerekebilir.

Deploy Context Nasıl Seçilir?

Aynı key için farklı context values tanımlanabilir:

Context	Örnek değer
Production	https://api.example.com
Deploy Previews	https://preview-api.example.com
Branch deploys	https://staging-api.example.com
Branch: release/*	https://release-api.example.com
Local development	http://localhost:9999

Branch-specific value, eşleşen branch’in Deploy Preview, Branch Deploy ve deploy permalink’lerinde kullanılabilir. Örneğin release/*, release/1. 0 ve release/1. 1 branch’lerini hedefleyebilir.

Production secret’ını preview’a varsayılan fallback ile açmak risklidir. Dış katkıcının pull request’i build sırasında script çalıştırabilir; preview uygulaması da gerçek kullanıcı verisine erişebilir. Preview için sandbox, read-only veya kısa ömürlü credential kullanın.

Context ayırımı yalnız URL değiştirmek için değildir. Şunları da ayırın:

• Database/schema,
• Ödeme modu,
• E-posta alıcı allowlist’i,
• Analytics property,
• Object storage bucket,
• AI model bütçesi ve rate limit,
• Webhook callback.

Preview verisini production’dan izole etmek, yanlış merge’den çok test sırasında yapılan işlemlerin canlı sisteme ulaşmasını önler.

Override Kuralları Nasıl Çalışır?

Netlify’de aynı key birden fazla yerde bulunabilir. Temel öncelikler:

• netlify.toml içinde tanımlanan aynı key, UI/CLI/API değerini override eder.
• Site variable, aynı key’e sahip shared variable’ı tanımlı scope ve context’te override eder.
• Daha spesifik deploy context veya branch value, genel context değerinin önüne geçer.

Örnek problem:

• Team shared API_ORIGIN=https://api.example.com
• Site preview API_ORIGIN=https://preview-api.example.com
• netlify.toml genel [build.environment] API_ORIGIN="https://legacy.example.com"

Build sırasında TOML değeri beklenmedik biçimde kazanabilir. Sorun çözmede key’i tüm kaynaklarda arayın:

``bash grep -R "API_ORIGIN" . --exclude-dir=node_modules --exclude-dir=.git ``

Repository araması UI’daki değerleri göstermez. Netlify dashboard, CLI output ve deploy logundaki context bilgisi ayrıca incelenmelidir.

Secret’ları netlify. toml içine koymayın. Dosya repository’de tutulur ve daha gelişmiş scope/audit seçeneklerinden yararlanmaz.

Build İçinde Environment Variable Nasıl Okunur?

Node tabanlı build script’inde:

```js const apiOrigin = process.env.API_ORIGIN;

if (! apiOrigin) { throw new Error("API_ORIGIN is required during build"); } ```

Build-time değer statik HTML veya JavaScript içine yazılabilir. Bu nedenle server secret’ın build’e açık olması, otomatik olarak gizli kalacağı anlamına gelmez. Framework static generation sırasında değeri output’a serialize ediyorsa ziyaretçi görebilir.

Build artifact taraması yapın:

``bash grep -R "dummy-secret-marker" dist .next 2>/dev/null ``

Yalnız dummy marker kullanın; gerçek secret’ı test için bile çıktı klasörüne sokmayın. Source map ve debug manifest’lerini de inceleyin.

Variable eksikse build’i erken ve anlaşılır mesajla durdurmak, uygulamanın production’da belirsiz biçimde bozulmasından daha iyidir. Hata mesajında secret değerini yazdırmayın.

Netlify Functions İçinde Variable Nasıl Kullanılır?

Güncel JavaScript/TypeScript Function örneği:

```ts export default async () => { const apiToken = process.env.SERVER_API_TOKEN;

if (! apiToken) { return Response. json( { error: "Server configuration is missing" }, { status: 500 } ); }

return Response. json({ configured: true }); }; ```

Function response veya log içinde token’ın kendisini döndürmeyin. Yalnız “var/yok”, son dört karakteri bile gerektirmeyen güvenli fingerprint veya configuration version kullanılabilir.

Variable değişikliği sonrası Function’ın hangi deploy sürümüyle çalıştığını doğrulayın. Immutable deploy geçmişindeki eski Function paketi, oluşturulduğu context davranışını taşıyabilir. Rollback yaptığınızda kod ve güncel variable kombinasyonunun uyumlu olup olmadığını test edin.

Edge Functions İçinde Variable Nasıl Kullanılır?

Edge Function runtime ve API biçimi normal Functions’tan farklı olabilir. Netlify’nin güncel Edge Functions dokümanındaki erişim yöntemini kullanın. Kullanılan runtime’da Node process. env varsayımı her zaman doğru değildir.

Kavramsal örnek:

``ts export default async () => { const value = Netlify.env.get("EDGE_CONFIG_VALUE"); return new Response(value ? "configured" : "missing"); }; ``

Bu kodun gerçek API biçimi kullanılan Netlify runtime sürümünde doğrulanmalıdır. Secret’ı response’a döndürmeyin. Edge logic kişiselleştirilmiş yanıt üretiyorsa shared cache’e yanlışlıkla girmediğini de test edin.

Vite, React ve Next.js Client-Side Değişken Uyarıları

Frontend framework’leri belirli prefix’leri browser bundle’a açar:

Framework	Public/client prefix	Erişim örneği
Vite	VITE_	import.meta.env.VITE_API_ORIGIN
Next.js	NEXT_PUBLIC_	process.env.NEXT_PUBLIC_SITE_NAME
Create React App	REACT_APP_	process.env.REACT_APP_API_URL

Şu örnek güvenli değildir:

``env VITE_PAYMENT_SECRET=real-private-key ``

Adında “SECRET” bulunması browser’a dahil edilmesini engellemez. Build sonrası JavaScript dosyasında değer açık biçimde aranabilir.

Public değerler için bile şu soruları sorun:

• Kullanıcı bu değerle doğrudan ücretli API çağrısı yapabilir mi?
• Domain restriction veya public key modeli var mı?
• Key yalnız tanımlayıcı mı, yoksa yetki veriyor mu?
• Abuse durumunda rate limit ve bütçe sınırı var mı?

Google Maps browser key gibi bazı anahtarlar tasarım gereği public olabilir; yine de referrer/domain restriction ve quota gerekir.

Secret Rotation Nasıl Yapılır?

Secret rotation yalnız yeni değer eklemek değildir. Güvenli sıra:

1. Yeni credential oluşturun. 2. Mümkünse eski ve yeni credential’ı kısa süre birlikte geçerli tutun. 3. Netlify’de yeni değeri doğru scope/context’e ekleyin. 4. Yeni deploy veya runtime doğrulaması yapın. 5. Log ve health check ile yeni credential’ın kullanıldığını doğrulayın. 6. Eski credential’ı sağlayıcı tarafında iptal edin. 7. Audit log ve üçüncü taraf erişim kayıtlarını inceleyin. 8. Olay kaydı ve bir sonraki rotation tarihini yazın.

Secret Git geçmişine girdiyse yalnız variable’ı değiştirmek yeterli değildir. Sağlayıcı tarafında revoke edin; deploy artifact, build log, source map, PR comment ve chat paylaşımını da inceleyin.

Düzenli rotation sıklığı risk ve sağlayıcı yeteneğine göre belirlenmelidir. Sırf takvim için sık rotation yapıp operasyon hatası yaratmak yerine otomatik, gözlemlenebilir ve geri dönüşlü süreç kurun.

Sensitive Variable Policy Ne İşe Yarar?

Public repository’ye bağlı sitelerde güvenilmeyen deploy’ların hassas variables’a erişimi özel risk yaratır. Netlify’nin sensitive variable policy ayarı, bu erişimin nasıl ele alınacağını kontrol etmeye yardımcı olur.

Threat model:

• Dış katkıcı PR açar.
• Build script’i veya dependency lifecycle script’i çalışır.
• Script environment variable’ı dışarı göndermeye çalışır.
• Preview logu veya generated artifact secret içerir.

Koruma:

• Public repo policy’yi inceleyin.
• Untrusted deploy’a production secret vermeyin.
• Preview için düşük yetkili ayrı token kullanın.
• Dependency install script’lerini ve lockfile değişikliklerini review edin.
• Build log ve output’ta dummy marker testi yapın.
• Gerekirse dış katkı branch’leri için secret gerektirmeyen build yolu oluşturun.

Değişken Görünmüyorsa Nasıl Sorun Çözülür?

Yanlış context

Variable yalnız Production’a atanmış, test ise Deploy Preview’da çalışıyor olabilir. Deploy context’i ve branch-specific override’ı kontrol edin.

Yanlış scope

Değer Builds scope’unda fakat runtime Function içinde okunmaya çalışılıyor olabilir. Gerekli scope’u açın; gereksiz scope eklemeyin.

Yeni deploy alınmadı

Build-time değişken değiştiğinde mevcut statik output geriye dönük değişmez. Yeni build/deploy başlatın.

Framework prefix’i yanlış

Vite’ta REACT_APP_ veya Next. js’te VITE_ kullanılmış olabilir. Framework’ün public variable kuralını kontrol edin.

netlify.toml override ediyor

Repository içindeki [build. environment] aynı key’i UI değerinin önüne geçiriyor olabilir.

Değer server’da var, browser’da yok

Bu istenen güvenli davranış olabilir. Private variable’ın client’a otomatik gelmemesi hatadan ziyade doğru izolasyondur.

Reserved key kullanılıyor

Netlify’nin read-only configuration variables adları override edilemez. Key’i değiştirin.

Dummy Değerlerle Zorunlu Exposure Testi

Gerçek secret yerine benzersiz ve zararsız marker’lar kullanın:

``text PUBLIC_MARKER_PROD=public-prod-7f3a PUBLIC_MARKER_PREVIEW=public-preview-8b21 SERVER_MARKER_PROD=server-prod-dummy-4c6e SERVER_MARKER_PREVIEW=server-preview-dummy-9a10 ``

Test matrisi:

Kontrol	Production	Deploy Preview	Staging branch
Build output public marker	Beklenen context	Beklenen context	Beklenen context
Browser bundle public marker	Görünmeli	Görünmeli	Görünmeli
Browser bundle server marker	Görünmemeli	Görünmemeli	Görünmemeli
Function server marker	Yalnız var/yok	Yalnız var/yok	Yalnız var/yok
Function gerçek değeri response’ta	Asla	Asla	Asla
Audit log	Değişiklik kaydı	Değişiklik kaydı	Değişiklik kaydı

> Editör notu — zorunlu özgün kanıt: Bu taslak hazırlanırken dummy variables üç context’e atanmadı ve build/browser/Function exposure testi çalıştırılmadı. Yayından önce temiz bir demo projede Netlify CLI ve dashboard kullanılarak yalnız sahte marker’lar tanımlanmalı; Node, framework ve CLI sürümleri, commit SHA, context, artifact arama komutları ve redakte ekranlar kaydedilmelidir. Gerçek API key test materyaline hiçbir aşamada konmamalıdır.

> Görsel notu: Shared/site → context → scope → build/server/browser akışını gösteren exposure diyagramı, redakte variable UI ekranı ve test matrisi hazırlanmalıdır.

> İç link editör notu: Netlify güvenlik, Functions ve AI Gateway rehberleri yayımlandığında secret yönetimi bölümlerine doğal bağlantı eklenmelidir.

Netlify Environment Variables Kontrol Listesi

• [ ] Variable site mi shared mı olmalı kararlaştırıldı.
• [ ] Minimum gerekli scope seçildi.
• [ ] Production, preview, branch ve local values ayrıldı.
• [ ] Preview production verisine veya live ödeme moduna bağlı değil.
• [ ] Secret “Contains secret values” olarak işaretlendi.
• [ ] Public framework prefix’inde private değer yok.
• [ ] netlify.toml override’ı kontrol edildi.
• [ ] Build artifact ve browser bundle dummy marker ile tarandı.
• [ ] Function/Edge response ve logları secret döndürmüyor.
• [ ] Rotation, revoke ve audit sahibi belli.
• [ ] Public repo sensitive variable policy incelendi.

Sık Sorulan Sorular

Netlify environment variables güvenli mi?

Doğru scope, context ve server-side kullanım ile güvenli yönetim sağlar. Client bundle’a eklenen veya response/log içinde döndürülen değer gizli kalmaz.

.env dosyası Netlify’ye yüklenmeli mi?

Gerçek . env repository’ye commit edilmemelidir. Production değerleri Netlify UI, CLI veya API ile tanımlayın; . env. example yalnız key şemasını belgeleyebilir.

Variable değişince otomatik deploy olur mu?

Değişikliğin deployment etkisi kullanılan ayar ve akışa bağlıdır. Build-time değer için yeni deploy gereklidir; mevcut immutable output otomatik güncellenmez.

netlify.toml içindeki variable mı, UI’daki mı öncelikli?

Aynı key çakıştığında TOML değeri UI/CLI/API ile tanımlanan değeri override eder. Secret’ı TOML’a taşımak önerilmez.

Vite’taki VITE_ değeri secret olabilir mi?

Hayır. Build sırasında browser bundle’a açılır. Yalnız public konfigürasyon için kullanılmalıdır.

Kaynaklar

• Environment variables overview
• Get started with environment variables
• Use environment variables with frameworks
• Secrets Controller
• Local development with Netlify CLI
• Security and privacy for AI features

Sonuç

Netlify environment variables yönetiminde amaç yalnız API key’i koddan çıkarmak değildir. Değeri doğru site/shared katmanına, minimum scope’a ve doğru deploy context’e yerleştirmek; client ve server sınırını test etmek gerekir. Production ile preview değerlerini ayırın, public framework prefix’lerine private bilgi koymayın, netlify. toml override’larını kontrol edin ve rotation sırasında eski credential’ı gerçekten revoke edin. Güvenliği gerçek secret’la değil, benzersiz dummy marker’larla gözlemlenebilir biçimde doğrulayın.

Environment variable ve deploy context davranışını güvenli dummy değerlerle test etmek için [ücretsiz Netlify hesabı oluşturabilirsiniz](https://join. netlify. com/wmkqymu1heo2). Bu bir iş ortaklığı bağlantısıdır; bağlantı üzerinden kayıt olmanız veya ücretli plana geçmeniz halinde Ortak Alan komisyon kazanabilir.