Adicionar e usar grupos de variáveis

  • Artigo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Os grupos de variáveis armazenam valores e segredos que talvez você queira 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.

Variáveis secretas em grupos de 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

Você não pode 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 no arquivo YAML.

Se você usar tanto variáveis quanto grupos de variáveis, use a sintaxe name/value 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 runtime. 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

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

# 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 de variáveis, você precisa autorizar o grupo. Se você nomear apenas o grupo de variáveis no YAML, qualquer pessoa que possa enviar código por push para o 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, acesse Azure Pipelines. Essa pode ser uma boa opção se você não tiver segredos no grupo. SelecioneBiblioteca>Grupos de variáveis 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 um build manualmente. Você verá um erro de autorização de recurso 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.

Observação

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

Acesse os valores de variável em um grupo de variáveis vinculado da mesma maneira que as variáveis que você define dentro do próprio pipeline. Por exemplo, para acessar o valor de uma variável chamada customer em um grupo de variáveis vinculado ao pipeline, use $(customer) em um parâmetro de tarefa ou um script. No entanto, 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 precisam ser passadas como argumentos para uma tarefa. Para obter mais informações, confira segredos

As alterações feitas em um grupo de variáveis estão automaticamente disponíveis para todas as definições ou fases às quais o grupo de variáveis é 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 a CLI for nova para você, confira 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: o nome do grupo de variáveis. Os curingas, como new-var*, são aceitos.
  • org: a URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • project: nome ou ID do projeto. Você pode configurar o projeto padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config.
  • query-order: lista os resultados em ordem crescente ou decrescente (o padrão). Os valores aceitos são Asc e Desc.
  • top: o 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 a CLI for nova para você, confira Introdução à CLI do Azure DevOps.

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

Parâmetros

  • group-id: obrigatório. A ID do grupo de variáveis. Para localizar a ID do grupo de variáveis, confira Listar grupos de variáveis.
  • org: a URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • project: nome ou ID do projeto. Você pode configurar o projeto padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config.

Exemplo

O comando a seguir mostra detalhes do grupo de variáveis com a 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 a CLI for nova para você, confira Introdução à CLI do Azure DevOps.

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

Parâmetros

  • group-id: obrigatório. A ID do grupo de variáveis. Para localizar a ID do grupo de variáveis, confira Listar grupos de variáveis.
  • org: a URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • project: nome ou ID do projeto. Você pode configurar o projeto padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config.
  • yes: opcional. Não solicite confirmação.

Exemplo

O comando a seguir exclui o grupo de variáveis com a 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 create. Se a extensão do Azure DevOps para a CLI for nova para você, confira 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. A ID do grupo de variáveis. Para localizar a ID do grupo de variáveis, confira Listar grupos de variáveis.
  • nome: Obrigatórios. O nome da variável que você está adicionando.
  • org: a URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • project: nome ou ID do projeto. Você pode configurar o projeto padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config.
  • secret: opcional. Indica se o valor da variável é um segredo. Os valores aceitos são false e true.
  • value: necessário para variável não secreta. O 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 de ambiente AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret.

Exemplo

O comando a seguir cria uma variável no grupo de variáveis com a ID 4. A nova variável é chamada requires-login e tem um valor True, e o resultado é mostrado no 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. Se a extensão do Azure DevOps para a CLI for nova para você, confira Introdução à CLI do Azure DevOps.

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

Parâmetros

  • group-id: obrigatório. A ID do grupo de variáveis. Para localizar a ID do grupo de variáveis, confira Listar grupos de variáveis.
  • org: a URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • project: nome ou ID do projeto. Você pode configurar o projeto padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config.

Exemplo

O comando a seguir lista todas as variáveis no grupo de variáveis com a ID 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 a CLI for nova para você, confira 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. A ID do grupo de variáveis. Para localizar a ID do grupo de variáveis, confira Listar grupos de variáveis.
  • nome: Obrigatórios. O nome da variável que você está adicionando.
  • new-name opcional. Especifique para alterar o nome da variável.
  • org: a URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • project: nome ou ID do projeto. Você pode configurar o projeto padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config.
  • prompt-value: defina como true para atualizar o valor de uma variável secreta usando variável de ambiente ou prompt por meio de entrada padrão. Os valores aceitos são false e true.
  • secret: opcional. Indica se o valor da variável é mantido secreto. Os valores aceitos são false e true.
  • value: atualiza o valor da variável. Para variáveis secretas, use o parâmetro prompt-value para ser solicitado a inseri-lo de maneira padrão. Para consoles não interativos, ele pode ser escolhido na 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 de ambiente AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret.

Exemplo

O comando a seguir atualiza a variável requires-login com o novo valor False no grupo de variáveis com a ID 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 nulo em vez de False, pois é 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 a CLI for nova para você, confira Introdução à CLI do Azure DevOps.

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

Parâmetros

  • group-id: obrigatório. A ID do grupo de variáveis. Para localizar a ID do grupo de variáveis, confira Listar grupos de variáveis.
  • nome: Obrigatórios. O nome da variável que você está excluindo.
  • org: a URL da organização do Azure DevOps. Configure a organização padrão usando az devops configure -d organization=ORG_URL. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • project: nome ou ID do projeto. Você pode configurar o projeto padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado por meio de git config.
  • yes: opcional. Não solicite confirmação.

Exemplo

O comando a seguir exclui a variável requires-login do grupo de variáveis com a ID 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.

Observação

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

Vincule um Azure Key Vault a um grupo de variáveis e mapeie segredos seletivos do cofre para o grupo de variáveis.

  1. Na página Grupos de variáveis, habilite Vincular segredos de um Azure Key Vault como variáveis. Você precisará de um cofre de chaves existente que contenha seus segredos. Crie um key vault usando o portal do Azure.

    Captura de tela do grupo de variáveis com a integração do Azure Key Vault.

  2. Especifique o ponto de extremidade da 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 as permissões de gerenciamento Obter e Listar no cofre para obter segredos. Habilite o Azure Pipelines para definir essas permissões escolhendo Autorizar ao lado do nome do cofre. Ou então, defina as permissões manualmente no portal do Azure:

    1. Abra Configurações para o cofre e escolha Políticas de acesso>Adicionar.
    2. Selecione Selecionar entidade e escolha a entidade de serviço para sua conta cliente.
    3. Selecione Permissões de segredo e verifique se Obter e Listar estão marcadas.
    4. Selecione Ok para salvar as alterações.

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

Gerenciar segredos do Key Vault

Confira a lista a seguir de dicas úteis para gerenciar segredos.

  • Somente os nomes de segredo são mapeados para o grupo de variáveis, não os valores de segredo. O valor do segredo mais recente, buscado do cofre, é usado na execução de pipeline vinculada ao grupo de variáveis.

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

  • Quando 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 precisam ser atualizados explicitamente 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 ao gerenciamento de chaves criptográficas e segredos no Azure. Atualmente, a integração de grupo de variáveis do Azure Pipelines dá suporte ao mapeamento apenas de segredos do Azure Key Vault. Não há suporte para chaves criptográficas e certificados.

Expandir as 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 precedência de variáveis, consulte Variáveis.