Como manter segredos fora do seu código

Segredo é qualquer valor que dá acesso: o token de um bot, a senha do banco, a chave da API de pagamento, uma chave de assinatura. No momento em que um deles entra num commit do Git, você perde o controle sobre ele. Ele é copiado para todo clone, aparece nos diffs e, se o push for público, robôs podem capturá-lo em pouco tempo.

A solução é mais um hábito do que uma ferramenta: o código pede o segredo em tempo de execução, e o segredo mora em outro lugar. Os passos abaixo vão da primeira refatoração até o que fazer quando algo vaza.

Por que um segredo escrito no código é um problema?#

O Git não esquece. Apagar uma linha num commit seguinte deixa o valor antigo no histórico, e o histórico é copiado para todo clone e fork. Repositório privado também não é lugar seguro: mais gente ganha acesso de leitura com o tempo, sistemas de CI imprimem logs e repositórios viram públicos por acidente.

Escrever o segredo no código também amarra código e ambiente. O mesmo arquivo não roda com uma chave de teste no seu computador e uma chave real em produção sem editar o código.

Como tirar um segredo do código?#

Leia o valor de uma variável de ambiente. Antes:

const token = "MTIzNDU2Nzg5MA.fake.token"; // escrito no código: nunca faça isso

Depois, em Node.js, com uma checagem que falha logo se o valor não existir:

// index.js
const token = process.env.DISCORD_TOKEN;
if (!token) {
  throw new Error("DISCORD_TOKEN is not set");
}

O mesmo em Python:

import os

token = os.environ["DISCORD_TOKEN"]  # lança KeyError se não existir

No desenvolvimento local, coloque os valores num arquivo .env e carregue-o. O Node.js faz isso nativamente com uma flag (--env-file, disponível desde a v20.6.0 e não mais experimental na v22.21 e na v24.10):

node --env-file=.env index.js

Se o arquivo pode não existir, use --env-file-if-exists=.env (desde a v22.9.0). Sem isso, o Node.js dá erro quando o arquivo falta. Uma variável já definida no ambiente real tem prioridade sobre o arquivo. Veja o arquivo .env para a sintaxe e o carregamento em Python, e variáveis de ambiente para o conceito.

Como impedir que segredos cheguem ao Git?#

Use três camadas, porque cada uma pega o que as outras deixam passar.

1. Ignore o arquivo. Adicione isto ao .gitignore antes de criar o primeiro .env:

.env
.env.*
!.env.example

Depois commite um .env.example com os nomes das variáveis e valores falsos, para quem trabalha com você saber o que definir:

DISCORD_TOKEN=replace_me
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

O .gitignore só vale para arquivos que o Git ainda não rastreia. Se o .env já foi commitado, rode git rm --cached .env antes.

2. Escaneie antes de commitar. O Gitleaks é um scanner open source. Para usá-lo como hook de pre-commit, adicione isto ao .pre-commit-config.yaml (troque o rev pela versão atual, que aparece na página de releases do projeto, ou rode pre-commit autoupdate) e depois rode pre-commit install:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks

Para escanear uma vez o histórico inteiro de um repositório que já existe:

gitleaks git -v .

Os comandos antigos detect e protect foram descontinuados na v8.19.0 em favor de git, dir e stdin.

3. Bloqueie no servidor. O push protection do GitHub recusa pushes que contêm padrões de segredo reconhecidos. Para usuários, ele vem ligado por padrão em repositórios públicos no GitHub.com. Ativá-lo num repositório cabe a um administrador do repositório ou dono da organização e exige o GitHub Secret Protection. É uma rede de segurança, não substitui as duas primeiras camadas, porque só reconhece os padrões suportados e os personalizados.

Onde os segredos devem ficar?#

Escolha o lugar mais simples para cada etapa:

Um cofre de segredos dedicado acrescenta controle de acesso, logs de auditoria e rotação. Vale a pena quando muitas pessoas ou serviços compartilham credenciais. Para um único bot ou API, as variáveis de ambiente da plataforma costumam bastar.

Duas regras valem em todo lugar. Dê a cada ambiente o seu próprio segredo, para que uma chave de desenvolvimento vazada não alcance a produção. E dê a cada segredo a menor permissão necessária, como um usuário de banco só de leitura para um script de relatórios.

Posso guardar segredos no código do front-end?#

Não. Tudo que é enviado ao navegador é público. O Next.js, por exemplo, embute no bundle JavaScript, durante o build, as variáveis com o prefixo NEXT_PUBLIC_, e faz isso de propósito. Outros frameworks têm prefixos parecidos. Uma chave secreta de pagamento ou a URL de um banco numa variável de front-end fica publicada para todo visitante.

Mantenha os segredos de verdade num servidor e faça o navegador chamar um endpoint seu. Identificadores públicos, como uma chave publicável feita para o cliente, podem ficar no front-end sem problema.

O que fazer se um segredo já foi commitado?#

A ordem importa. Revogue primeiro, limpe depois.

1. Revogue ou troque o segredo agora. Gere um token ou senha novos no provedor e atualize o seu deploy. A própria orientação do GitHub coloca isso em primeiro lugar: depois que o valor antigo é revogado, ele não pode mais ser usado, o que pode resolver o problema sozinho.
2. Procure uso indevido. Olhe os logs de auditoria ou de uso do provedor em busca de atividade que você não reconhece.
3. Tire do histórico, se quiser. Use o git filter-repo para reescrever o histórico e faça um force-push. Peça a quem colabora que clone de novo, senão alguém pode subir os dados antigos outra vez.
4. Aceite os limites. Reescrever não limpa outros clones, forks nem visualizações em cache de commits antigos. Por isso o passo 1 é a correção de verdade.

Para os passos exatos depois de um vazamento no GitHub, leia o que fazer quando uma chave de API vaza no GitHub. Uma lista mais ampla de verificações está no checklist de segurança para deploy.

Como conferir que deu certo?#

• git ls-files | grep -i "\.env" lista os arquivos env rastreados. Só o .env.example deve aparecer.
• git log -p -S"prefixo-do-segredo" procura no histórico um valor que preocupa você. Use um prefixo, não o segredo inteiro.
• Rode gitleaks git -v . e confirme que ele não aponta vazamentos.
• Inicie a aplicação sem a variável definida. Ela deve falhar com o seu erro claro, e não rodar com um valor padrão.

Como fazer isso na Square Cloud#

Na Square Cloud, você define as variáveis de ambiente por aplicação: no painel, pela API, na CLI ou na extensão do VS Code. O painel importa um arquivo .env e exporta as variáveis de volta como KEY=VALUE, então fica fácil manter o arquivo local e a produção sincronizados.

A mudança vale no próximo restart, sem rebuild. O seu código lê os valores do jeito de sempre, por process.env ou os.environ, então nada no código precisa saber onde eles estão guardados. Cada aplicação também recebe a própria variável SQUARECLOUD_APP_ID em tempo de execução.

Como as variáveis são por aplicação, você pode dar a cada app os seus próprios tokens e deixar o .env fora do ZIP ou do repositório que você envia. Saiba mais na página de variáveis de ambiente.