Adicionar & usar grupos de variáveis

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

Os grupos de variáveis armazenam valores e segredos que você pode querer que sejam passados para um pipeline YAML ou disponibilizados em vários pipelines. Você pode compartilhar e usar grupos de variáveis em vários pipelines no mesmo projeto.

As variáveis secretas nos grupos Variáveis são recursos protegidos. Você pode adicionar combinações de aprovações, verificações e permissões de pipeline para limitar o acesso a variáveis secretas em um grupo de variáveis. O acesso a variáveis não secretas não é limitado por aprovações, verificações e permissões de pipeline.

Criar um grupo de variáveis

Não é possível criar grupos de variáveis no YAML, mas eles podem ser usados conforme descrito em Usar um grupo de variáveis.

Usar um grupo de variáveis

Para usar uma variável de um grupo de variáveis, adicione uma referência ao grupo no arquivo YAML:

variables:
- group: my-variable-group

Em seguida, as variáveis do grupo de variáveis podem ser usadas em seu arquivo YAML.

Se você usar variáveis e grupos de variáveis, use a name/value sintaxe para as variáveis individuais não agrupadas:

variables:
- group: my-variable-group
- name: my-bare-variable
  value: 'value of my-bare-variable'

Para fazer referência a um grupo de variáveis, use a sintaxe de macro ou uma expressão de tempo de execução. No exemplo a seguir, o grupo my-variable-group tem uma variável chamada myhello.

variables:
- group: my-variable-group
- name: my-passed-variable
  value: $[variables.myhello] # uses runtime expression

steps:
- script: echo $(myhello) # uses macro syntax
- script: echo $(my-passed-variable)

Você pode fazer referência a vários grupos de variáveis no mesmo pipeline. Se vários grupos de variáveis incluírem a mesma variável, o grupo de variáveis incluído por último no arquivo YAML definirá o valor da variável.

variables:
- group: my-first-variable-group
- group: my-second-variable-group

Você também pode fazer referência a um grupo de variáveis em um modelo. No modelo variables.yml, o grupo my-variable-group é referenciado. O grupo de variáveis inclui uma variável chamada myhello.

# variables.yml
variables:
- group: my-variable-group

Neste pipeline, a variável $(myhello) do grupo my-variable-group de variáveis é incluída e variables.yml referenciada.

# azure-pipeline.yml
stages:
- stage: MyStage
  variables:
  - template: variables.yml
  jobs:
  - job: Test
    steps:
    - script: echo $(myhello)

Autorizar um grupo de variáveis

Para trabalhar com um grupo variável, você deve autorizar o grupo. Se você nomear apenas o grupo de variáveis no YAML, qualquer pessoa que possa enviar código para seu repositório poderá extrair o conteúdo dos segredos no grupo de variáveis. Para autorizar o grupo, use uma das seguintes técnicas:

  • Para autorizar qualquer pipeline a usar o grupo de variáveis, vá para Azure Pipelines. Esta pode ser uma boa opção se você não tiver segredos no grupo. Selecione Grupos de variáveis da biblioteca>e, em seguida, selecione o grupo de variáveis em questão e habilite a configuração Permitir acesso a todos os pipelines.

  • Para autorizar um grupo de variáveis para um pipeline específico, abra o pipeline, selecione Editar e enfileire uma compilação manualmente. Você vê um erro de autorização de recursos e uma ação "Autorizar recursos" no erro. Escolha esta ação para adicionar explicitamente o pipeline como um usuário autorizado do grupo de variáveis.

Nota

Se você adicionar um grupo de variáveis a um pipeline e não receber um erro de autorização de recurso em sua compilação quando esperava, desative a configuração Permitir acesso a todos os pipelines .

Acesse os valores das variáveis em um grupo de variáveis vinculadas da mesma forma que as variáveis definidas dentro do próprio pipeline. Por exemplo, para acessar o valor de uma variável chamada cliente em um grupo de variáveis vinculado ao pipeline, use $(customer) um parâmetro de tarefa ou um script. Mas, você não pode acessar variáveis secretas (variáveis criptografadas e variáveis do cofre de chaves) diretamente em scripts - em vez disso, elas devem ser passadas como argumentos para uma tarefa. Para obter mais informações, consulte segredos

As alterações feitas em um grupo de variáveis ficam automaticamente disponíveis para todas as definições ou estágios aos quais o grupo de variáveis fica vinculado.

Listar grupos de variáveis

Use a CLI para listar os grupos de variáveis para execuções de pipeline com o comando az pipelines variable-group list. Se a extensão do Azure DevOps para CLI for nova para você, consulte Introdução à CLI do Azure DevOps.

az pipelines variable-group list [--action {manage, none, use}]
                                 [--continuation-token]
                                 [--group-name]
                                 [--org]
                                 [--project]
                                 [--query-order {Asc, Desc}]
                                 [--top]

Parâmetros opcionais

  • action: Especifica a ação que pode ser executada nos grupos de variáveis. Os valores aceitos são manage, none e use.
  • continuation-token: Lista os grupos de variáveis depois que um token de continuação é fornecido.
  • group-name: Nome do grupo de variáveis. Curingas são aceitos, como new-var*.
  • org: URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URLo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo . Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • projeto: Nome ou ID do projeto. Configure o projeto padrão usando az devops configure -d project=NAME_OR_IDo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo .
  • query-order: lista os resultados em ordem crescente ou decrescente (o padrão). Os valores aceitos são Asc e Desc.
  • top: Número de grupos de variáveis a serem listados.

Exemplo

O comando a seguir lista os três principais grupos de variáveis em ordem crescente e retorna os resultados em formato de tabela.

az pipelines variable-group list --top 3 --query-order Asc --output table

ID    Name               Type    Number of Variables
----  -----------------  ------  ---------------------
1     myvariables        Vsts    2
2     newvariables       Vsts    4
3     new-app-variables  Vsts    3

Mostrar detalhes para um grupo de variáveis

Exiba os detalhes de um grupo de variáveis em seu projeto com o comando az pipelines variable-group show . Se a extensão do Azure DevOps para CLI for nova para você, consulte Introdução à CLI do Azure DevOps.

az pipelines variable-group show --group-id
                                 [--org]
                                 [--project]

Parâmetros

  • group-id: Obrigatório. ID do grupo de variáveis. Para localizar o ID do grupo de variáveis, consulte Listar grupos de variáveis.
  • org: URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URLo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo . Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • projeto: Nome ou ID do projeto. Configure o projeto padrão usando az devops configure -d project=NAME_OR_IDo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo .

Exemplo

O comando a seguir mostra detalhes para o grupo de variáveis com o ID 4 e retorna os resultados no formato YAML.

az pipelines variable-group show --group-id 4 --output yaml

authorized: false
description: Variables for my new app
id: 4
name: MyNewAppVariables
providerData: null
type: Vsts
variables:
  app-location:
    isSecret: null
    value: Head_Office
  app-name:
    isSecret: null
    value: Fabrikam

Excluir um grupo de variáveis

Exclua um grupo de variáveis em seu projeto com o comando az pipelines variable-group delete . Se a extensão do Azure DevOps para CLI for nova para você, consulte Introdução à CLI do Azure DevOps.

az pipelines variable-group delete --group-id
                                   [--org]
                                   [--project]
                                   [--yes]

Parâmetros

  • group-id: Obrigatório. ID do grupo de variáveis. Para localizar o ID do grupo de variáveis, consulte Listar grupos de variáveis.
  • org: URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URLo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo . Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • projeto: Nome ou ID do projeto. Configure o projeto padrão usando az devops configure -d project=NAME_OR_IDo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo .
  • Sim: Opcional. Não solicita confirmação.

Exemplo

O comando a seguir exclui o grupo de variáveis com o ID 1 e não solicita confirmação.

az pipelines variable-group delete --group-id 1 --yes

Deleted variable group successfully.

Adicionar variáveis a um grupo de variáveis

Com a CLI do Azure DevOps, você pode adicionar uma variável a um grupo de variáveis em um pipeline com o comando az pipelines variable-group variable group . Se a extensão do Azure DevOps para CLI for nova para você, consulte Introdução à CLI do Azure DevOps.

az pipelines variable-group variable create --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--secret {false, true}]
                                            [--value]

Parâmetros

  • group-id: Obrigatório. ID do grupo de variáveis. Para localizar o ID do grupo de variáveis, consulte Listar grupos de variáveis.
  • nome: Obrigatório. Nome da variável que você está adicionando.
  • org: URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URLo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo . Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • projeto: Nome ou ID do projeto. Configure o projeto padrão usando az devops configure -d project=NAME_OR_IDo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo .
  • secret: Opcional. Indica se o valor da variável é um segredo. Os valores aceites são falsos e verdadeiros.
  • value: Necessário para variável não secreta. Valor da variável. Para variáveis secretas, se o parâmetro value não for fornecido, ele será escolhido da variável de ambiente prefixada com AZURE_DEVOPS_EXT_PIPELINE_VAR_ ou o usuário será solicitado a inseri-lo por meio de entrada padrão. Por exemplo, uma variável chamada MySecret pode ser inserida usando a variável AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecretde ambiente .

Exemplo

O comando a seguir cria uma variável no grupo de variáveis com ID de 4. A nova variável é chamada requires-login e tem um valor True, e o resultado é mostrado em formato de tabela.

az pipelines variable-group variable create --group-id 4 --name requires-login --value True --output table

Name            Is Secret    Value
--------------  -----------  -------
requires-login  False        True

Listar variáveis em um grupo de variáveis

Você pode listar as variáveis em um grupo de variáveis com o comando az pipelines variable-group variable list list . Se a extensão do Azure DevOps para CLI for nova para você, consulte Introdução à CLI do Azure DevOps.

az pipelines variable-group variable list --group-id
                                          [--org]
                                          [--project]

Parâmetros

  • group-id: Obrigatório. ID do grupo de variáveis. Para localizar o ID do grupo de variáveis, consulte Listar grupos de variáveis.
  • org: URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URLo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo . Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • projeto: Nome ou ID do projeto. Configure o projeto padrão usando az devops configure -d project=NAME_OR_IDo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo .

Exemplo

O comando a seguir lista todas as variáveis no grupo de variáveis com ID de 4 e mostra o resultado em formato de tabela.

az pipelines variable-group variable list --group-id 4 --output table

Name            Is Secret    Value
--------------  -----------  -----------
app-location    False        Head_Office
app-name        False        Fabrikam
requires-login  False        True

Atualizar variáveis em um grupo de variáveis

Atualize uma variável em um grupo de variáveis com o comando az pipelines variable-group variable update . Se a extensão do Azure DevOps para CLI for nova para você, consulte Introdução à CLI do Azure DevOps.

az pipelines variable-group variable update --group-id
                                            --name
                                            [--new-name]
                                            [--org]
                                            [--project]
                                            [--prompt-value {false, true}]
                                            [--secret {false, true}]
                                            [--value]

Parâmetros

  • group-id: Obrigatório. ID do grupo de variáveis. Para localizar o ID do grupo de variáveis, consulte Listar grupos de variáveis.
  • nome: Obrigatório. Nome da variável que você está adicionando.
  • novo nome: Opcional. Especifique para alterar o nome da variável.
  • org: URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URLo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo . Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • projeto: Nome ou ID do projeto. Configure o projeto padrão usando az devops configure -d project=NAME_OR_IDo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo .
  • prompt-value: defina como true para atualizar o valor de uma variável secreta usando a variável de ambiente ou prompt via entrada padrão. Os valores aceites são falsos e verdadeiros.
  • secret: Opcional. Indica se o valor da variável é mantido em segredo. Os valores aceites são falsos e verdadeiros.
  • value: Atualiza o valor da variável. Para variáveis secretas, use o parâmetro prompt-value para ser solicitado a inseri-lo por meio de entrada padrão. Para consoles não interativos, ele pode ser escolhido a partir da variável de ambiente prefixada com AZURE_DEVOPS_EXT_PIPELINE_VAR_. Por exemplo, uma variável chamada MySecret pode ser inserida usando a variável AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecretde ambiente .

Exemplo

O comando a seguir atualiza a variável requires-login com o novo valor False no grupo de variáveis com ID de 4. Ele especifica que a variável é um segredo e mostra o resultado no formato YAML. Observe que a saída mostra o valor como null em vez de False já que é um valor oculto secreto.

az pipelines variable-group variable update --group-id 4 --name requires-login --value False --secret true --output yaml

requires-login:
  isSecret: true
  value: null

Excluir variáveis de um grupo de variáveis

Exclua uma variável de um grupo de variáveis com o comando az pipelines variable-group variable delete . Se a extensão do Azure DevOps para CLI for nova para você, consulte Introdução à CLI do Azure DevOps.

az pipelines variable-group variable delete --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--yes]

Parâmetros

  • group-id: Obrigatório. ID do grupo de variáveis. Para localizar o ID do grupo de variáveis, consulte Listar grupos de variáveis.
  • nome: Obrigatório. Nome da variável que você está excluindo.
  • org: URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URLo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo . Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • projeto: Nome ou ID do projeto. Configure o projeto padrão usando az devops configure -d project=NAME_OR_IDo . Obrigatório se não estiver configurado como padrão ou coletado usando git configo .
  • Sim: Opcional. Não solicita confirmação.

Exemplo

O comando a seguir exclui a variável requires-login do grupo de variáveis com ID de 4 e solicita confirmação.

az pipelines variable-group variable delete --group-id 4 --name requires-login

Are you sure you want to delete this variable? (y/n): y
Deleted variable 'requires-login' successfully.

Nota

Não há suporte para Cofres de Chaves usando o controle de acesso baseado em função do Azure (Azure RBAC).

Vincule um cofre de chaves do Azure existente a um grupo de variáveis e mapeie segredos de cofre seletivo para o grupo de variáveis.

  1. Na página Grupos de variáveis, habilite Segredos de link de um cofre de chaves do Azure como variáveis. Você precisará de um cofre de chaves existente contendo seus segredos. Crie um cofre de chaves usando o portal do Azure.

    Captura de ecrã do grupo variável com a integração do cofre de chaves do Azure.

  2. Especifique seu ponto final de assinatura do Azure e o nome do cofre que contém seus segredos.

    Verifique se a conexão de serviço do Azure tem pelo menos permissões de gerenciamento Obter e Listar no cofre para segredos. Habilite o Azure Pipelines para definir essas permissões escolhendo Autorizar ao lado do nome do cofre. Ou defina as permissões manualmente no portal do Azure:

    1. Abra Configurações do cofre e escolha Políticas de acesso>Adicionar novo.
    2. Selecione Selecionar entidade de segurança e, em seguida, escolha a entidade de serviço para a sua conta de cliente.
    3. Selecione Permissões secretas e verifique se Obtere Listar têm marcas de seleção.
    4. Selecione OK para salvar as alterações.

  3. Na página Grupos de variáveis, selecione + Adicionar para selecionar segredos específicos do seu cofre para mapeamento para esse grupo de variáveis.

Gerenciar segredos do cofre de chaves

Veja a seguinte lista de dicas úteis para gerenciar segredos.

  • Apenas os nomes secretos são mapeados para o grupo de variáveis, não os valores secretos. O valor secreto mais recente, obtido no cofre, é usado na execução de pipeline vinculada ao grupo de variáveis.

  • Qualquer alteração feita em segredos existentes no cofre de chaves fica automaticamente disponível para todos os pipelines em que o grupo de variáveis é usado.

  • Quando novos segredos são adicionados ou excluídos do cofre, os grupos de variáveis associados não são atualizados automaticamente. Os segredos incluídos no grupo de variáveis devem ser explicitamente atualizados para que os pipelines que estão usando o grupo de variáveis sejam executados corretamente.

  • O Azure Key Vault dá suporte ao armazenamento e gerenciamento de chaves criptográficas e segredos no Azure. Atualmente, a integração de grupos variáveis do Azure Pipelines dá suporte ao mapeamento apenas de segredos do cofre de chaves do Azure. Não há suporte para chaves criptográficas e certificados.

Expandir variáveis em um grupo

Quando você define uma variável em um grupo e a usa em um arquivo YAML, ela é igual a outras variáveis definidas no arquivo YAML. Para obter mais informações sobre a precedência de variáveis, consulte Variáveis.