Desbloquear Variáveis do Azure DevOps para Automação

Se você construiu um Pipeline do Azure DevOps como sua solução para um pipeline CI/CD, você sem dúvida se deparou com situações que exigem o gerenciamento dinâmico de valores de configuração em compilações e releases. Quer seja fornecendo uma versão de compilação para um script do PowerShell, passando parâmetros dinâmicos para tarefas de compilação ou usando strings em compilações e releases, você precisa de variáveis.

Se você já se perguntou questões como:

• Como usar variáveis do Pipeline de compilação do Azure DevOps em um script do PowerShell?
• Como compartilhar variáveis entre compilações e releases?
• Como diferem as variáveis predefinidas, definidas pelo usuário e secretas?
• Como funcionam os grupos de variáveis?

…então você está com sorte! Neste artigo, responderemos a cada uma dessas perguntas e mais.

Ao final deste artigo, você entenderá como as variáveis de compilação do Azure DevOps funcionam nos Pipelines do Azure!

O que são Variáveis de Pipeline do Azure DevOps?

Antes de mergulharmos nos detalhes das variáveis, o que são elas e como ajudam você a construir e automatizar pipelines de compilação e release eficientes?

As variáveis permitem que você passe partes de dados para várias partes de seus pipelines. As variáveis são ótimas para armazenar texto e números que podem mudar ao longo do fluxo de trabalho de um pipeline. Em um pipeline, você pode definir e ler variáveis quase em qualquer lugar, em vez de codificar valores em scripts e definições YAML.

Nota: Este artigo focará apenas em pipelines YAML. Não abordaremos nenhuma informação sobre pipelines clássicos legados. Além disso, com algumas poucas exceções, você não aprenderá como trabalhar com variáveis via interface web. Vamos nos ater estritamente ao YAML.

As variáveis são referenciadas e algumas são definidas (consulte variáveis definidas pelo usuário) em tempo de execução. Quando um pipeline inicia um job, diversos processos gerenciam essas variáveis e passam seus valores para outras partes do sistema. Este sistema oferece uma maneira de executar jobs de pipeline de forma dinâmica sem se preocupar em alterar definições de build e scripts toda vez.

Não se preocupe se você não entender o conceito de variáveis neste momento. O restante deste artigo irá ensinar tudo o que você precisa saber.

Ambientes de Variáveis

Antes de entrar nas variáveis propriamente ditas, é importante abordar os ambientes de variáveis do pipeline Azure. Você verá várias referências a esse termo ao longo do artigo.

Dentro de um pipeline, existem dois lugares informalmente chamados de ambientes onde você pode interagir com variáveis. Você pode trabalhar com variáveis dentro de uma definição de build YAML chamada ambiente do pipeline ou dentro de um script executado via uma tarefa chamada ambiente do script.

O Ambiente de Pipeline

Ao definir ou ler variáveis de compilação dentro de uma definição de compilação YAML, isso é chamado de ambiente de pipeline. Por exemplo, abaixo você pode ver a seção de variables definida em uma definição de compilação YAML, configurando uma variável chamada foo para bar. Neste contexto, a variável está sendo definida dentro do ambiente de pipeline

variables:
  foo: 'bar'

O Ambiente de Script

Você também pode trabalhar com variáveis de código definidas na própria definição YAML ou em scripts. Quando você não tem um script existente já criado, você pode definir e ler variáveis dentro da definição YAML, como mostrado abaixo. Você aprenderá a sintaxe de como lidar com essas variáveis neste contexto mais tarde.

steps:
 - bash: ## Configurando e obtendo variáveis aqui

Você poderia, alternativamente, permanecer dentro do ambiente de script adicionando esta mesma sintaxe a um script Bash e executando-o. Este é o mesmo conceito geral.

Variáveis de Ambiente

No ambiente de script, quando uma variável de pipeline está disponível, isso é feito criando uma variável de ambiente. Essas variáveis de ambiente podem então ser acessadas pelos métodos típicos da linguagem escolhida.

Variáveis de pipeline expostas como variáveis de ambiente sempre terão letras maiúsculas e qualquer ponto será substituído por sublinhados. Por exemplo, você verá abaixo como cada linguagem de script pode acessar a variável de pipeline foo, conforme mostrado abaixo.

variables:
  foo: 'bar'

• Lote – %FOO%
• PowerShell – $env:FOO
• Script Bash – $FOO

Fases de “Execução” do Pipeline

Quando um pipeline “executa”, ele não apenas “executa”. Assim como os estágios que contém, um pipeline também passa por várias fases quando é executado. Devido à falta de um termo oficial na documentação da Microsoft, estou chamando isso de “fases de execução”.

Quando um pipeline é acionado, ele passa por três fases aproximadas – Fila, Compilação e Tempo de Execução. É importante entender esses contextos porque, se você estiver navegando na documentação da Microsoft, verá referências a esses termos.

Tempo de Fila

A primeira fase pela qual um pipeline passa quando acionado é enfileirada. Nesta fase, o pipeline ainda não começou, mas está enfileirado e pronto para ser iniciado quando o agente estiver disponível. Ao definir variáveis, você pode configurá-las para ficarem disponíveis no momento da fila, não as definindo no arquivo YAML.

Você poderá definir variáveis no momento da fila quando o pipeline for inicialmente enfileirado, como mostrado abaixo. Quando esta variável é adicionada, ela será então disponibilizada como uma variável global no pipeline e pode ser substituída pelo mesmo nome de variável no arquivo YAML.

Compilação

Finalmente, quando um pipeline processa um arquivo YAML e chega às etapas que exigem execução de script, o pipeline está na “fase” de compilação. Neste contexto, o agente está executando o código definido nas etapas do script.

Tempo de execução

A próxima fase é o tempo de execução. Esta é a fase em que o arquivo YAML está sendo processado. Durante esta fase, cada estágio, trabalho e etapa estão sendo processados mas não executando nenhum script.

Expansão de Variável

Outro tópico importante para entender é a expansão de variável. Expansão de variável, em termos mais simples, é quando a variável retorna um valor estático. A variável se expande para revelar o valor que está segurando. Isso é feito para você sem esforço quando você lê uma variável mas essa expansão pode ser feita em momentos diferentes durante a execução de um pipeline que podem te confundir.

Este conceito de expansão de variável e compilação versus tempo de execução surgirá muito quando você começar a entender a sintaxe de variável.

Como você aprendeu acima, o pipeline cobre diferentes “fases” quando é executado. Você precisará estar ciente dessas fases provavelmente ao solucionar problemas de expansão de variável.

Você pode ver um exemplo abaixo. O conceito dessas “fases” está intimamente relacionado aos ambientes de variáveis.

steps:
  # Define FOO como "algum valor" no script e nos próximos
  - bash: |
      FOO="runtime value"
      echo "##vso[task.setvariable variable=FOO]$FOO"

  # Usando a sintaxe $() durante "tempo de compilação", o pipeline expande a variável
  - bash: |
      echo "$(FOO)"

  # Usando uma variável de ambiente no contexto do script em "tempo de execução", bash expande a variável
  - bash: |
      echo "$FOO"

Variáveis são expandidas uma vez quando a execução do pipeline é iniciada e novamente no início de cada etapa. Abaixo, você pode ver um exemplo simples desse comportamento.

jobs:
- job: build
  variables:
  - foo: bar 
  steps:
    - bash: |
        echo $(foo)            # This will be bar
        echo '##vso[task.setvariable variable=foo]baz'
        echo $(foo)            # This will also be bar, $(foo) expands before the step
    - bash: echo $(foo)        # Isso será baz. A variável é expandida logo antes da etapa

Sintaxe de Variável

Como você aprendeu, você pode definir ou ler variáveis em dois “ambientes” – o ambiente do pipeline e o ambiente do script. Enquanto estiver em cada ambiente, a forma como você referencia variáveis é um pouco diferente. Existem algumas nuances que você precisa ficar atento.

Variáveis de Pipeline

As variáveis de pipeline são referenciadas nas definições de build YAML e podem ser referenciadas por meio de três métodos de sintaxe diferentes – macro, expressão de modelo e expressão de tempo de execução.

Sintaxe de Macro

A sintaxe mais comum que você encontrará é a sintaxe de macro. A sintaxe de macro referencia um valor para uma variável no formato $(foo). Os parênteses representam uma expressão que é avaliada durante a execução.

Quando o Azure Pipelines processa uma variável definida como uma expressão de macro, ele substituirá a expressão pelo conteúdo da variável. Ao definir variáveis com a sintaxe de macro, elas seguem o padrão <nome da variável>: $(<valor da variável>) por exemplo, foo: $(bar).

Se você tentar referenciar uma variável com a sintaxe de macro e um valor não existir, a variável simplesmente não existirá. Esse comportamento difere um pouco entre os tipos de sintaxe.

Sintaxe de Expressão de Modelo

Outro tipo de sintaxe de variável é chamado de expressão de modelo. Definir variáveis de pipeline dessa forma tem a forma de ${{ variáveis.foo }} : ${{ variáveis.bar }}. Como você pode ver, é um pouco mais longo que a sintaxe de macro.

A sintaxe de expressão de modelo também possui um recurso adicional. Usando essa sintaxe, você também pode expandir parâmetros de modelo. Se uma variável definida com sintaxe de expressão de modelo for referenciada, o pipeline retornará uma string vazia versus um valor nulo com sintaxe de macro.

As variáveis de expressão de modelo são processadas em tempo de compilação e depois sobrescritas (se definidas) em tempo de execução.

Sintaxe de Expressão de Tempo de Execução

Como o tipo de sintaxe, as variáveis de expressão de tempo de execução sugeridas são expandidas apenas no tempo de execução. Esses tipos de variáveis são representados pelo formato $[variáveis.foo]. Assim como as variáveis de sintaxe de expressão de modelo, esses tipos de variáveis retornarão uma string vazia se não forem substituídas.

Assim como a sintaxe de macro, a sintaxe de expressão de tempo de execução requer o nome da variável no lado esquerdo da definição, como foo: $[variáveis.bar].

Variáveis de Script

Trabalhar com variáveis dentro de scripts é um pouco diferente das variáveis de pipeline. Definir e referenciar variáveis de pipeline expostas em scripts de tarefas pode ser feito de duas maneiras; com sintaxe de comando de registro ou variáveis de ambiente.

Comandos de Registro

Uma maneira de definir e referenciar variáveis de pipeline em scripts é usar a sintaxe de comandos de registro. Essa sintaxe é um pouco complicada, mas você aprenderá que é necessária em determinadas situações. Variáveis definidas dessa maneira devem ser definidas como uma string no script.

Definir uma variável chamada foo com um valor de bar usando a sintaxe de comando de registro seria assim:

"##vso[task.setvariable variable=foo;]bar"

I could not find a way to get the value of variables using logging commands. If this exists, let me know!

Variáveis de Ambiente

Quando as variáveis de pipeline são convertidas em variáveis de ambiente em scripts, os nomes das variáveis são alterados ligeiramente. Você verá que os nomes das variáveis se tornam maiúsculos e os pontos se transformam em sublinhados. Muitas variáveis pré-definidas ou do sistema têm pontos nelas.

Por exemplo, se uma variável de pipeline chamada [foo.bar](<http://foo.bar>) fosse definida, você faria referência a essa variável através do método de referência de variáveis de ambiente nativas do script, como $env:FOO_BAR no PowerShell ou $FOO_BAR no Bash.

Cobrimos mais sobre variáveis de ambiente na seção Ambiente de Script acima.

Escopo de Variável

A pipeline has various stages, tasks and jobs running. Many areas have predefined variable scopes. A scope is namespace where when a variable is defined, its value can be referenced.

Existem essencialmente três escopos diferentes de variáveis em uma hierarquia. Elas são variáveis definidas em:

• o nível raiz tornando variáveis disponíveis para todos os trabalhos no pipeline
• o nível de estágio tornando variáveis disponíveis para um estágio específico
• o nível de trabalho tornando variáveis disponíveis para um trabalho específico

Variáveis definidas nos “níveis” mais baixos, como um trabalho, substituirão a mesma variável definida no nível do estágio e raiz, por exemplo. Variáveis definidas no nível do estágio substituirão variáveis definidas no nível “raiz”, mas serão substituídas por variáveis definidas no nível do trabalho.

Abaixo você pode ver um exemplo de definição de compilação YAML em que cada escopo está sendo usado.

variables:
  global_variable: value  # isso está globalmente disponível para todos os estágios e trabalhos

stages:
- stage: Build
  variables:
    stage_variable1: value3 # disponível no estágio de compilação e em todos os trabalhos
  jobs:
  - job: BuildJob
    variables:
      job_variable1: value1    # isso está disponível apenas em BuildJob
    steps:
    - bash: echo $(stage_variable1) ## funciona
    - bash: echo $(global_variable) ## funciona
    - bash: echo $(job_variable1) ## funciona

Precedência de Variável

Às vezes, você verá uma situação em que uma variável com o mesmo nome é definida em vários escopos. Quando isso acontece, o valor daquela variável será sobrescrito de acordo com uma sequência específica, dando precedência à “ação” mais próxima.

Abaixo, você verá a ordem na qual as variáveis serão sobrescritas, começando com uma variável definida dentro de um trabalho. Isso terá a maior precedência.

1. Variável definida no nível do trabalho (definida no arquivo YAML)
2. Variável definida no nível do estágio (definida no arquivo YAML)
3. Variável definida no nível do pipeline (global) (definida no arquivo YAML)
4. Variável definida no momento da fila
5. Variável do pipeline definida nas configurações de Pipeline UI

Por exemplo, dê uma olhada na definição YAML abaixo. Neste exemplo, a mesma variável é definida em várias áreas diferentes, mas acaba tendo o valor definido no job. Com cada ação, o valor da variável é sobrescrito à medida que o pipeline avança para o job.

variables:
  foo: 'global variable'

stages:
- stage: build
  variables:
   - name: foo
     value: 'defined at stage level'

  jobs:
  - job: compile
    variables:
    - name: foo
      value: 'defined at job level'
    steps:
      - bash: echo $(foo) # Isso será 'definido no nível do job'

Tipos de Variáveis

Você aprendeu sobre o que são variáveis, como elas são, os contextos em que podem ser executadas e muito mais até agora neste artigo. Mas o que não abordamos é que nem todas as variáveis são iguais. Algumas variáveis já existem quando um pipeline começa e não podem ser alteradas, enquanto outras você pode criar, alterar e remover à vontade.

Há quatro tipos gerais de variáveis – variáveis predefinidas ou do sistema, variáveis definidas pelo usuário, variáveis de saída e variáveis secretas. Vamos cobrir cada uma delas e entender cada tipo de variável.

Variáveis Predefinidas

Em todas as compilações e lançamentos, você encontrará muitas variáveis diferentes que existem por padrão. Essas variáveis são chamadas de variáveis predefinidas ou variáveis do sistema. As variáveis predefinidas são todas somente leitura e, assim como outros tipos de variáveis, representam simples strings e números.

Um pipeline do Azure consiste em muitos componentes, desde o agente de software que executa a compilação, até os jobs que são iniciados quando uma implantação é executada e outras informações diversas. Para representar todas essas áreas, as variáveis predefinidas ou do sistema são informalmente divididas em cinco categorias distintas:

• Agente
• Compilação
• Pipeline
• Trabalho de implantação
• Sistema

Há dezenas de variáveis espalhadas por cada uma dessas cinco categorias. Você não vai aprender sobre todas elas neste artigo. Se você deseja uma lista de todas as variáveis predefinidas, dê uma olhada na documentação da Microsoft.

Variáveis Definidas pelo Usuário

Ao criar uma variável em uma definição YAML ou via script, você está criando uma variável definida pelo usuário. Variáveis definidas pelo usuário são simplesmente todas as variáveis que você, como usuário, define e usa em um pipeline. Você pode usar praticamente qualquer nome para essas variáveis, com algumas exceções.

Você não pode definir variáveis que começam com a palavra endpoint, input, secret, ou securefile. Esses rótulos estão fora de limites porque são reservados para uso do sistema e não fazem distinção entre maiúsculas e minúsculas.

Além disso, quaisquer variáveis que você definir devem consistir apenas de letras, números, pontos ou caracteres de sublinhado. Se você tentar definir uma variável que não siga este formato, sua definição de compilação YAML não funcionará.

Variáveis de Saída

A build definition contains one or more tasks. Sometimes a task sends a variable out to be made available to downstream steps and jobs within the same stage. These types of variables are called output variables.

Variáveis de saída são usadas para compartilhar informações entre os componentes do pipeline. Por exemplo, se uma tarefa consulta um valor de um banco de dados e tarefas subsequentes precisam do resultado retornado, uma variável de saída pode ser usada. Assim, você não precisa consultar o banco de dados toda vez. Em vez disso, você pode simplesmente referenciar a variável.

Nota: As variáveis de saída são definidas para uma etapa específica. Não espere que uma variável de saída esteja disponível em sua etapa de “build” e também em sua etapa de “testing”, por exemplo.

Variáveis Secretas

O último tipo de variável é a variável secreta. Tecnicamente, esta não é um tipo independente, pois pode ser uma variável definida pelo sistema ou pelo usuário. No entanto, as variáveis secretas precisam estar em sua própria categoria porque são tratadas de maneira diferente de outras variáveis.

A secret variable is a standard variable that’s encrypted. Secret variables typically contain sensitive information like API keys, passwords, etc. These variables are encrypted at rest with a 2048-bit RSA key and are available on the agent for all tasks and scripts to use.

– NÃO defina variáveis secretas dentro de seus arquivos YAML
– NÃO divulgue segredos como variáveis de saída ou informações de registro

As variáveis secretas devem ser definidas no editor de pipeline. Isso limita as variáveis secretas ao nível global, tornando-as disponíveis para tarefas na pipeline.

Os valores secretos são mascarados nos logs, mas não completamente. Por isso, é importante não incluí-los em um arquivo YAML. Você também deve saber que não deve incluir nenhum dado “estruturado” como um segredo. Se, por exemplo, { "foo": "bar" } for definido como um segredo, bar não será mascarado nos logs.

Os segredos não são descriptografados automaticamente e mapeados para variáveis de ambiente. Se você definir uma variável secreta, não espere que ela esteja disponível via $env:FOO em um script PowerShell, por exemplo.

Grupos de Variáveis

Finalmente, chegamos aos grupos de variáveis. Grupos de variáveis, como você pode esperar, são “grupos” de variáveis que podem ser referenciados como um só. O objetivo principal de um grupo de variáveis é armazenar valores que você deseja tornar disponíveis em várias pipelines.

Ao contrário de variáveis, grupos de variáveis não são definidos no arquivo YAML. Em vez disso, eles são definidos na página da Biblioteca sob Pipelines na interface do usuário.

Use um grupo de variáveis para armazenar valores que você deseja controlar e tornar disponíveis em vários pipelines. Você também pode usar grupos de variáveis para armazenar segredos e outros valores que possam precisar ser passados para um pipeline YAML. Grupos de variáveis são definidos e gerenciados na página da Biblioteca sob Pipelines conforme mostrado abaixo.

Depois de definido na biblioteca de pipelines, você pode então acessar esse grupo de variáveis no arquivo YAML usando a sintaxe abaixo.

variables:
- group: group1

Grupos de variáveis não estão, por padrão, disponíveis para todos os pipelines. Essa configuração está disponível ao criar o grupo. Os pipelines devem ser autorizados a usar um grupo de variáveis.

Depois que um grupo de variáveis for acessado no arquivo YAML, você poderá acessar as variáveis dentro do grupo exatamente como faria com qualquer outra variável. O nome do grupo de variáveis não é usado ao referenciar variáveis no grupo.

Por exemplo, se você definiu um grupo de variáveis chamado grupo1 com uma variável chamada foo dentro, você referenciaria a variável foo como qualquer outra, por exemplo, $(foo).

Variáveis secretas definidas em um grupo de variáveis não podem ser acessadas diretamente via scripts. Em vez disso, elas devem ser passadas como argumentos para a tarefa.

Se uma alteração for feita em uma variável dentro de um grupo de variáveis, essa alteração será automaticamente disponibilizada para todos os pipelines autorizados a usar esse grupo.

Resumo

Você deve agora ter um conhecimento sólido das variáveis do Azure Pipelines. Você aprendeu praticamente todos os conceitos relacionados a variáveis neste artigo! Agora, vá lá, aplique esse conhecimento em seus Azure DevOps Pipelines e automatize tudo!