Come creare .env.example senza pubblicare API key e segreti

.env e .env.example hanno scopi diversi

.env

Contiene valori locali reali. Di norma resta fuori da Git e può includere credenziali o configurazioni specifiche della macchina.

.env.example

È versionato. Elenca le variabili richieste usando placeholder sicuri e commenti che aiutano il setup.

Procedura sicura

1. Apri il file locale senza copiarlo direttamente nel repository.
2. Mantieni soltanto i nomi delle variabili realmente necessarie.
3. Sostituisci ogni valore sensibile con un placeholder esplicito.
4. Conserva valori innocui solo se sono validi per tutti gli ambienti.
5. Aggiungi commenti su formato, obbligatorietà e provenienza del valore.
6. Verifica che .env e le varianti locali siano incluse in .gitignore.
7. Controlla il diff prima del commit.

Esempio corretto

# URL pubblico dell'applicazione, senza slash finale
APP_BASE_URL=http://localhost:4200

# Obbligatoria. Creala nel dashboard del provider.
OPENAI_API_KEY=your_api_key_here

# Obbligatoria. Stringa di connessione del database locale.
DATABASE_URL=postgresql://user:password@localhost:5432/app_db

# Opzionale. Usa "true" solo in sviluppo locale.
DEBUG=false

Esempio sbagliato da evitare

Il caso pericoloso è un file che sembra dimostrativo ma contiene valori realistici, token parzialmente mascherati o endpoint privati. Se un valore arriva da una dashboard o da un ambiente reale, non dovrebbe finire in .env.example.

# Sbagliato: valori troppo realistici
OPENAI_API_KEY=sk-proj-abc123...
DATABASE_URL=postgresql://admin:password-reale@db.internal:5432/prod
STRIPE_SECRET_KEY=sk_live_...
JWT_SECRET=super-secret-usato-in-dev

Cosa va trattato come segreto

• API key, token OAuth e personal access token.
• Password, connection string e credenziali database.
• Chiavi private, certificati privati e service account.
• Webhook secret e signing secret.
• URL che incorporano username, password o token.
• Valori copiati da dashboard cloud anche se usati solo per test.

API key nel frontend: perché è pericoloso

Se una chiave finisce nel codice frontend, può essere letta da chiunque apra il sito, analizzi il bundle o controlli le richieste di rete. Metterla in una variabile ambiente del frontend non la rende segreta: durante la build viene comunque incorporata nel codice pubblico.

.env.example deve quindi aiutare a distinguere variabili pubbliche e variabili private. Le chiavi server-side vanno usate da backend, funzioni serverless o ambienti protetti, non dal browser.

• Variabili pubbliche: configurazioni innocue che possono essere viste dagli utenti.
• Variabili private: API key, secret, token e connection string da tenere lato server.
• Prefissi come PUBLIC_ o VITE_ indicano spesso valori esposti al browser.
• Se una chiave permette di spendere soldi, leggere dati o modificare risorse, non è frontend-safe.

Checklist prima del commit

1. Controlla che .env, .env.local e file equivalenti siano in .gitignore.
2. Apri il diff e cerca token, password, URL privati e valori copiati da dashboard reali.
3. Verifica che .env.example contenga placeholder chiaramente finti.
4. Aggiungi commenti solo dove aiutano il setup, senza rivelare dettagli interni.
5. Se hai dubbi su una variabile, trattala come segreta finché non hai verificato.

Se un segreto è già finito su Git

Cancellare la riga nell’ultimo commit non basta: il valore può essere presente nella cronologia, nei fork, nelle cache o nei log CI.

1. Revoca o ruota subito la credenziale dal provider.
2. Rimuovi il valore dal codice e aggiungi la regola corretta a .gitignore.
3. Controlla cronologia, pull request, issue, log e artifact pubblicati.
4. Valuta la pulizia della history in base al repository e coordinala con il team.

FAQ su .env.example e segreti

.env.example va committato?

Sì, di solito va versionato perché documenta le variabili necessarie. Devono però esserci solo placeholder sicuri e valori non sensibili.

.env va committato?

No, normalmente .env contiene valori locali reali e deve restare fuori da Git tramite .gitignore.

Posso lasciare una API key finta?

Sì, se è evidentemente finta, per esempio your_api_key_here. Non usare chiavi reali troncate, mascherate o prese da ambienti di test.

Se una chiave è già finita su Git basta cancellarla?

No. Devi revocarla o ruotarla dal provider, perché può essere ancora presente nella cronologia, nei fork, nelle cache o nei log.

Fonti primarie

Le raccomandazioni su chiavi client-side, repository e variabili ambiente seguono la documentazione dei fornitori. Adatta sempre nomi e strumenti allo stack effettivamente usato dal progetto.

• OpenAI: Best Practices for API Key Safety ↗
• GitHub Docs: Ignoring files ↗