Variáveis de ambiente e segredos: como não vazar senhas e chaves de API

Atualizado em 3 de novembro de 2026 · Leitura de 5 min

Edson Feitosa de Oliveira Junior Fundador e Engenheiro Líder · PruPru Digital Services

Variáveis de ambiente são o lugar certo para senhas de banco de dados, chaves de API de pagamento, tokens de serviços de e-mail e segredos de assinatura de JWT, que nunca deveriam estar no código-fonte. Mesmo assim, segredos vazados em repositórios estão entre as causas mais comuns de incidentes de segurança, porque robôs varrem repositórios públicos continuamente em busca de chaves e as exploram em minutos. A boa prática é simples: o código fica no repositório, a configuração sensível fica no ambiente.

O princípio: código e configuração separados

A mesma aplicação roda em ambientes diferentes (sua máquina, testes, produção), com bancos e chaves diferentes. Tudo o que muda entre ambientes, e principalmente o que é secreto, deve vir de fora do código, por variáveis de ambiente ou por um gerenciador de segredos.

O que costuma ser segredo:

• senhas e URLs de conexão com banco de dados;
• chaves de API (pagamento, e-mail, mapas, IA);
• segredos de assinatura de tokens;
• credenciais de nuvem;
• chaves privadas e certificados.

Arquivo .env no desenvolvimento

No desenvolvimento local, é comum usar um arquivo .env:

DB_URL=jdbc:postgresql://localhost:5432/loja
DB_USER=loja
DB_PASSWORD=senha-local-de-teste
JWT_SECRET=troque-por-um-valor-longo-e-aleatorio

Regras essenciais:

1. Adicione .env ao .gitignore antes do primeiro commit.
2. Crie um .env.example com os nomes das variáveis e valores fictícios, e versione esse arquivo. Ele documenta o que a aplicação precisa.
3. Use valores diferentes em cada ambiente. A senha de produção nunca deve estar na máquina de desenvolvimento.

Veja como funciona o .gitignore em Git e GitHub para iniciantes.

Lendo variáveis de ambiente na aplicação

Spring Boot

O Spring lê variáveis de ambiente automaticamente. No application.properties:

spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}
app.jwt.secret=${JWT_SECRET}

Node.js

Versões recentes do Node.js podem carregar o arquivo com node --env-file=.env app.js, ou você pode usar a biblioteca dotenv. No código:

const dbPassword = process.env.DB_PASSWORD;
if (!dbPassword) throw new Error("DB_PASSWORD não configurada");

Falhar logo na inicialização quando uma variável obrigatória está ausente evita erros confusos mais tarde.

Docker e Docker Compose

No compose, você pode referenciar um arquivo de variáveis:

services:
  api:
    build: .
    env_file: .env

Nunca coloque segredos no Dockerfile com ENV ou ARG: eles ficam gravados nas camadas da imagem e podem ser lidos por quem tiver acesso a ela. Veja Docker para iniciantes.

Em produção e no CI/CD

• Plataformas de hospedagem (Cloudflare, Vercel, Render, provedores de nuvem) têm áreas para cadastrar variáveis e segredos, que são injetados na aplicação. No Cloudflare Workers, por exemplo, segredos são configurados com wrangler secret put. Veja Cloudflare Workers: o que é.
• GitHub Actions e outras ferramentas de CI têm segredos de repositório, que aparecem mascarados nos logs.
• Gerenciadores de segredos dos provedores de nuvem e ferramentas dedicadas oferecem controle de acesso, auditoria e rotação.

Cuidados que vão além do .env

• Não registre segredos nos logs. Cuidado com logs que imprimem a configuração inteira ou os cabeçalhos completos das requisições. Veja logs em produção.
• Não coloque segredos no front-end. Tudo o que vai para o navegador ou para um aplicativo móvel pode ser lido. Variáveis do front-end (como as que começam com VITE_ ou NEXT_PUBLIC_) são públicas por definição. Chamadas que exigem chave secreta devem passar pelo seu back-end.
• Use chaves com o menor privilégio possível: uma chave que só lê, só para um serviço, com restrição de domínio ou IP quando a plataforma permitir.
• Rotacione periodicamente os segredos mais críticos.
• Ative a varredura de segredos do GitHub (secret scanning e push protection), que bloqueia commits com chaves conhecidas.

Vazou uma chave no GitHub. E agora?

1. Revogue ou troque a chave imediatamente no serviço correspondente. Esta é a única ação que realmente resolve.
2. Verifique os logs de uso do serviço para identificar acessos indevidos.
3. Remova o segredo do histórico, se o repositório for público, com ferramentas próprias para reescrever o histórico. Mas lembre-se: depois de publicado, considere a chave comprometida, mesmo que o commit seja apagado.
4. Descubra como aconteceu e corrija o processo: .gitignore, revisão antes do commit, proteção de push.

Apagar o arquivo em um novo commit não resolve, porque a chave continua no histórico.

Checklist rápido

• .env no .gitignore e .env.example versionado.
• Nenhum segredo no código, no Dockerfile ou no front-end.
• Segredos de produção apenas na plataforma de hospedagem ou no gerenciador de segredos.
• Logs sem senhas e tokens.
• Varredura de segredos ativada no repositório.

Esses cuidados fazem parte da higiene cibernética de qualquer projeto, por menor que seja.

Perguntas frequentes