.env bestand veilig beheren: checklist + .gitignore

# .gitignore
# Geheimen: nooit in git
.env
.env.*
!.env.example

# .env.example (wel in git)
# Kopieer naar .env.local en vul de echte waarden in
DATABASE_URL=postgresql://gebruiker:wachtwoord@localhost:5432/mijnapp
STRIPE_SECRET_KEY=sk_test_vervang_mij
NEXT_PUBLIC_APP_URL=http://localhost:3000

Een .env bestand met echte keys hoort niet in git. Je zet een leeg voorbeeld (.env.example) wel in je code en houdt je ingevulde bestand (.env.local) lokaal, met een regel in je .gitignore. Zo ziet elke developer wat de app nodig heeft, en komen je keys niet in je repository terecht.

Hierboven staat de checklist met het .gitignore-sjabloon. Hieronder leg ik uit waarom het werkt, hoe je het toepast en waar het meestal misgaat.

Waarom heb je twee .env bestanden nodig?

Je app heeft instellingen nodig: een Stripe-key, een databaseadres, een API-sleutel van een AI-dienst. Die staan niet in je code, maar in een .env bestand. Dat is op zich goed. Het probleem begint wanneer dat bestand in git belandt.

Daarom splits je het in twee:

• .env.example is het lege formulier. Enkel namen, met een dummywaarde erachter. Dit bestand gaat mee in je code.
• .env.local is het ingevulde formulier. Hier staan je echte keys. Het staat alleen op jouw machine.

Dat tweede bestand houdt je buiten git. De documentatie van Next.js zegt het zo: .env*.local hoort in je .gitignore, omdat die bestanden bedoeld zijn om genegeerd te worden. .env.local is de plek waar je geheimen bewaart.

Hoe zet je .env.example en .env.local op?

Stap 1: schrijf het voorbeeld

Loop door je code en noteer elke variabele die je ophaalt. Zet ze met een nepwaarde in .env.example. Geef je de waarde een duidelijke naam, zoals sk_test_vervang_mij, dan weet niemand ooit twijfelen of het een echte key is.

Stap 2: kopieer en vul in

Kopieer het voorbeeld naar .env.local en vul je echte waarden in. Je app leest dat bestand bij het opstarten. Bij Next.js gebeurt dat automatisch. Bij andere frameworks verschilt de bestandsnaam of heb je een kleine library nodig. Check dat in de documentatie van je framework.

Stap 3: zet je .gitignore goed, vóór je eerste commit

Het volgorde is belangrijk. Een .gitignore werkt enkel voor bestanden die git nog niet volgt. Heb je .env.local al eens gecommit, dan blijft git het volgen, ook als je het later in .gitignore zet. Je moet het dan eerst uit de index halen met git rm --cached.

Controleer daarna altijd met git check-ignore -v .env.local. Dat kost vijf seconden en je weet zeker dat het klopt.

Waarom werkt dit goed voor een nieuwe developer?

Stel dat je een kleine webshop-app hebt en er komt een collega bij. Zonder voorbeeldbestand begint die te vragen: welke keys heb ik nodig, waar haal ik de databasegegevens, wat staat er nog ontbrekend? Het antwoord komt dan via de chat, vaak met een wachtwoord erbij.

Met een .env.example is het verhaal kort: clonen, voorbeeld kopiëren, keys invullen, draaien. De collega ziet in één blik wat de app nodig heeft. Jij hoeft niets te typen.

Wat als er toch een key in git terechtkomt?

Dit gebeurt, ook bij ervaren developers. Het bestand verwijderen en opnieuw committen lost niets op. Git bewaart de geschiedenis, dus de key staat nog in je eerdere commits. Een key uit git halen betekent niet dat hij niet eerder zichtbaar was.

Doe dit in deze volgorde:

1. Trek de key in bij de dienst zelf (Stripe, je database, je AI-provider) en maak een nieuwe aan. Dit eerst, want vanaf dat moment is de gelekte key waardeloos.
2. Zet de nieuwe key in je .env.local.
3. Schoon je geschiedenis op. git-filter-repo is de moderne, aanbevolen tool om git-geschiedenis te herschrijven en vervangt het oudere git filter-branch. GitHub beschrijft de stappen in zijn documentatie over het verwijderen van gevoelige data uit een repository.
4. Laat je collega's opnieuw clonen, want een herschreven geschiedenis verandert de commits.

Stap 3 is werk, en soms niet voldoende als iemand je repository al gekopieerd heeft. Daarom staat intrekken bovenaan.

Beschermt GitHub je tegen gelekte keys?

Gedeeltelijk. Push protection voor gebruikers staat standaard aan en stopt je met het pushen van secrets naar publieke repositories op GitHub. Daarnaast draait secret scanning automatisch en gratis op publieke repositories. Voor privé-repositories van een organisatie is het een betaalde optie: het vraagt GitHub Secret Protection.

Reken er niet op als enige verdediging. Het herkent bekende soorten keys, geen elk wachtwoord dat je in een gewone variabele zet. Je .gitignore blijft de eerste lijn.

Welke valkuilen kom je tegen?

NEXT_PUBLIC_ stuurt je waarde naar de browser

In Next.js zijn variabelen standaard enkel op de server beschikbaar. Zet je er NEXT_PUBLIC_ voor, dan worden ze bij next build in de JavaScript-bundel geplaatst. Iedereen die je site opent, kan ze lezen. Een publieke ID (zoals een analytics-ID) is oké. Een geheime key niet.

Echte waarden in het voorbeeldbestand

Dit is de meest voorkomende fout: je kopieert je .env.local naar .env.example en vergeet de waarden leeg te maken. Kijk altijd na vóór je commit. Een snelle controle: staat er iets in dat je niet zou voorlezen aan een onbekende?

Voorbeeldbestand dat achterloopt

Je voegt een variabele toe in code, maar vergeet het voorbeeld. De volgende developer krijgt een foutmelding en begint te vragen. Werk .env.example bij in dezelfde commit.

Productiekeys op je laptop

Je live-keys horen thuis in de instellingen van je hosting, niet in een bestand op je machine. Op je laptop werk je met testkeys. Dan is een gestolen laptop of een foutieve commit minder erg.

Bouw je zelf met AI of automatisaties?

Zodra je tools koppelt, zoals een AI-API, een betaalprovider of een CRM, stapelen de keys zich op. Ben je met AI automations bezig, houd dan voor elk project hetzelfde patroon aan: één voorbeeld, één lokaal bestand, één .gitignore. Laat je een CRM op maat of een website bouwen, vraag dan wie de keys beheert en waar ze staan. Een goede ontwikkelaar kan dat in twee zinnen uitleggen.

Twijfel je of jouw project goed is opgezet? Neem contact op voor een vrijblijvend gesprek.