Por que .env no Git é um erro fatal – Mesmo em projetos privados

🔖 Visão Geral

Muitos desenvolvedores acreditam erroneamente que “em repositório privado, é seguro comitar .env”. Este post derruba esse mito, apresenta riscos reais baseado em experiências práticas (eu mesmo já cometi esse erro), e ensina práticas seguras — desde ferramentas modernas até integração contínua.

Nesse post, você vai aprender a:

Entender por que é perigoso comitar .env, mesmo em repositórios privados
Conhecer casos reais de incidentes de segurança
Usar dotenv-cli para alternar ambientes com segurança
Implementar verificações automáticas com git-secrets e hooks no pre-commit
Utilizar serviços robustos como AWS Secrets Manager e Doppler

1. O mito: “Privado = seguro”

A falsa sensação de segurança em repositórios privados é perigosa. Aqui compartilho alguns exemplos reais:

Acesso concedido a consultores eventuais, sem revogação de acesso adequada …
Repositório privado que se tornou público por acidente e acreditem … não é só o estagiário ou o júnior da empresa que cometem erros …
Tecnologia adquirida por outra empresa, expandindo o acesso, como por exemplo: “integrações de repositório com outras ferramentas de mercado” …

2. Três razões pelas quais isso é arriscado

1. Controle de acesso é dinâmico

Conforme o projeto cresce, mais pessoas ou organizações podem ganhar acesso.

2. Histórico do Git é permanente

Mesmo que você delete .env, ele permanece nos commits antigos:

1
2


git rm .env
git commit -m "removendo do repositório arquivo .env"

3. Erros humanos são comuns

Exemplos: alteração acidental para public, push no repositório errado, falha ao tratar forks.

3. Casos reais de vazamento

Caso 1: Uso indevido de API
Chaves como OPENAI_API_KEY e credenciais AWS em .env foram expostas. Resultado: em vez de US$50 mensais, houve fatura de US$15.000 … isso não aconteceu comigo (por sorte), mas aqui vai algumas fontes:

Regarding the latest breach where .env files were leaked (Reddit)
Attackers Exploit Public .env Files to Breach Cloud Accounts in Extortion Campaign (The Hackers News)

Caso 2: Ataque ao banco de dados
Credenciais do banco (por ex. DATABASE_URL) que podem vazar registros de clientes e serem expostos na internet, sim isso pode gerar multa por violação do GDPR ou no Brasil pela LGPD; Abaixo cito alguns exemplos reais de vazamento:

Report: unidentified database exposes 200 million Americans (Cybernews)

✅ 4. Como gerenciar variáveis de ambiente corretamente

✅ Passo 1: configurar `.gitignore`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


.properties
.env
.env.local
.env.development
.env.staging
.env.production
.env.*.local
node_modules/
npm-debug.log*
.next/
out/
.DS_Store
Thumbs.db
target/

✅ Passo 2: criar `.env.example`

1
2
3
4
5
6


# .env.example
NEXT_PUBLIC_APP_NAME=MyApp
DATABASE_URL=postgresql://username:password@localhost:5432/myapp
OPENAI_API_KEY=sk-xxxx
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

✅ Passo 3: váriaveis de ambiente definidas em seu repositório

Algumas das ferramentas de armazenamento de projetos Git podem te ajudar a definir variáveis de ambiente diretamente no repositório, evitando o uso de .env com valores sensíveis.

Ferramentas como:

GitLab (https://gitlab.com)
GitHub (https://github.com)

Exemplo utilizando o Gitlab:

No GitLab, defina as varáveis que seriam utilizadas em seu .env e outros segredos em Settings > CI/CD > Variables:

Github Variables

Exemplo utilizando o Github:

No Github, adicione os secrets do seu .env em “Settings > Secrets and variables > Actions > Variables”:

Github Variables

5. Alternância segura entre ambientes

Gerenciar múltiplos ambientes de forma segura e organizada é essencial em qualquer projeto moderno — especialmente ao lidar com variáveis sensíveis como chaves de API, conexões com banco de dados e tokens de serviços externos.

1

npm install --save-dev dotenv-cli

E no package.json:

1
2
3
4


"scripts": {
  "dev": "dotenv -e .env.development -- next dev",
  "build:production": "dotenv -e .env.production -- next build"
}

6. Validação de variáveis

1
2
3
4
5
6
7


require('dotenv').config();
const requiredEnvVars = ['DATABASE_URL','OPENAI_API_KEY'];
const missing = requiredEnvVars.filter(v => !process.env[v]);
if (missing.length) {
  console.error('❌ Variáveis faltantes:', missing);
  process.exit(1);
}

Esse pequeno trecho de código é um exemplo de como boas práticas simples podem evitar dores de cabeça lá na frente. Verificar variáveis de ambiente logo na inicialização da sua aplicação é uma forma eficaz de manter seu ambiente mais seguro, estável e previsível — especialmente em cenários com múltiplos ambientes ou equipes.

7. Plataformas cloud com gestão segura

Vercel

1
2


vercel env add DATABASE_URL production
vercel env pull .env.local

O Vercel oferece uma CLI poderosa que permite controlar essas variáveis de forma segura e integrada com seus ambientes (development, preview e production).

Next.js

Variáveis privadas: process.env.OPENAI_API_KEY (somente server-side)
Variáveis públicas (cliente): prefixo NEXT_PUBLIC_...

8. Ferramentas de segurança

✅ `git-secrets`

1
2
3
4


brew install git-secrets
git secrets --install
git secrets --register-aws
git secrets --add 'sk-[a-zA-Z0-9]{48}'

✅ Hooks com `pre-commit`

Exemplo .pre-commit-config.yaml para prevenir commits de .env e outros erros.

9. Fluxo em equipe

Vaults como LastPass ou Bitwarden
Arquivos criptografados com GPG
Serviços temporários como Privnote

Serviços especializados:

AWS Secrets Manager
Google Secret Manager
HashiCorp Vault
Doppler

10. Checklist de boas práticas

.env* no .gitignore
.env.example presente no repositório como exemplo para os demais desenvolvedores utilizar como base
Compartilhamento seguro em equipe
Ferramentas como git-secrets, pre-commit, dotenv-cli
Validação de ambiente
Gestão via cloud (e.g., Vercel)
Rotação de segredos
Uso de serviços de gestão de segredos

11. O que fazer se “commitou” o `.env`

1. Revogue credenciais imediatamente

2. Apague o histórico Git completamente:

1
2
3


git filter-branch --force --index-filter   'git rm --cached --ignore-unmatch .env'   --prune-empty --tag-name-filter cat -- --all
git push origin --force --all
git push origin --force --tags

⚠️ Todos devem re-clonar o repositório após isso.

Consideraçções finais

Gerenciar variáveis de ambiente é mais que técnica — é cultura de segurança. Mesmo repositórios privados não garantem proteção. Adotar práticas como dotenv-cli, validação, hooks e gestão via serviços de segredos eleva a segurança e eficiência do projeto. Comece mandando bem já no seu próximo projeto!