Compartilhar via


Definir variáveis

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

As variáveis oferecem uma forma conveniente de inserir os principais bits de dados em várias partes do pipeline. O uso mais comum de variáveis é definir um valor que você pode usar em seu pipeline. Todas as variáveis são cadeias de caracteres e são mutáveis. O valor de uma variável pode mudar de execução para execução ou de trabalho para trabalho do pipeline.

Quando você define a mesma variável em vários locais com o mesmo nome, a variável com escopo mais local vence. Portanto, uma variável definida no nível do trabalho pode substituir uma variável definida no nível de fase. Uma variável definida no nível de fase substitui uma variável definida no nível raiz do pipeline. Uma variável definida no nível raiz do pipeline substitui uma variável definida na interface do usuário de configurações do pipeline. Para saber mais sobre como trabalhar com variáveis definidas no trabalho, no estágio e no nível raiz, consulte Escopo da variável.

Você pode usar variáveis com expressões para atribuir valores condicionalmente e personalizar ainda mais os pipelines.

As variáveis são diferentes dos parâmetros de runtime. Os parâmetros de runtime são tipados e disponíveis durante a análise de modelo.

Variáveis definidas pelo usuário

Ao definir uma variável, você pode usar sintaxes diferentes (macro, expressão de modelo ou runtime) e a sintaxe que você usa determina onde, no pipeline, sua variável é renderizada.

Em pipelines YAML, você pode definir variáveis no nível raiz, de fase e de trabalho. Você também pode especificar variáveis fora de um pipeline YAML na interface do usuário. Quando você define uma variável na interface do usuário, essa variável pode ser criptografada e definida como secreta.

As variáveis definidas pelo usuário podem ser definidas como somente leitura. Há restrições de nomenclatura para variáveis (exemplo: você não pode usar secret no início de um nome de variável).

Você pode usar um grupo de variáveis para disponibilizar variáveis em vários pipelines.

Use modelos para definir variáveis em um arquivo usado em vários pipelines.

Variáveis de várias linhas definidas pelo usuário

O Azure DevOps dá suporte a variáveis de várias linhas, mas há algumas limitações.

Componentes downstream, como tarefas de pipeline, podem não manipular os valores de variável corretamente.

O Azure DevOps não alterará os valores de variáveis definidos pelo usuário. Os valores variáveis precisam ser formatados corretamente antes de serem passados como variáveis de várias linhas. Ao formatar sua variável, evite caracteres especiais, não use nomes restritos e use um formato de delimitador que funcione para o sistema operacional do agente.

Variáveis de várias linhas se comportam de maneira diferente, dependendo do sistema operacional. Para evitar isso, formate variáveis de várias linhas corretamente para o sistema operacional de destino.

O Azure DevOps nunca altera valores de variáveis, mesmo que você forneça formatação incompatível.

Variáveis do sistema

Além das variáveis definidas pelo usuário, o Azure Pipelines tem variáveis de sistema com valores predefinidos. Por exemplo, a variável Build.BuildId predefinida fornece a ID de cada build e pode ser usada para identificar diferentes execuções de pipeline. Você pode usar a variável Build.BuildId em scripts ou tarefas quando precisar de um valor exclusivo.

Se você estiver usando YAML ou pipelines de build clássicos, confira variáveis predefinidas para obter uma lista abrangente de variáveis do sistema.

Se você estiver usando pipelines de lançamento clássicos, confira Variáveis de versão.

As variáveis do sistema são definidas com o valor atual delas quando você executa o pipeline. Algumas variáveis são definidas automaticamente. Como um autor de pipeline ou usuário final, você altera o valor de uma variável do sistema antes da execução do pipeline.

As variáveis de sistema são somente leitura.

Variáveis de ambiente

As variáveis de ambiente são específicas para o sistema operacional que você está usando. Eles são injetados em um pipeline de maneiras específicas para cada plataforma. O formato corresponde a como as variáveis de ambiente são formatadas para sua plataforma de script específica.

Em sistemas UNIX (macOS e Linux), as variáveis de ambiente têm o formato $NAME. No Windows, o formato é %NAME% para lote e $env:NAME no PowerShell.

As variáveis definidas pelo sistema e pelo usuário também são injetadas como variáveis de ambiente para sua plataforma. Quando as variáveis são convertidas em variáveis de ambiente, os nomes de variáveis passam a ficar em maiúsculas e os pontos se transformam em sublinhados. Por exemplo, o nome de variável any.variable se torna $ANY_VARIABLE.

restrições de nomenclatura de variáveis para variáveis de ambiente (exemplo: você não pode usar secret no início de um nome de variável).

Restrições de nomenclatura de recursos

As variáveis de ambiente e definidas pelo usuário podem consistir em letras, números e nos caracteres .e _. Não use prefixos de variáveis reservados pelo sistema. Eles são endpoint, input, secret, path e securefile. Qualquer variável que comece com uma dessas cadeias de caracteres (independentemente da capitalização) não estará disponível para suas tarefas e scripts.

Noções básicas sobre sintaxe de variáveis

O Azure Pipelines suporta três maneiras diferentes de referenciar variáveis: macro, expressão de modelo e expressão de runtime. Você pode usar cada sintaxe para uma finalidade diferente e cada uma delas tem algumas limitações.

Em um pipeline, as variáveis de expressão de modelo (${{ variables.var }}) são processadas em tempo de build, antes do runtime iniciar. A sintaxe de macro ($(var)) de variáveis é processada durante o runtime, antes da execução de uma tarefa. As expressões de runtime ($[variables.var]) também são processadas durante o runtime, mas devem ser usadas com condições e expressões. Quando se usa uma expressão de runtime, ela deve ocupar todo o lado direito de uma definição.

Neste exemplo, você pode ver que a expressão de modelo ainda tem o valor inicial da variável depois que a variável é atualizada. O valor das atualizações da variável de sintaxe de macro. O valor da expressão de modelo não é alterado porque todas as variáveis de expressão de modelo são processadas em tempo de build antes da execução das tarefas. Por outro lado, as variáveis de sintaxe de macro são avaliadas antes da execução de cada tarefa.

variables:
- name: one
  value: initialValue 

steps:
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one)
    displayName: First variable pass
  - bash: echo "##vso[task.setvariable variable=one]secondValue"
    displayName: Set new variable value
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one) # outputs secondValue
    displayName: Second variable pass

Variáveis de sintaxe de macro

A maioria dos exemplos de documentação usa a sintaxe de macro ($(var)). A sintaxe de macro foi projetada para interpolar valores de variáveis em entradas de tarefa e em outras variáveis.

Variáveis com sintaxe de macro são processadas antes que uma tarefa seja executada durante o runtime. O runtime ocorre após a expansão do modelo. Quando o sistema encontra uma expressão de macro, ele substitui a expressão pelo conteúdo da variável. Se não houver nenhuma variável com esse nome, a expressão de macro não será alterada. Por exemplo, se $(var) não puder ser substituída, $(var) não será substituída por nada.

As variáveis de sintaxe de macro permanecem inalteradas sem nenhum valor, porque um valor vazio como $() pode significar algo para a tarefa que você está executando, e o agente não deve presumir que você deseja que esse valor seja substituído. Por exemplo, se você usar $(foo) para fazer referência à variável foo em uma tarefa do Bash, substituir todas as expressões $() na entrada para a tarefa poderá interromper seus scripts Bash.

As variáveis de macro só são expandidas quando usadas para um valor, não como uma palavra-chave. Os valores aparecem no lado direito de uma definição de pipeline. O seguinte é válido: key: $(value). O seguinte não é válido: $(key): value. As variáveis de macro não são expandidas quando usadas para exibir um nome de trabalho em linha. Em vez disso, você precisa usar a propriedade displayName.

Observação

As variáveis de sintaxe de macro são expandidas apenas para stages, jobs e steps. Você não pode, por exemplo, usar a sintaxe de macro dentro de um resource ou trigger.

Este exemplo usa a sintaxe macro com Bash, PowerShell e uma tarefa de script. A sintaxe para chamar uma variável com sintaxe de macro é a mesma para todos os três.

variables:
 - name: projectName
   value: contoso

steps: 
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)

Expressão de modelo

Você pode usar a sintaxe de expressão de modelo para expandir parâmetros de modelo e variáveis (${{ variables.var }}). As variáveis de modelo processam em tempo de build e são substituídas antes do início do runtime. As expressões de modelo são projetadas para reutilizar partes do YAML como modelos.

As variáveis de modelo se unem silenciosamente a cadeias de caracteres vazias quando nenhum valor substituto é encontrado. As expressões de modelo, ao contrário das expressões de macro e runtime, podem aparecer como chaves (lado esquerdo) ou valores (lado direito). O seguinte é válido: ${{ variables.key }} : ${{ variables.value }}.

Sintaxe da expressão lambda

Você pode usar a sintaxe de expressão de runtime para variáveis expandidas em runtime ($[variables.var]). As variáveis de expressão de runtime se agrupam silenciosamente a cadeias de caracteres vazias quando nenhum valor substituto é encontrado. Use expressões de runtime em condições de trabalho para dar suporte à execução condicional de trabalhos ou fases inteiras.

As variáveis de expressão de runtime só são expandidas quando são usadas para um valor, não como uma palavra-chave. Os valores aparecem no lado direito de uma definição de pipeline. O seguinte é válido: key: $[variables.value]. O seguinte não é válido: $[variables.key]: value. A expressão de runtime precisa ocupar todo o lado direito de um par chave-valor. Por exemplo, key: $[variables.value] é válida, mas key: $[variables.value] foo não é válida.

Sintaxe Exemplo Quando ele é processado? Onde ele se expande em uma definição de pipeline? Como ele é renderizado quando não encontrado?
Macro $(var) runtime antes de uma tarefa ser executada valor (lado direito) imprime $(var)
expressão de modelo ${{ variables.var }} tempo de build chave ou valor (lado esquerdo ou direito) cadeia de caracteres vazia
expressão de runtime $[variables.var] runtime valor (lado direito) cadeia de caracteres vazia

Qual sintaxe devo usar?

Use a sintaxe de macro se você estiver fornecendo entrada para uma tarefa.

Escolha uma expressão de runtime se você estiver trabalhando com condições e expressões. No entanto, não use uma expressão de runtime se você não quiser que sua variável vazia seja impressa (exemplo: $[variables.var]). Por exemplo, se você tiver uma lógica condicional que dependa de uma variável ter um valor específico ou nenhum valor. Nesse caso, você deve usar uma expressão de macro.

Se você estiver definindo uma variável em um modelo, use uma expressão de modelo.

Definir variáveis no pipeline

No caso mais comum, você define as variáveis e as usa no arquivo YAML. Isso também permite que você acompanhe as alterações na variável em seu sistema de controle de versão. Você também pode definir variáveis na interface do usuário de configurações de pipeline (consulte a guia Clássico) e referenciá-las em seu YAML.

Aqui está um exemplo que mostra como definir duas variáveis, configuration e platform, e usá-las posteriormente em etapas. Para usar uma variável em uma instrução YAML, encapsule-a em $(). As variáveis não podem ser usadas para definir um repository em uma instrução YAML.

# Set variables once
variables:
  configuration: debug
  platform: x64

steps:

# Use them once
- task: MSBuild@1
  inputs:
    solution: solution1.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

# Use them again
- task: MSBuild@1
  inputs:
    solution: solution2.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

Escopos de variável

No arquivo YAML, você pode definir uma variável em vários escopos:

  • No nível raiz, para disponibilizá-la para todos os trabalhos no pipeline.
  • No nível de fase, para disponibilizá-lo apenas para uma fase específica.
  • No nível de trabalho, para disponibilizá-la somente para um trabalho específico.

Quando você define uma variável na parte superior de um YAML, a variável está disponível para todos os trabalhos e fases no pipeline e é uma variável global. As variáveis globais definidas em um YAML não são visíveis na interface do usuário das configurações do pipeline.

As variáveis no nível de trabalho substituem variáveis no nível raiz e de fase. Variáveis no nível de estágio substituem variáveis no nível raiz.

variables:
  global_variable: value    # this is available to all jobs

jobs:
- job: job1
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable1: value1    # this is only available in job1
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable1)
  - bash: echo $JOB_VARIABLE1 # variables are available in the script environment too

- job: job2
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable2: value2    # this is only available in job2
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable2)
  - bash: echo $GLOBAL_VARIABLE

A saída de ambos os trabalhos tem esta aparência:

# job1
value 
value1
value1

# job2
value
value2
value

Especificar variáveis

Nos exemplos anteriores, a palavra-chave variables é seguida por uma lista de pares chave-valor. As chaves são os nomes das variáveis e os valores são os valores de variável.

Há outra sintaxe útil quando você deseja usar modelos de variável ou grupos de variáveis.

Com modelos, as variáveis podem ser definidas em um YAML e incluídas em outro arquivo YAML.

Os grupos de variáveis são um conjunto de variáveis que você pode usar em vários pipelines. Eles permitem que você gerencie e organize variáveis que são comuns a vários estágios em um só lugar.

Use essa sintaxe para modelos de variáveis e grupos de variáveis no nível raiz de um pipeline.

Nessa sintaxe alternativa, a palavra-chave variables usa uma lista de especificadores de variável. Os especificadores de variável são name para uma variável regular, group para um grupo de variáveis e template para incluir um modelo de variável. O exemplo a seguir demonstra os três.

variables:
# a regular variable
- name: myvariable
  value: myvalue
# a variable group
- group: myvariablegroup
# a reference to a variable template
- template: myvariabletemplate.yml

Saiba mais sobre a reutilização de variáveis com modelos.

Acessar variáveis por meio do ambiente

Observe que as variáveis também são disponibilizadas para scripts por meio de variáveis de ambiente. A sintaxe para usar essas variáveis de ambiente depende da linguagem de script.

O nome é em maiúsculas e o . é substituído pelo _. Isso é inserido automaticamente no ambiente de processo. Estes são alguns exemplos:

  • Script de lote: %VARIABLE_NAME%
  • Script do PowerShell: $env:VARIABLE_NAME
  • Script Bash: $VARIABLE_NAME

Importante

Variáveis predefinidas que contêm caminhos de arquivo são convertidas para o estilo apropriado (estilo do Windows C:\foo\ versus estilo Unix /foo/) com base no tipo de shell e no tipo de host do agente. Se você estiver executando tarefas de script bash no Windows, deverá usar o método de variável de ambiente para acessar essas variáveis em vez do método de variável de pipeline, para garantir que você tenha o estilo de caminho de arquivo correto.

Definir variáveis secretas

Dica

As variáveis secretas não são exportadas automaticamente como variáveis de ambiente. Para usar variáveis secretas em seus scripts, mapeie-as explicitamente para variáveis de ambiente. Para obter mais informações, consulte Definir variáveis secretas.

Não defina variáveis secretas no arquivo YAML. Os sistemas operacionais geralmente registram comandos para os processos executados e você não gostaria que o log incluísse um segredo que você passou como uma entrada. Use o ambiente do script ou mapeie a variável dentro do bloco variables para passar segredos para o pipeline.

Observação

O Azure Pipelines faz um esforço para mascarar segredos ao emitir dados para logs de pipeline, para que você possa ver variáveis adicionais, dados mascarados na saída e logs que não são definidos como segredos.

Você precisa definir variáveis secretas na interface do usuário das configurações do pipeline para o pipeline. Essas variáveis têm como escopo o pipeline em que estão definidas. Você também pode definir variáveis secretas em grupos de variáveis.

Para definir segredos na interface da Web, siga estas etapas:

  1. Acesse a página Pipelines, selecione o pipeline apropriado e escolha Editar.
  2. Localize as Variáveis desse pipeline.
  3. Adicione ou atualize a variável.
  4. Selecione a opção Manter esse valor em segredo para armazenar a variável de maneira criptografada.
  5. Salve o pipeline.

As variáveis secretas são criptografadas em estado inativo com uma chave RSA de 2.048 bits. Os segredos estão disponíveis no agente para uso por tarefas e scripts. Seja cauteloso com quem tem acesso para alterar o pipeline.

Importante

Fazemos um esforço para mascarar a exibição de segredos na saída do Azure Pipelines, mas ainda é preciso tomar precauções. Nunca ecoe segredos como saída. Alguns sistemas operacionais registram argumentos de linha de comando. Nunca transmita segredos na linha de comando. Em vez disso, a recomendação é mapear os segredos para variáveis de ambiente.

Nunca mascare as subcadeias de caracteres de segredos. Por exemplo, se "abc123" for definido como um segredo, "abc" não será mascarado nos logs. Isso evita mascarar segredos em um nível muito granular, o que torna os logs ilegíveis. Por esse motivo, os segredos não devem conter dados estruturados. Por exemplo, se "{ "foo": "bar" }" for definido como um segredo, "bar" não será mascarado nos logs.

Ao contrário de uma variável normal, elas não são descriptografadas automaticamente em variáveis de ambiente para scripts. Você precisa mapear explicitamente as variáveis secretas.

O exemplo a seguir mostra como mapear e usar uma variável secreta chamada mySecret em scripts do PowerShell e do Bash. Duas variáveis globais são definidas. GLOBAL_MYSECRET é atribuído o valor de uma variável mySecret secreta, e GLOBAL_MY_MAPPED_ENV_VAR é atribuído o valor de uma variável nonSecretVariable não secreta. Ao contrário de uma variável de pipeline normal, não há nenhuma variável de ambiente chamada MYSECRET.

A tarefa do PowerShell executa um script para imprimir as variáveis.

  • $(mySecret): esta é uma referência direta à variável secreta e funciona.
  • $env:MYSECRET: isso tenta acessar a variável secreta como uma variável de ambiente, que não funciona porque as variáveis secretas não são mapeadas automaticamente para variáveis de ambiente.
  • $env:GLOBAL_MYSECRET: isso tenta acessar a variável secreta por meio de uma variável global, que também não funciona porque as variáveis secretas não podem ser mapeadas dessa maneira.
  • $env:GLOBAL_MY_MAPPED_ENV_VAR: isso acessa a variável não secreta por meio de uma variável global, que funciona.
  • $env:MY_MAPPED_ENV_VAR: isso acessa a variável secreta por meio de uma variável de ambiente específica da tarefa, que é a maneira recomendada de mapear variáveis secretas para variáveis de ambiente.
variables:
 GLOBAL_MYSECRET: $(mySecret) # this will not work because the secret variable needs to be mapped as env
 GLOBAL_MY_MAPPED_ENV_VAR: $(nonSecretVariable) # this works because it's not a secret.

steps:

- powershell: |
    Write-Host "Using an input-macro works: $(mySecret)"
    Write-Host "Using the env var directly does not work: $env:MYSECRET"
    Write-Host "Using a global secret var mapped in the pipeline does not work either: $env:GLOBAL_MYSECRET"
    Write-Host "Using a global non-secret var mapped in the pipeline works: $env:GLOBAL_MY_MAPPED_ENV_VAR" 
    Write-Host "Using the mapped env var for this task works and is recommended: $env:MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable

- bash: |
    echo "Using an input-macro works: $(mySecret)"
    echo "Using the env var directly does not work: $MYSECRET"
    echo "Using a global secret var mapped in the pipeline does not work either: $GLOBAL_MYSECRET"
    echo "Using a global non-secret var mapped in the pipeline works: $GLOBAL_MY_MAPPED_ENV_VAR" 
    echo "Using the mapped env var for this task works and is recommended: $MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable


A saída de ambas as tarefas no script anterior teria esta aparência:

Using an input-macro works: ***
Using the env var directly does not work:
Using a global secret var mapped in the pipeline does not work either:
Using a global non-secret var mapped in the pipeline works: foo
Using the mapped env var for this task works and is recommended: ***

Você também pode usar variáveis secretas fora dos scripts. Por exemplo, você pode mapear variáveis secretas para tarefas usando a definição variables. Este exemplo mostra como usar as variáveis secretas $(vmsUser) e $(vmsAdminPass) em uma tarefa de cópia de arquivo do Azure.

variables:
  VMS_USER: $(vmsUser)
  VMS_PASS: $(vmsAdminPass)

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: AzureFileCopy@4
  inputs:
    SourcePath: 'my/path'
    azureSubscription: 'my-subscription'
    Destination: 'AzureVMs'
    storage: 'my-storage'
    resourceGroup: 'my-rg'
    vmsAdminUserName: $(VMS_USER)
    vmsAdminPassword: $(VMS_PASS)

Variáveis secretas de referência em grupos de variáveis

Este exemplo mostra como fazer referência a um grupo de variáveis no arquivo YAML e também como adicionar variáveis no YAML. Há duas variáveis usadas do grupo de variáveis: user e token. A variável token é secreta e é mapeada para a variável de ambiente $env:MY_MAPPED_TOKEN para que possa ser referenciada no YAML.

Esse YAML faz uma chamada REST para recuperar uma lista de versões e gera o resultado.

variables: 
- group: 'my-var-group' # variable group
- name: 'devopsAccount' # new variable defined in YAML
  value: 'contoso'
- name: 'projectName' # new variable defined in YAML
  value: 'contosoads'

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
        # Encode the Personal Access Token (PAT)
        # $env:USER is a normal variable in the variable group
        # $env:MY_MAPPED_TOKEN is a mapped secret variable
        $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $env:USER,$env:MY_MAPPED_TOKEN)))

        # Get a list of releases
        $uri = "https://vsrm.dev.azure.com/$(devopsAccount)/$(projectName)/_apis/release/releases?api-version=5.1"

        # Invoke the REST call
        $result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

        # Output releases in JSON
        Write-Host $result.value
  env:
    MY_MAPPED_TOKEN: $(token) # Maps the secret variable $(token) from my-var-group

Importante

Por padrão, com repositórios do GitHub, as variáveis secretas associadas ao pipeline não são disponibilizadas para builds de solicitação de pull de forks. Para obter mais informações, confira Contribuições de forks.

Compartilhar variáveis entre pipelines

Para compartilhar variáveis entre vários pipelines em seu projeto, use a interface da Web. Em Biblioteca, use grupos de variáveis.

Usar variáveis de saída por meio de tarefas

Algumas tarefas definem variáveis de saída, que você pode consumir em etapas downstream, trabalhos e fases. No YAML, você pode acessar variáveis entre trabalhos e fases usando dependências.

Ao referenciar trabalhos de matriz em tarefas downstream, você precisará usar uma sintaxe diferente. Confira Definir uma variável de saída de vários trabalhos. Você também precisa usar uma sintaxe diferente para variáveis em trabalhos de implantação. Consulte Suporte para variáveis de saída em trabalhos de implantação.

Algumas tarefas definem variáveis de saída, que você pode consumir em etapas downstream e trabalhos dentro da mesma fase. No YAML, você pode acessar variáveis entre trabalhos usando dependências.

  • Para fazer referência a uma variável de uma tarefa diferente dentro do mesmo trabalho, use TASK.VARIABLE.
  • Para fazer referência a uma variável de uma tarefa de um trabalho diferente, use dependencies.JOB.outputs['TASK.VARIABLE'].

Observação

Por padrão, cada fase em um pipeline depende daquele imediatamente anterior a ele no arquivo YAML. Se você precisar se referir a uma fase que não seja imediatamente anterior à atual, poderá substituir esse padrão automático adicionando uma seção dependsOn à fase.

Observação

Os exemplos a seguir usam a sintaxe de pipeline padrão. Se você estiver usando pipelines de implantação, a sintaxe variável e a variável condicional serão diferentes. Para obter informações sobre a sintaxe específica a ser usada, confira Trabalhos de implantação.

Para esses exemplos, suponha que temos uma tarefa chamada MyTask, que define uma variável de saída chamada MyVar. Saiba mais sobre a sintaxe em Expressões – Dependências.

Usar saídas no mesmo trabalho

steps:
- task: MyTask@1  # this step generates the output variable
  name: ProduceVar  # because we're going to depend on it, we need to name the step
- script: echo $(ProduceVar.MyVar) # this step uses the output variable

Usar saídas em um trabalho diferente

jobs:
- job: A
  steps:
  # assume that MyTask generates an output variable called "MyVar"
  # (you would learn that from the task's documentation)
  - task: MyTask@1
    name: ProduceVar  # because we're going to depend on it, we need to name the step
- job: B
  dependsOn: A
  variables:
    # map the output variable from A into this job
    varFromA: $[ dependencies.A.outputs['ProduceVar.MyVar'] ]
  steps:
  - script: echo $(varFromA) # this step uses the mapped-in variable

Usar saídas em uma fase diferente

Para usar a saída de um estágio diferente, o formato para fazer referência a variáveis é stageDependencies.STAGE.JOB.outputs['TASK.VARIABLE']. No nível de estágio, mas não no nível de trabalho, é possível usar essas variáveis em condições.

As variáveis de saída só estão disponíveis na próxima fase downstream. Se várias fases consumirem a mesma variável de saída, use a condição dependsOn.

stages:
- stage: One
  jobs:
  - job: A
    steps:
    - task: MyTask@1  # this step generates the output variable
      name: ProduceVar  # because we're going to depend on it, we need to name the step

- stage: Two
  dependsOn:
  - One
  jobs:
  - job: B
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

- stage: Three
  dependsOn:
  - One
  - Two
  jobs:
  - job: C
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

Você também pode passar variáveis entre fases com uma entrada de arquivo. Para fazer isso, você precisará definir variáveis na segunda fase no nível do trabalho e, em seguida, passar as variáveis como entradas env:.

## script-a.sh
echo "##vso[task.setvariable variable=sauce;isOutput=true]crushed tomatoes"
## script-b.sh
echo 'Hello file version'
echo $skipMe
echo $StageSauce
## azure-pipelines.yml
stages:

- stage: one
  jobs:
  - job: A
    steps:
    - task: Bash@3
      inputs:
          filePath: 'script-a.sh'
      name: setvar
    - bash: |
       echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]true"
      name: skipstep

- stage: two
  jobs:
  - job: B
    variables:
      - name: StageSauce
        value: $[ stageDependencies.one.A.outputs['setvar.sauce'] ]
      - name: skipMe
        value: $[ stageDependencies.one.A.outputs['skipstep.skipsubsequent'] ]
    steps:
    - task: Bash@3
      inputs:
        filePath: 'script-b.sh'
      name: fileversion
      env:
        StageSauce: $(StageSauce) # predefined in variables section
        skipMe: $(skipMe) # predefined in variables section
    - task: Bash@3
      inputs:
        targetType: 'inline'
        script: |
          echo 'Hello inline version'
          echo $(skipMe) 
          echo $(StageSauce) 

A saída de fases no pipeline anterior tem esta aparência:

Hello inline version
true
crushed tomatoes

Listar variáveis

Você pode listar todas as variáveis em seu pipeline com o comando az pipelines variable list. Para começar, confira Introdução à CLI do Azure DevOps.

az pipelines variable list [--org]
                           [--pipeline-id]
                           [--pipeline-name]
                           [--project]

Parâmetros

  • org: a URL da organização do Azure DevOps. Você pode configurar 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 usando git config. Exemplo: --org https://dev.azure.com/MyOrganizationName/.
  • pipeline-id: obrigatório se pipeline-name não for fornecido. ID do pipeline.
  • pipeline-name: obrigatório se pipeline-id não for fornecido, mas ignorado se pipeline-id for fornecido. Nome do pipeline.
  • project: nome ou ID do projeto. Você pode configurar o grupo padrão usando az devops configure -d project=NAME_OR_ID. Obrigatório se não estiver configurado como padrão ou selecionado usando git config.

Exemplo

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

az pipelines variable list --pipeline-id 12 --output table

Name           Allow Override    Is Secret    Value
-------------  ----------------  -----------  ------------
MyVariable     False             False        platform
NextVariable   False             True         platform
Configuration  False             False        config.debug

Definir variáveis em scripts

Os scripts podem definir variáveis que serão consumidas posteriormente nas etapas subsequentes no pipeline. Todas as variáveis definidas por esse método são tratadas como cadeias de caracteres. Para definir uma variável de um script, use uma sintaxe de comando e imprima para stdout.

Definir uma variável com escopo de trabalho a partir de um script

Para definir uma variável a partir de um script, use o task.setvariable comando logging. Isso atualiza as variáveis de ambiente para os trabalhos subsequentes. Trabalhos subsequentes têm acesso à nova variável com sintaxe de macro e em tarefas como variáveis de ambiente.

Quando issecret é definido como true, o valor da variável é salvo como segredo e mascarado do log. Para obter mais informações sobre variáveis secretas, confira comandos de registro em log.

steps:
# Create a variable
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes" # remember to use double quotes

# Use the variable
# "$(sauce)" is replaced by the contents of the `sauce` variable by Azure Pipelines
# before handing the body of the script to the shell.
- bash: |
    echo my pipeline variable is $(sauce)

A variável de pipeline também será adicionada ao ambiente das etapas subsequentes. Você não pode usar a variável na etapa definida.

steps:
# Create a variable
# Note that this does not update the environment of the current script.
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes"

# An environment variable called `SAUCE` has been added to all downstream steps
- bash: |
    echo "my environment variable is $SAUCE"
- pwsh: |
    Write-Host "my environment variable is $env:SAUCE"

A saída do pipeline anterior.

my environment variable is crushed tomatoes
my environment variable is crushed tomatoes

Definir uma variável de saída de vários trabalhos

Se você quiser disponibilizar uma variável para trabalhos futuros, precisará marcá-la como uma variável de saída usando isOutput=true. Em seguida, você pode mapeá-lo para trabalhos futuros usando a sintaxe $[] e incluindo o nome da etapa que define a variável. Variáveis de saída de vários trabalhos só funcionam para trabalhos na mesma fase.

Para passar variáveis para trabalhos em fases diferentes, use a sintaxe de dependências de fase.

Observação

Por padrão, cada fase em um pipeline depende daquele imediatamente anterior a ele no arquivo YAML. Portanto, cada fase pode usar variáveis de saída da fase anterior. Para acessar outras fases, você precisará alterar o grafo de dependência, por exemplo, se a fase 3 exigir uma variável da fase 1, você precisará declarar uma dependência explícita na fase 1.

Ao criar uma variável de saída de vários trabalhos, você deve atribuir a expressão a uma variável. Neste YAML, $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] é atribuído à variável $(myVarFromJobA).

jobs:
# Set an output variable from job A
- job: A
  pool:
    vmImage: 'windows-latest'
  steps:
  - powershell: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable into job B
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobA: $[ dependencies.A.outputs['setvarStep.myOutputVar'] ]  # map in the variable
                                                                          # remember, expressions require single quotes
  steps:
  - script: echo $(myVarFromJobA)
    name: echovar

A saída do pipeline anterior.

this is the value
this is the value

Se você estiver definindo uma variável de uma fase para outra, use stageDependencies.

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=myStageOutputVar;isOutput=true]this is a stage output var"
       name: printvar

- stage: B
  dependsOn: A
  variables:
    myVarfromStageA: $[ stageDependencies.A.A1.outputs['printvar.myStageOutputVar'] ]
  jobs:
  - job: B1
    steps:
    - script: echo $(myVarfromStageA)

Se você estiver definindo uma variável de uma matriz ou fatia para referenciar a variável ao acessá-la de um trabalho downstream, você precisará incluir:

  • O nome do trabalho.
  • A etapa.
jobs:

# Set an output variable from a job with a matrix
- job: A
  pool:
    vmImage: 'ubuntu-latest'
  strategy:
    maxParallel: 2
    matrix:
      debugJob:
        configuration: debug
        platform: x64
      releaseJob:
        configuration: release
        platform: x64
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the $(configuration) value"
    name: setvarStep
  - bash: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the debug job
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobADebug: $[ dependencies.A.outputs['debugJob.setvarStep.myOutputVar'] ]
  steps:
  - script: echo $(myVarFromJobADebug)
    name: echovar
jobs:

# Set an output variable from a job with slicing
- job: A
  pool:
    vmImage: 'ubuntu-latest'
    parallel: 2 # Two slices
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the slice $(system.jobPositionInPhase) value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ]
  steps:
  - script: "echo $(myVarFromJobsA1)"
    name: echovar

Certifique-se de prefixar o nome do trabalho para as variáveis de saída de um trabalho de implantação. Nesse caso, o nome do trabalho é A:

jobs:

# Set an output variable from a deployment
- deployment: A
  pool:
    vmImage: 'ubuntu-latest'
  environment: staging
  strategy:
    runOnce:
      deploy:
        steps:
        - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the deployment variable value"
          name: setvarStep
        - bash: echo $(setvarStep.myOutputVar)
          name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromDeploymentJob: $[ dependencies.A.outputs['A.setvarStep.myOutputVar'] ]
  steps:
  - bash: "echo $(myVarFromDeploymentJob)"
    name: echovar

Definir variáveis usando expressões

Você pode definir uma variável usando uma expressão. Já encontramos um caso disso para definir uma variável para a saída de outra de um trabalho anterior.

- job: B
  dependsOn: A
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ] # remember to use single quotes

Você pode usar qualquer uma das expressões compatíveis para definir uma variável. Aqui está um exemplo de como definir uma variável para atuar como um contador que começa em 100, é incrementado em 1 para cada execução e é redefinido para 100 todos os dias.

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

Para obter mais informações sobre contadores, dependências e outras expressões, confira expressões.

Definir variáveis configuráveis para etapas

Você pode definir settableVariables dentro de uma etapa ou especificar que nenhuma variável pode ser definida.

Neste exemplo, o script não pode definir uma variável.

steps:
- script: echo This is a step
  target:
    settableVariables: none

Neste exemplo, o script permite a variável sauce, mas não a variável secretSauce. Você verá um aviso na página de execução do pipeline.

Aviso de que você não pode definir secretSauce.

steps:
  - bash: |
      echo "##vso[task.setvariable variable=Sauce;]crushed tomatoes"
      echo "##vso[task.setvariable variable=secretSauce;]crushed tomatoes with garlic"
    target:
     settableVariables:
      - sauce
    name: SetVars
  - bash: 
      echo "Sauce is $(sauce)"
      echo "secretSauce is $(secretSauce)"
    name: OutputVars

Permitir na hora da fila

Se uma variável aparecer no bloco variables de um arquivo YAML, o valor dela será fixo e não poderá ser substituído no tempo de espera. A melhor prática é definir suas variáveis em um arquivo YAML, mas há momentos em que isso não é razoável. Por exemplo, talvez você queira definir uma variável secreta, em vez de ter a variável exposta em seu YAML. Ou talvez seja necessário definir manualmente um valor de variável durante a execução do pipeline.

Você tem duas opções para definir valores de tempo de espera. Você pode definir uma variável na interface do usuário e selecionar a opção Permitir que os usuários substituam esse valor ao executar esse pipeline ou você pode usar parâmetros de runtime. Se a variável não for um segredo, a melhor prática será usar parâmetros de runtime.

Para definir uma variável no momento da fila, adicione uma nova variável no pipeline e selecione a opção de substituição.

Defina uma variável no tempo de espera.

Para permitir que uma variável seja definida no tempo de espera, verifique se a variável também não aparece no bloco variables de um pipeline ou trabalho. Se você definir uma variável no bloco de variáveis de um YAML e na interface do usuário, o valor no YAML terá prioridade.

Expansão de variáveis

Quando você define uma variável com o mesmo nome em vários escopos, a precedência a seguir se aplica (primeiro, a precedência mais alta).

  1. Variável no nível de trabalho definida no arquivo YAML
  2. Variável no nível de fase definida no arquivo YAML
  3. Variável no nível de pipeline definida no arquivo YAML
  4. Conjunto de variáveis na hora da fila
  5. Conjunto de variáveis de pipeline na interface do usuário das configurações de pipeline

No exemplo a seguir, a mesma variável a é definida no nível do pipeline e no nível do trabalho no arquivo YAML. Ela também é definida em um grupo de variáveis G e como uma variável na interface do usuário de configurações do pipeline.

variables:
  a: 'pipeline yaml'

stages:
- stage: one
  displayName: one
  variables:
  - name: a
    value: 'stage yaml'

  jobs:
  - job: A
    variables:
    - name: a
      value: 'job yaml'
    steps:
    - bash: echo $(a)        # This will be 'job yaml'

Quando você definir uma variável com o mesmo nome no mesmo escopo, o último valor definido terá precedência.

stages:
- stage: one
  displayName: Stage One
  variables: 
    - name: a
      value: alpha
    - name: a
      value: beta
  jobs: 
  - job: I
    displayName: Job I
    variables:
      - name: b
        value: uno
      - name: b
        value: dos
    steps: 
    - script: echo $(a) #outputs beta
    - script: echo $(b) #outputs dos

Observação

Ao definir uma variável no arquivo YAML, não a defina no editor da Web como configurável no momento da fila. Atualmente, você não pode alterar variáveis definidas no arquivo YAML no tempo de espera. Se você precisar que uma variável seja configurável no tempo de espera, não a defina no arquivo YAML.

As variáveis são expandidas uma vez quando a execução é iniciada e novamente no início de cada etapa. Por exemplo:

jobs:
- job: A
  variables:
    a: 10
  steps:
  - bash: |
      echo $(a)            # This will be 10
      echo '##vso[task.setvariable variable=a]20'
      echo $(a)            # This will also be 10, since the expansion of $(a) happens before the step
  - bash: echo $(a)        # This will be 20, since the variables are expanded just before the step

Há duas etapas no exemplo anterior. A expansão de $(a) ocorre uma vez no início do trabalho e uma vez no início de cada uma das duas etapas.

Como as variáveis são expandidas no início de um trabalho, você não pode usá-las em uma estratégia. No exemplo a seguir, você não pode usar a variável a para expandir a matriz de trabalho, pois a variável só está disponível no início de cada trabalho expandido.

jobs:
- job: A
  variables:
    a: 10
  strategy:
    matrix:
      x:
        some_variable: $(a)    # This does not work

Se a variável a for uma variável de saída de um trabalho anterior, você poderá usá-la em um trabalho futuro.

- job: A
  steps:
  - powershell: echo "##vso[task.setvariable variable=a;isOutput=true]10"
    name: a_step

# Map the variable into job B
- job: B
  dependsOn: A
  variables:
    some_variable: $[ dependencies.A.outputs['a_step.a'] ]

Expansão recursiva

No agente, as variáveis referenciadas usando a sintaxe $( ) são expandidas recursivamente. Por exemplo:

variables:
  myInner: someValue
  myOuter: $(myInner)

steps:
- script: echo $(myOuter)  # prints "someValue"
  displayName: Variable is $(myOuter)  # display name is "Variable is someValue"