Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
As variáveis fornecem uma maneira conveniente de incluir dados importantes em várias partes do pipeline. O uso mais comum de variáveis é definir um valor que você pode usar em todo o 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 tarefa para tarefa em seu pipeline.
Quando você define a mesma variável em vários locais com o mesmo nome, a variável com escopo mais local tem precedência. 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, estágio e nível raiz, consulte o escopo variável.
Você pode usar variáveis com expressions para atribuir valores condicionalmente e personalizar ainda mais pipelines.
As variáveis diferem dos parâmetros de runtime. Os parâmetros de tempo de execução são tipados e disponíveis durante a análise do modelo.
Variáveis definidas pelo usuário
Ao definir uma variável, use sintaxes diferentes (macro, expressão de modelo ou runtime). A sintaxe escolhida determina onde, no pipeline, sua variável é renderizada.
No YAML pipelines, defina variáveis nos níveis raiz, estágio e trabalho. Você também pode especificar variáveis fora de um pipeline YAML na interface do usuário. Ao definir uma variável na interface do usuário, você pode criptografar a variável e defini-la 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.
Para definir variáveis em um arquivo para uso em vários pipelines, use templates.
Variáveis de várias linhas definidas pelo usuário
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.
Azure DevOps não altera valores de variáveis definidos pelo usuário. Você precisa formatar valores variáveis corretamente antes de passá-los como variáveis de várias linhas. Ao formatar sua variável, evite caracteres especiais, não use nomes restritos e certifique-se de usar um formato de final de linha 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 esse problema, certifique-se de formatar variáveis de várias linhas corretamente para o sistema operacional de destino.
Azure DevOps nunca altera valores variáveis, mesmo se você fornecer formatação sem suporte.
Variáveis do sistema
Além das variáveis definidas pelo usuário, 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, consulte variáveis predefinidas para obter uma lista abrangente de variáveis do sistema.
Se você estiver usando pipelines de versão clássica, consulte as variáveis de liberação.
Quando você executa o pipeline, as variáveis do sistema definem seu valor atual. Algumas variáveis são definidas automaticamente. Como um autor de pipeline ou usuário final, você pode alterar 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. Você os injeta em um pipeline de maneiras específicas da 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.
Variáveis definidas pelo sistema e pelo usuário (exceto variáveis secretas) 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.
Há 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 variáveis
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. Esses prefixos são: endpoint, , input, secret, pathe 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. Não use espaços em variáveis. Para ver restrições adicionais, consulte restrições de nomenclatura do Azure Pipelines.
Noções básicas sobre sintaxe de variáveis
Azure Pipelines dá suporte a três maneiras diferentes de fazer referência a variáveis: macro, expressão de modelo e expressão de runtime. Você pode usar cada sintaxe para uma finalidade diferente e cada uma 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 da variável de sintaxe de macro é atualizado. O valor da expressão de modelo não é alterado porque o pipeline processa todas as variáveis de expressão de modelo no tempo de compilação 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)). Use a sintaxe de macro para interpolar valores variáveis em entradas de tarefa e em outras variáveis.
O sistema processa variáveis com sintaxe de macro 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ído, ele permanecerá como $(var).
As variáveis de sintaxe de macro permanecem inalteradas quando não têm valor porque um valor vazio como $() pode significar algo para a tarefa que você está executando e o agente não deve assumir 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ó se expandem 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: $(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
O sistema só expande variáveis de sintaxe de macro para entradas de tarefa dentro de stages, jobs e steps.
Ele não os expande em palavras-chave de pipeline que resolvem em tempo de compilação, como resources, trigger, ou o valor de referência do repositório da etapa checkout (por exemplo, checkout: git://MyProject/MyRepo@$(var) não funciona).
Para parametrizar esses valores, use expressões de modelo (${{ }}) ou parâmetros de runtime .
Este exemplo usa a sintaxe macro com Bash, PowerShell e uma tarefa de script. A sintaxe para chamar uma variável usando a sintaxe de macro é a mesma para os três.
variables:
- name: projectName
value: contoso
steps:
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)
Sintaxe de expressões de template
Use a sintaxe de expressão de modelo para expandir parâmetros de modelo e variáveis (${{ variables.var }}). O sistema processa variáveis de modelo em tempo de compilação e as substitui antes do início do runtime. Use expressões de modelo 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 de expressão em tempo de execução
Use a sintaxe de expressão de tempo de execução para variáveis que se expandem em tempo de execução ($[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 estágios inteiros.
As variáveis de expressão de runtime só se expandem 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 é processado? | Onde ele se expande em uma definição de pipeline? | Como é renderizado quando não é encontrado? |
|---|---|---|---|---|
| macro | $(var) |
tempo de execução antes de uma tarefa ser executada | valor (lado direito) | imprime $(var) |
| expressão de modelo | ${{ variables.var }} |
tempo de compilação | chave ou valor (no lado esquerdo ou no lado 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 da macro se você estiver fornecendo uma cadeia de caracteres segura ou uma variável predefinida entrada para uma tarefa.
Escolha uma expressão de runtime se você estiver trabalhando com condições e [expressões](expressions.md]. 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 com um valor específico ou nenhum valor, use uma expressão de macro.
Normalmente, uma variável de modelo é o padrão a ser usado. Ao utilizar variáveis de template, seu pipeline injeta completamente o valor da variável no pipeline durante a compilação do pipeline. Esta injeção é útil ao tentar debugar pipelines. Você pode baixar os arquivos de log e avaliar o valor totalmente expandido que está sendo inserido. Como a variável é substituída, não aproveite a sintaxe de modelo para valores confidenciais.
Usar IA para identificar problemas de sintaxe variável
Este prompt de exemplo para o Copilot Chat identifica quais tipos de variáveis são usadas em um pipeline e quando as variáveis são resolvidas. Destaque o seu código YAML e, em seguida, digite o seguinte prompt para o Chat do Copilot.
What types of Azure DevOps variables are used in this YAML pipeline? Give specific examples.
When does each variable process in the pipeline?
How will each variable render when not found?
What stages and jobs will the variables be available for?
Personalize seu prompt para adicionar detalhes conforme necessário.
Copilot é alimentado pela IA, portanto, surpresas e erros são possíveis. Para obter mais informações, consulte Copilot perguntas frequentes.
Definir variáveis no pipeline
No caso mais comum, defina as variáveis e use-as no arquivo YAML. Essa abordagem 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.
O exemplo a seguir mostra como definir duas variáveis configuration e platformusá-las posteriormente em etapas. Para usar uma variável em uma instrução YAML, encapsule-a em $(). Você não pode usar variáveis para definir uma repository 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, defina uma variável em vários escopos:
- No nível raiz, para disponibilizá-la para todos os trabalhos no pipeline.
- No nível de etapa, para disponibilizá-lo apenas para uma etapa específica.
- No nível de tarefa, para torná-la disponível apenas para uma tarefa específica.
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 processos 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.
Outra sintaxe é útil quando você deseja usar modelos para variáveis ou grupos de variáveis.
Usando modelos, você pode definir variáveis em um arquivo YAML e incluí-las em outro arquivo YAML.
Grupos de variáveis são um conjunto de variáveis que você pode usar em vários pipelines. Usando grupos de variáveis, você pode gerenciar e organizar variáveis 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
Para saber mais, consulte a reutilização de variável com modelos.
Acesse variáveis através 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 seus segredos para o pipeline.
Observação
Azure Pipelines faz um esforço para mascarar segredos ao registrar dados nos logs de pipeline, assim você pode ver variáveis adicionais e dados mascarados na saída e nos logs, mas não definidos como segredos.
Você precisa definir variáveis secretas na interface das configurações do 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:
- Vá para a página Pipelines, selecione o pipeline apropriado e selecione Edit.
- Encontre as Variáveis para este pipeline.
- Adicione ou atualize a variável.
- Selecione a opção Manter esse valor em segredo para armazenar a variável de maneira criptografada.
- Salvar 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 que tarefas e scripts os utilizem. Tenha cuidado com quem tem acesso para alterar seu pipeline.
Importante
Fazemos um esforço para mascarar segredos para não aparecerem na saída do Azure Pipelines, mas você ainda precisa tomar precauções. Nunca exiba 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.
Nós nunca mascaramos substratos de segredos. Por exemplo, se "abc123" for definido como um segredo, "abc" não será ocultado 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: esta ação tenta acessar a variável secreta como uma variável de ambiente, o que não funciona porque as variáveis secretas não são mapeadas automaticamente para as variáveis de ambiente. -
$env:GLOBAL_MYSECRET: Esta tentativa de acessar a variável secreta por meio de uma variável global também não funciona, pois variáveis secretas não são mapeáveis dessa forma. -
$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 tem 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 variables definição. Este exemplo mostra como usar variáveis secretas $(vmsUser) e $(vmsAdminPass) em uma tarefa de cópia de arquivo Azure.
variables:
VMS_USER: $(vmsUser)
VMS_PASS: $(vmsAdminPass)
pool:
vmImage: 'ubuntu-latest'
steps:
- task: AzureFileCopy@6
inputs:
SourcePath: 'my/path' # Specify the source path
azureSubscription: 'my-subscription' # Azure subscription name
Destination: 'AzureVMs' # Destination type
storage: 'my-storage' # Azure storage account name
resourceGroup: 'my-resource-group' # Resource group name
vmsAdminUserName: $(VMS_USER) # Admin username for the VM
vmsAdminPassword: $(VMS_PASS) # Admin password for the VM
CleanTargetBeforeCopy: false # Do not clean the target before copying
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. O exemplo usa duas variáveis do grupo de variáveis: user e token. A token variável é secreta e é mapeada para a variável $env:MY_MAPPED_TOKEN de ambiente para que você possa referenciá-la 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, os builds de pull requests de forks não podem acessar variáveis secretas associadas ao pipeline. Para obter mais informações, consulte Contributions from forks.
Compartilhar variáveis entre diferentes pipelines
Para compartilhar variáveis em vários pipelines em seu projeto, use a interface 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 usar em etapas subsequentes, tarefas e estágios. No YAML, você pode acessar variáveis em trabalhos e estágios usando dependencies.
Ao referenciar trabalhos de matriz em tarefas downstream, use 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.
- 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 você tenha uma tarefa nomeada MyTask, que define uma variável de saída chamada MyVar.
Saiba mais sobre a sintaxe em Expressões – Dependências.
Usar saídas na mesma tarefa
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 etapa diferente
Para usar a saída de um estágio diferente, use o formato stageDependencies.STAGE.JOB.outputs['TASK.VARIABLE'] para referenciar variáveis. 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 estágios usando uma entrada de arquivo. Para isso, você precisa definir variáveis no segundo estágio no nível de tarefa 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
Liste todas as variáveis no pipeline usando o comando az pipelines variable list. Para começar, consulte Comece com Azure DevOps CLI.
az pipelines variable list [--org]
[--pipeline-id]
[--pipeline-name]
[--project]
Parâmetros
-
org: URL da organização 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 usandogit config. Exemplo:--org https://dev.azure.com/MyOrganizationName/. - pipeline-id: obrigatório se pipeline-name não for fornecido. ID da canalização.
- 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 project. Configure 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 usandogit 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 as etapas posteriores no pipeline consomem. 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 de um script, use o task.setvariablecomando logging. Esse comando atualiza as variáveis de ambiente para trabalhos subsequentes. Trabalhos subsequentes podem acessar a nova variável usando a sintaxe de macro e em tarefas como variáveis de ambiente.
Quando você define issecret como true, o valor da variável é salvo como segredo e mascarado do log. Para obter mais informações sobre variáveis secretas, consulte comandos de 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)
As etapas subsequentes também têm a variável de pipeline adicionada ao ambiente. 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 access estágios adicionais, você precisará alterar o grafo de dependência, por exemplo, se o estágio 3 exigir uma variável do estágio 1, você precisará declarar uma dependência explícita no estágio 1.
Ao criar uma variável de saída para múltiplos 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 matrix ou slice, para referenciar a variável ao acessá-la a partir de um trabalho downstream, deverá incluir:
- O nome da tarefa.
- 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 nas 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 as variáveis 
Definir as variáveis 
Definir as variáveis Definir variáveis usando expressões
Você pode definir uma variável usando uma expressão. Você já encontrou um caso dessa abordagem ao definir uma variável para a saída de outra variável 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
No exemplo a seguir, o script pode definir a variável sauce , mas não pode definir a variável secretSauce. Você verá um aviso na página de execução do pipeline.
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 no tempo de fila
Se uma variável aparecer no bloco variables de um arquivo YAML, seu valor será fixo e os usuários não poderão substituí-la durante o enfileiramento. Defina suas variáveis em um arquivo YAML, mas há momentos em que essa abordagem não faz sentido. Por exemplo, talvez você queira definir uma variável secreta e não expô-la 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 quando executarem esse pipeline ou você pode usar parâmetros de tempo de execução. Se a variável não for um segredo, a melhor prática será usar parâmetros de runtime.
Para definir uma variável durante o tempo de fila, adicione uma nova variável no pipeline e selecione a opção de substituição. Somente os usuários com a permissão Editar configuração de build da fila podem alterar o valor de uma variável.
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.
Para aumentar a segurança, use um conjunto predefinido de valores para variáveis configuráveis durante o tempo de fila e tipos seguros, como booleanos e inteiros. Para cadeias de caracteres, use um conjunto predefinido de valores.
Expansão de variáveis
Quando você define uma variável com o mesmo nome em vários escopos, a seguinte precedência se aplica (precedência mais alta primeiro):
- Variável no nível de trabalho definida no arquivo YAML
- Variável no nível de fase definida no arquivo YAML
- Variável de nível de pipeline definida no arquivo YAML
- Variável configurada no momento da fila
- Variáveis de pipeline definidas na interface do usuário das configurações do 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 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"