Grupos de Variáveis de Ambiente Partilhadas

An environment variable group holds values that several Orbit projects need, such as a shared API key or a database credential, in one place. Link the group to the projects that need it and every…

Um grupo de variáveis de ambiente contém valores que vários projetos Orbit necessitam, como uma chave API partilhada ou uma credencial de base de dados, num único local. Associe o grupo aos projetos que o necessitam e todas as suas compilações receberão essas variáveis, portanto rodar uma chave é uma edição em vez de seis.

Onde Vivem os Grupos Env

Abra Orbit e escolha Env groups na navegação de nível superior. A página tem o título Shared env var groups e descreve-os como grupos de nível de conta partilhados em vários projetos Orbit.

Os grupos ficam acima dos projetos. As variáveis próprias de um projeto continuam a viver no seu separador Env vars: consulte Environment Variables in Orbit.

Quando Usar um Grupo

O teste é simples: o mesmo valor é colado em mais de um projeto?

Bons candidatos:

Uma chave de análise ou rastreamento de erros partilhada utilizada por cada front end.
Uma sequência de ligação de réplica de leitura utilizada por várias ferramentas internas.
Uma chave API de terceiros para um serviço com o qual toda a conta comunica.
Um token de cliente de sinalizador de funcionalidade comum.

Maus candidatos:

Qualquer coisa específica de um projeto. Pertence a esse projeto.
Qualquer coisa que difira entre produção e pré-visualização. Os grupos não são por ambiente, portanto um valor que muda por ambiente pertence às variáveis de ambiente próprias do projeto.

Criar um Grupo

Clique em New group.
Dê-lhe um Group name, até 64 caracteres. Nomeie-o segundo o que contém, por exemplo o serviço a que as credenciais pertencem.
Adicione uma Description opcional.
Clique em Create group.

Uma conta pode conter até 20 grupos. Quando atingir o limite, o botão mostra (limit reached) e criar outro é recusado.

Criar, editar e eliminar um grupo requer uma função de proprietário ou administrador na conta. Programadores e visualizadores podem ver grupos, mas não alterá-los, o que é intencional: uma edição de grupo altera vários projetos de uma vez.

Adicionar Variáveis

Abra o grupo e utilize a secção Variables:

Clique em Add variable.
Introduza a chave e o valor.
Marque Mark as secret para qualquer coisa sensível.
Clique em Save group.

Uma variável marcada como secreta é armazenada encriptada e seu valor não é devolvido ao painel depois. A lista mostra a chave e um indicador Marked as secret (hidden) em vez do valor. Os valores não secretos permanecem visíveis para que possa verificá-los rapidamente.

Marcar uma variável como secreta significa que não pode lê-la de volta a partir do painel. Esse é o objetivo, mas também significa que o grupo não é um gestor de senhas. Mantenha a cópia autoritativa onde a sua equipa já guarda credenciais e trate o grupo como o mecanismo de distribuição.

Para alterar o valor de um segredo, escreva o novo e guarde. Para remover uma variável, clique em Remove na sua linha e guarde.

Associar Projetos

A secção Linked projects lista todos os projetos na conta. Clique num projeto para associá-lo ou desassociá-lo; os projetos associados são destacados. Guarde o grupo para aplicar.

Um grupo sem projetos associados não faz nada, e a secção diz No projects yet até associar um.

As variáveis de grupo são injectadas no tempo de compilação, portanto associar um projeto afecta sua próxima compilação, não a implementação actualmente em directo. Se necessitar da alteração agora, reimplemente: consulte Deploying Your Project.

Precedência

A regra é declarada na página: as variáveis de grupo são injectadas no tempo de compilação, e as variáveis de nível de projeto e de nível de ambiente têm precedência sobre as variáveis de grupo.

Por outras palavras, o mais específico vence:

Variáveis de nível de ambiente, prioridade mais elevada.
Variáveis de nível de projeto.
Variáveis de grupo, prioridade mais baixa.

Essa ordenação é útil em vez de ser meramente uma tecnicidade. Defina a predefinição partilhada no grupo e substitua-a no único projeto que necessita de algo diferente, sem remover esse projeto do grupo. Consulte Environment Variables Per Environment para a camada de ambiente.

Também explica a confusão mais comum com grupos: edita o grupo, reimplementa e nada muda, porque o projeto tem sua própria variável com a mesma chave vencendo silenciosamente. Verifique primeiro o separador Env vars próprio do projeto quando um valor de grupo parece ser ignorado.

Rodar uma Credencial Partilhada

Este é o fluxo de trabalho para o qual os grupos existem:

Crie a nova credencial no fornecedor, deixando a antiga activa.
Edite o valor no grupo e guarde.
Reimplemente cada projeto associado ou aguarde sua próxima implementação.
Confirme que cada projeto está a funcionar com a nova credencial.
Revogue a credencial antiga no fornecedor.

Fazer o passo 5 em primeiro lugar dá-lhe uma janela em que cada projeto associado está quebrado de uma só vez, que é precisamente o risco que uma credencial partilhada concentra.

Eliminar um Grupo

Clique em eliminar no grupo. A confirmação é específica sobre a consequência: as compilações futuras perderão estas variáveis e as compilações já concluídas não são afectadas.

Eliminar também desassocia cada projeto. Isso significa que as implementações em execução continuam com os valores com que foram compiladas, e a próxima compilação de cada projeto associado vem sem eles. Se essas variáveis forem necessárias, essa compilação falhará ou a aplicação se comportará incorrectamente em tempo de execução.

Antes de eliminar, desassocie projetos um de cada vez e reimplemente cada um, para descobrir quais deles realmente dependem do grupo antes de todos perderem.

Conselhos Práticos

Mantenha os grupos pequenos e com propósito. Um grupo por serviço externo vence um grupo "partilhado" gigante, porque permite associar exactamente os projetos que necessitam de cada coisa.

Nomeie as chaves da mesma forma em todo o lado. Se um projeto lê SENTRY_DSN e outro lê SENTRY_KEY, um grupo partilhado não pode ajudá-lo. Padronize os nomes em primeiro lugar.

Não coloque credenciais de produção num grupo associado a projetos com pré-visualizações públicas. As variáveis de grupo chegam a cada compilação de um projeto associado, pré-visualizações incluídas.

Resolução de Problemas

Uma compilação não vê a variável. Confirme que o projeto está associado e guardado, e que a compilação foi executada após a associação ter sido feita. As variáveis de grupo aplicam-se a partir da próxima compilação.

O valor está errado em tempo de execução. Uma variável de nível de projeto ou de nível de ambiente com a mesma chave está a substituí-la. Verifique o separador Env vars do projeto.

Criar grupo não está disponível. Atingiu o limite de 20 grupos ou sua função de conta não é proprietário ou administrador.

O valor de um segredo é apresentado em branco. Isso está correcto. Os valores secretos não são devolvidos ao painel após guardar.

Um projeto falhou após uma edição de grupo. Reverta o valor no grupo e reimplemente, depois descubra qual projeto discordou. Rolling Back a Deployment deixa o site em execução saudável enquanto o faz.

Onde Ir a Seguir

Environment Variables in Orbit para variáveis de nível de projeto.
Environment Variables Per Environment para a camada de substituição.
Orbit Project Settings para o resto da configuração de um projecto.