# Variáveis no painel

Pelo painel você define as variáveis de ambiente do seu app sem usar a API. Há três lugares, conforme o alcance: o **serviço**, o **projeto** e o **time**. As mudanças valem no próximo deploy; o painel oferece um botão **Redeploy** para aplicar na hora.

## Onde ficam

| Alcance | Onde abrir | Quem altera |
|---|---|---|
| Serviço | Tela do site, seção "Variáveis de <serviço>". Valem só para este serviço. | Membro ou acima |
| Compartilhadas do grupo | Mesma tela, seção "Compartilhadas do grupo". Valem para todos os serviços do projeto. | Membro ou acima |
| Projeto | Aba de variáveis do projeto. | Membro ou acima |
| Time | Menu **Variáveis compartilhadas**. Valem para todos os projetos que você ligar a elas. | Administrador ou acima |

Leitores veem só os nomes; o valor aparece como "Valor oculto para o seu papel".

## Criar ou editar uma variável do serviço

1. Abra o projeto, entre no site e vá à seção "Variáveis de <serviço>".
2. Clique em **Nova variável**.
3. Preencha **Nome** e **Valor**.
4. Ligue **Sensível** se for um segredo: fica mascarada na tela e nos logs e não pode ser lida de volta ([Segredos](/conectados/segredos/)).
5. Salve. O painel avisa "Variável X salva. Vale no próximo deploy." e marca com **Precisa de redeploy** os serviços afetados.

Na tabela, cada linha tem **Editar** e **Apagar**, e as marcas **Sensível**, **Referência** e **Precisa de redeploy**. Ao apagar, o painel lembra que quem a referencia passará a falhar com `unresolved_reference`.

## Referências com ${{...}}

No campo **Valor**, digite `${{` e o painel sugere o que dá para referenciar (campo com sugestão automática). Use:

- `${{api.PRIVATE_URL}}`: variável de outro serviço do projeto.
- `${{shared.REGION}}`: variável compartilhada.

Se a referência apontar para algo que não existe, o painel avisa "Referência sem destino: X. O deploy falharia com unresolved_reference." Regras e variáveis automáticas em [Variáveis e referências](/conectados/variaveis-e-referencias/).

## Variáveis do projeto e do time

A tela de variáveis do projeto e a de **Variáveis compartilhadas** do time usam o mesmo editor:

- **Buscar pelo nome…** e o filtro **Todos os ambientes** (**Production**, **Preview**, **Development**).
- **Adicionar variável**: **Nome** (não muda depois), **Valor** (várias linhas, até 64 KiB), **Ambientes** (escolha ao menos um), **Sensível** e **Comentário (opcional)**.
- A coluna de origem mostra **Time** (gerenciada na página do time) ou **Projeto**.
- No time, **Projetos de <chave>** liga a variável a projetos. Eles a herdam no próximo deploy, e uma variável do projeto com o mesmo nome e ambiente vence a do time.

Nomes aceitam letras, números e `_`, sem começar por número. Reservados: `PORT`, `HOST`, `HOSTNAME`, `NODE_ENV`, `CI`, `HOME`, `PATH` e nomes começando por `NEBULAR_`. O painel sugere outro nome, como `APP_PORT`. Se chegar ao limite de variáveis, apague alguma para adicionar outra.

## Importar um .env em lote

1. Clique em **Importar .env**.
2. Cole o conteúdo ou escolha o arquivo (até 1 MB).
3. Confira a pré-visualização: cada chave aparece como ok, sobrescreve, ignorada, repetida (vale a última) ou valor grande demais.
4. Escolha os ambientes. Se quiser, marque **Marcar todas como sensíveis** e **Sobrescrever existentes**.
5. Clique em **Importar N variáveis**. O resultado diz quantas foram criadas, atualizadas e ignoradas.

## Aplicar com redeploy

Depois de mudar variáveis, aparece o aviso "Alterações valem no próximo deploy." com o botão **Redeploy**. Clique para refazer o deploy atual com os novos valores ("Redeploy iniciado com as novas variáveis."). Sem deploy ativo, publique uma versão para aplicá-las. Apagar uma variável também só tem efeito no próximo deploy.

## Prefixos públicos

Variáveis que começam com `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_` ou `EXPO_PUBLIC_` entram no código enviado ao navegador, e o valor fica visível a qualquer visitante. O painel avisa: não coloque segredos nelas.

## Histórico

Cada mudança de configuração do serviço, incluindo variáveis, gera uma versão em **Histórico de configuração**. Os valores sensíveis aparecem mascarados, e **Restaurar esta versão** reaplica a configuração. Veja [Histórico de configuração](/operacao/historico-de-configuracao/).

## Se algo der errado

| Sintoma | O que fazer |
|---|---|
| "Esse nome é reservado pelo Nebular." | Escolha outro nome, por exemplo `APP_PORT`. |
| "Já existe X em Production..." | Edite a variável existente ou desmarque esse ambiente. |
| "Informe o valor (valores sensíveis precisam ser digitados de novo)." | Ao editar uma variável sensível, digite o valor novamente. |
| O app não viu o valor novo | Faça o **Redeploy**. |
| Deploy falha com `unresolved_reference` | Crie o serviço ou a variável citada, ou corrija o nome. |

## Próximos passos

- [Segredos](/conectados/segredos/)
- [Variáveis e referências](/conectados/variaveis-e-referencias/)
- [Papéis e permissões](/times/papeis-e-permissoes/)
