A resposta curta

Os segredos ficam fora do repositório. Na Unbroker cada variável tem escopo All, Production ou Preview. Um preview novo copia All e Preview, e nunca copia um valor que é só de Production.

NEXT_PUBLIC_* e VITE_* são públicas no bundle do cliente mesmo quando você as carrega a partir de Variables. A revisão que está no ar só pega uma mudança de runtime depois de um novo deploy.

O que fica no repositório e o que fica na plataforma

Uma flag que pode ser publicada pode viver no código. Senha de banco, API key e segredo de assinatura de sessão ficam na view Variables do serviço. Não faça commit delas.

A referência de deployments diz para nunca commitar segredos de produção, guardá-los na configuração do serviço e rotacioná-los se forem expostos. O guia inclui prints e prompts de agente nessa lista.

ValorOnde fica
Feature flag públicaO repositório, quando publicá-la é aceitável
Origem de API que o navegador vêConfiguração pública do frontend
Senha ou connection string do bancoVariável de runtime do backend
Segredo de assinatura da sessãoVariável de runtime do backend
Chave pública do BeaconPode entrar na configuração do frontend
Segredo JWT do BeaconSó no backend

O corte é o mesmo para um app que começou no Lovable, no Bolt ou no Cursor. O que uma página pública ainda não prova está em um app feito com IA em produção. Um frontend e uma API no mesmo projeto ainda recebem variáveis diferentes: a origem pública no frontend, a URL do banco na API. O desenho é frontend e API.

Escopos: All, Production e Preview

All, Production e Preview são os três escopos. Esses nomes ficam em inglês na interface.

All cobre produção e os ambientes de preview. Variáveis que já existiam continuam em All até você mudá-las. Production cobre produção. A referência descreve essa escolha como apenas o projeto de produção. Preview cobre ambientes que não são de produção, inclusive previews de pull request e ambientes nomeados, como staging.

A mesma chave pode ter um valor diferente em cada escopo. Dentro de um serviço ou de um projeto, o valor do ambiente substitui All. Uma referência à variável de outro serviço resolve no ambiente do deployment.

Coloque a origem da API de produção em Production e a de staging em Preview. Não deixe uma credencial do banco de produção em All, a menos que todo preview novo deva recebê-la. Essa é a diferença entre variáveis de Production e de Preview.

Colar um arquivo .env importa cada variável no escopo que você selecionou. Editar ou apagar uma variável afeta só essa variante. Para mudar o escopo e manter o segredo guardado, deixe o valor novo em branco.

A nota de 6 de outubro é variáveis de ambiente para produção e previews.

Variáveis do serviço e variáveis compartilhadas do projeto

Uma variável de serviço pertence a uma aplicação. Uma variável compartilhada do projeto, shared project variable na documentação, é um ajuste que vários serviços do projeto precisam igual. Se a chave coincide, a do serviço substitui a compartilhada.

Use a compartilhada quando o valor realmente é comum. Use a do serviço quando um serviço precisa de outro banco ou de outra chave.

Variáveis compartilhadas do projeto exigem Pro. O Free não as inclui. Previews de pull request também exigem Pro. O Pro custa $25 por mês com $25 de crédito de uso. O crédito recomeça a cada ciclo de cobrança e não acumula. Se o uso elegível ficar abaixo do crédito, a cobrança do mês continua $25. As linhas estão em preços e em Plans. O que o Free deixa de fora está em hospedagem de backend grátis.

Variáveis públicas de build e segredos de runtime

NEXT_PUBLIC_* e VITE_* são variáveis públicas de build. No Next.js, as env vars públicas usam o prefixo NEXT_PUBLIC_. A Unbroker escolhe esses prefixos para o ambiente de destino antes do build. Um valor que acaba no bundle de JavaScript é público mesmo se você o digitou em Variables. Quando esse valor público é a origem da API que o navegador deve chamar, a ordem do build, o CORS e os cookies estão em deploy de um frontend e uma API separados.

O restante fica só em runtime, com uma exceção documentada: credenciais de registro de pacotes. Num build JavaScript gerado ou num Dockerfile próprio, defina NODE_AUTH_TOKEN ou GITHUB_TOKEN no serviço ou como variável compartilhada do projeto. A Unbroker prefere um NODE_AUTH_TOKEN não vazio e, se não houver, usa GITHUB_TOKEN. A credencial escolhida é montada como segredo do BuildKit e exposta com os dois nomes durante a instalação das dependências. Ela não entra como argumento de build e não fica gravada numa variável de ambiente da imagem. NODE_AUTH_TOKEN sai do ambiente de runtime. GITHUB_TOKEN pode continuar em runtime se o app também chama a API do GitHub. Para o GitHub Packages, use um personal access token seu com read:packages. Um Dockerfile recebe uma variável só quando pede --mount=type=secret. Declarar ARG não entrega o valor. A referência é variáveis de ambiente.

Um servidor Next.js começa em deploy de Next.js. O que muda entre next dev e esse servidor, inclusive as NEXT_PUBLIC_ no build, está em Next.js em produção. Mudar uma origem pública é outro passo que anexar um hostname. O DNS e o certificado estão em domínio personalizado e HTTPS.

O que os previews novos copiam e o que nunca copiam

Um preview novo copia All e Preview. Nunca copia uma variável que é só de Production.

Cada preview é uma cópia independente. Mudar a variável pai não reescreve um preview que já existe. Marcar a variável como Production não revoga um segredo que esse preview já guardou. Remova nele, ou recrie o preview, e rotacione a credencial se ela pode ter sido exposta. Mudar o rótulo não é revogação.

Previews automáticos de pull request rodam só branches do repositório conectado. Um fork externo não abre um preview automático, porque esse código poderia ler os segredos do preview. Os previews herdam a proteção de acesso do serviço de origem e a configuração Wait for CI. Fechar ou fazer merge do pull request remove o preview. Atividade renova um vencimento de sete dias. Como deixar o banco fora da produção está em ambientes de preview de pull request.

Aplicar, conferir, rotacionar

Abra o serviço, escolha o escopo e digite o valor no Cloud. Faça um novo deploy para a revisão em execução usar a configuração nova de runtime. Se o valor é compilado nos assets do frontend, essa mudança pede um build novo.

Com deploys automáticos ligados, um push no branch configurado enfileira um deployment. Esse deployment é o que aplica a variável. O branch, os watch paths e a espera dos checks do GitHub estão em deploy no git push.

Confira com um request da aplicação. Não imprima o segredo. Para uma URL de banco, rode uma consulta limitada. Para uma origem de API, olhe o destino do request no navegador. Não despeje o ambiente inteiro nos logs.

Se o provedor permite duas credenciais ao mesmo tempo, crie a substituta, atualize a variável, faça um novo deploy e confira antes de revogar o valor antigo. Se a sobreposição for impossível, use a janela de manutenção que esse provedor exige. Confira workers e outros consumidores, não só o serviço web. Serviços worker exigem Pro.

Agentes e prompts

Passe ao agente os nomes das chaves e os escopos. Os valores secretos entram no Cloud. Não vão no prompt, no repositório nem num print.

A inspeção de serviços via MCP não devolve credenciais nem valores de variáveis de ambiente. get_service lê um serviço sem eles. Como limitar o token está em deixar um agente fazer deploy com segurança. Um app feito no Cursor usa o mesmo corte. A lista está em deploy com Cursor.

Como isso funciona na Unbroker

Segredos no deploy, na Unbroker, ficam na view Variables. Você escolhe a chave, o valor e o escopo. Variáveis compartilhadas do projeto e previews de pull request exigem Pro. Um fork externo não abre um preview automático.

Checklist

  1. Deixe segredos de produção fora do repositório, de prints e de prompts do agente.
  2. Coloque um connection string em Variables. Deixe uma flag pública no código só quando publicá-la é aceitável.
  3. Dê escopo Production a uma credencial de produção. Não a deixe em All.
  4. Aponte Preview para um banco ou uma API key que você pode descartar.
  5. Deixe uma variável de serviço substituir a compartilhada do projeto quando um serviço precisa de outro valor.
  6. Trate NEXT_PUBLIC_* e VITE_* como públicas. Elas são escolhidas antes do build.
  7. Faça um novo deploy depois de uma mudança de runtime. Reconstrua quando o valor é compilado nos assets do frontend.
  8. Depois de restringir um escopo, edite ou recrie os previews que já copiaram o valor antigo.
  9. Rotacione uma senha vazada com sobreposição quando o provedor permitir, e depois confira workers e outros consumidores.
  10. Passe a um agente nomes e escopos. Digite os valores secretos no Cloud.

Perguntas frequentes

Onde guardar as API keys de um app em deploy?

Na view Variables do serviço, no Cloud, não no repositório e não num .env commitado. Uma key de produção fica em Production. Dê ao Preview uma key de teste, e deixe um valor em All só quando todo preview novo precisa recebê-lo. Os passos estão no guia de variáveis de ambiente.

Qual é a diferença entre as variáveis All, Production e Preview?

All vale para produção e para os ambientes de preview. Production vale para produção. A referência descreve essa escolha como apenas o projeto de produção. Preview vale para ambientes que não são de produção, inclusive previews de pull request e ambientes nomeados, como staging. Para a mesma chave, o valor do ambiente substitui All dentro daquele serviço ou projeto.

Os previews de pull request recebem segredos de produção?

Um preview novo copia All e Preview, e não recebe valores que são só de Production. Um segredo de produção que ficou em All é copiado. Um preview que já existe fica com a cópia que tem, e marcar a variável como Production não remove essa cópia. Previews de pull request exigem Pro. O mapa está em ambientes de preview.

Variáveis NEXT_PUBLIC_ ou VITE_ são secretas?

Não. Esses prefixos são variáveis públicas de build. A Unbroker as escolhe para o ambiente de destino antes do build. Um valor que cai no bundle de JavaScript é público mesmo quando você o digitou em Variables.

Preciso fazer um novo deploy depois de mudar uma variável?

Sim. Faça um novo deploy do serviço para a revisão em execução usar o valor novo de runtime. Se esse valor é compilado nos assets do frontend, a mudança também pede um build novo.

O que são as variáveis compartilhadas do projeto e elas exigem Pro?

Uma variável compartilhada do projeto é um ajuste que vários serviços do projeto podem usar. Uma variável de serviço com a mesma chave a substitui. Variáveis compartilhadas do projeto exigem Pro, e o Free não as inclui. O Pro custa $25 por mês com $25 de crédito de uso. Veja preços e Plans.

Como rotacionar uma senha de banco que vazou?

Se o banco permite duas senhas ao mesmo tempo, crie a substituta, atualize a variável, faça um novo deploy e confira com uma consulta limitada antes de revogar a senha antiga. Se não houver sobreposição, use a janela de manutenção que esse provedor exige. Edite ou recrie os previews que já copiaram o valor antigo. Confira workers e outros consumidores, não só o serviço web. Não imprima a senha nos logs.

Um agente de código consegue ver meus valores secretos?

A inspeção de serviços via MCP não os devolve. A ferramenta get_service inspeciona um serviço sem credenciais nem valores de variáveis de ambiente. O agente vê um segredo que você cola no prompt, no repositório ou num print. Passe nomes e escopos, e digite os valores no Cloud. Os limites do token estão em deixar um agente fazer deploy.