Variáveis de versão e artefactos clássicos

  • Artigo

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

As variáveis clássicas de liberação e artefatos são uma maneira conveniente de trocar e transportar dados em todo o seu pipeline. Cada variável é armazenada como uma cadeia de carateres e o seu valor pode ser alterado entre execuções do pipeline.

As variáveis são diferentes dos parâmetros de tempo de execução que só estão disponíveis no momento da análise do modelo.

À medida que você compõe as tarefas para implantar seu aplicativo em cada estágio em seus processos de CI/CD de DevOps, as variáveis ajudarão você a:

  • Defina um pipeline de implantação mais genérico uma vez e, em seguida, personalize-o facilmente para cada estágio. Por exemplo, uma variável pode ser usada para representar a cadeia de conexão para implantação na Web, e o valor dessa variável pode ser alterado de um estágio para outro. Estas são variáveis personalizadas.

  • Use informações sobre o contexto da versão, estágio, artefatos ou agente específico no qual o pipeline de implantação está sendo executado. Por exemplo, seu script pode precisar de acesso ao local da compilação para baixá-lo ou ao diretório de trabalho no agente para criar arquivos temporários. Estas são variáveis padrão.

Nota

Para pipelines YAML, consulte variáveis definidas pelo usuário e variáveis predefinidas para obter mais detalhes.

Variáveis predefinidas

As informações sobre o contexto de execução são disponibilizadas para tarefas em execução por meio de variáveis padrão. Suas tarefas e scripts podem usar essas variáveis para encontrar informações sobre o sistema, a versão, o estágio ou o agente em que estão sendo executados. Com exceção de System.Debug, essas variáveis são somente leitura e seus valores são definidos automaticamente pelo sistema. Algumas das variáveis mais significativas são descritas nas tabelas a seguir. Para exibir a lista completa, consulte Exibir os valores atuais de todas as variáveis.

Gorjeta

Você pode exibir os valores atuais de todas as variáveis de uma versão e usar uma variável padrão para executar uma versão no modo de depuração.

Sistema

Nome da variável Description
System.TeamFoundationServerUri A URL da conexão de serviço no Azure Pipelines. Use isso de seus scripts ou tarefas para chamar APIs REST do Azure Pipelines.

Exemplo: https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri A URL da coleção Team Foundation ou Azure Pipelines. Use isso de seus scripts ou tarefas para chamar APIs REST em outros serviços, como controle de compilação e versão.

Exemplo: https://dev.azure.com/fabrikam/
System.CollectionId A ID da coleção à qual esta compilação ou versão pertence.

Exemplo: 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId A ID do pipeline de liberação ao qual a versão atual pertence.

Exemplo: 1
System.TeamProject O nome do projeto ao qual esta compilação ou versão pertence.

Exemplo: Fabrikam
System.TeamProjectId A ID do projeto ao qual esta compilação ou versão pertence.

Exemplo: 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory O diretório para o qual os artefatos são baixados durante a implantação de uma versão. O diretório é limpo antes de cada implantação se exigir que os artefatos sejam baixados para o agente. O mesmo que Agent.ReleaseDirectory e System.DefaultWorkingDirectory.

Exemplo: C:\agent\_work\r1\a
System.DefaultWorkingDirectory O diretório para o qual os artefatos são baixados durante a implantação de uma versão. O diretório é limpo antes de cada implantação se exigir que os artefatos sejam baixados para o agente. O mesmo que Agent.ReleaseDirectory e System.ArtifactsDirectory.

Exemplo: C:\agent\_work\r1\a
System.WorkFolder O diretório de trabalho para este agente, onde subpastas são criadas para cada compilação ou versão. O mesmo que Agent.RootDirectory e Agent.WorkFolder.

Exemplo: C:\agent\_work
System.Debug Esta é a única variável de sistema que pode ser definida pelos usuários. Defina isso como true para executar a versão no modo de depuração para ajudar na localização de falhas.

Exemplo: true

Versão

Nome da variável Description
Release.AttemptNumber O número de vezes que esta versão é implantada neste estágio.

Exemplo: 1
Release.DefinitionEnvironmentId A ID do estágio no pipeline de liberação correspondente.

Exemplo: 1
Release.DefinitionId A ID do pipeline de liberação ao qual a versão atual pertence.

Exemplo: 1
Release.DefinitionName O nome do pipeline de liberação ao qual a versão atual pertence.

Exemplo: fabrikam-cd
Release.Deployment.RequestedFor O nome para exibição da identidade que disparou (iniciou) a implantação atualmente em andamento.

Exemplo: Mateo Escobedo
Release.Deployment.RequestedForEmail O endereço de e-mail da identidade que acionou (iniciou) a implantação atualmente em andamento.

Exemplo: mateo@fabrikam.com
Release.Deployment.RequestedForId A ID da identidade que disparou (iniciou) a implantação atualmente em andamento.

Exemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID A ID da implantação. Único por trabalho.

Exemplo: 254
Release.DeployPhaseID A ID da fase em que a implantação está sendo executada.

Exemplo: 127
Release.EnvironmentId A ID da instância do estágio em uma versão para a qual a implantação está atualmente em andamento.

Exemplo: 276
Release.EnvironmentName O nome do estágio para o qual a implantação está atualmente em andamento.

Exemplo: Dev
Release.EnvironmentUri O URI da instância do estágio em uma versão para a qual a implantação está atualmente em andamento.

Exemplo: vstfs://ReleaseManagement/Environment/276
Release.Environments. {nome do estágio}.status O status de implantação do estágio.

Exemplo: InProgress
Release.PrimaryArtifactSourceAlias O alias da origem do artefato primário

Exemplo: fabrikam\_web
Release.Reason O motivo da implantação. Os valores suportados são:
ContinuousIntegration - a versão iniciada em Continuous Deployment após a conclusão de uma compilação.
Manual - A liberação foi iniciada manualmente.
None - O motivo da implantação não foi especificado.
Schedule - O lançamento começou a partir de um cronograma.
Release.ReleaseDescription A descrição do texto fornecida no momento do lançamento.

Exemplo: Critical security patch
Release.ReleaseId O identificador do registro de lançamento atual.

Exemplo: 118
Release.ReleaseName O nome da versão atual.

Exemplo: Release-47
Release.ReleaseUri O URI da versão atual.

Exemplo: vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL O URL desta versão.

Exemplo: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor O nome de exibição da identidade que disparou a versão.

Exemplo: Mateo Escobedo
Release.RequestedForEmail O endereço de e-mail da identidade que acionou a liberação.

Exemplo: mateo@fabrikam.com
Release.RequestedForId A ID da identidade que disparou a liberação.

Exemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsBaixar Valor booleano que especifica se o download de artefatos para o agente deve ou não ser ignorado.

Exemplo: FALSE
Release.TriggeringArtifact.Alias O pseudônimo do artefato que desencadeou a liberação. Isso fica vazio quando a liberação foi agendada ou acionada manualmente.

Exemplo: fabrikam\_app

Fase de libertação

Nome da variável Description
Release.Environments. {nome artístico}. Situação O status de implantação desta versão dentro de um estágio especificado.

Exemplo: NotStarted

Agente

Nome da variável Description
Agent.Name O nome do agente conforme registrado no pool de agentes. É provável que isso seja diferente do nome do computador.

Exemplo: fabrikam-agent
Agent.MachineName O nome do computador no qual o agente está configurado.

Exemplo: fabrikam-agent
Agent.Version A versão do software do agente.

Exemplo: 2.109.1
Agent.JobName O nome do trabalho que está sendo executado, como Release ou Build.

Exemplo: Release
Agent.HomeDirectory A pasta onde o agente está instalado. Esta pasta contém o código e os recursos para o agente.

Exemplo: C:\agent
Agent.ReleaseDirectory O diretório para o qual os artefatos são baixados durante a implantação de uma versão. O diretório é limpo antes de cada implantação se exigir que os artefatos sejam baixados para o agente. O mesmo que System.ArtifactsDirectory e System.DefaultWorkingDirectory.

Exemplo: C:\agent\_work\r1\a
Agent.RootDirectory O diretório de trabalho para este agente, onde subpastas são criadas para cada compilação ou versão. O mesmo que Agent.WorkFolder e System.WorkFolder.

Exemplo: C:\agent\_work
Agent.WorkFolder O diretório de trabalho para este agente, onde subpastas são criadas para cada compilação ou versão. O mesmo que Agent.RootDirectory e System.WorkFolder.

Exemplo: C:\agent\_work
Agent.DeploymentGroupId A ID do grupo de implantação no qual o agente está registrado. Isso está disponível apenas em trabalhos de grupo de implantação.

Exemplo: 1

Artefato Geral

Para cada artefato referenciado em uma versão, você pode usar as seguintes variáveis de artefato. Nem todas as variáveis são significativas para cada tipo de artefato. A tabela abaixo lista as variáveis de artefato padrão e fornece exemplos dos valores que elas têm, dependendo do tipo de artefato. Se um exemplo estiver vazio, isso implica que a variável não está preenchida para esse tipo de artefato.

Substitua o espaço reservado {alias} pelo valor especificado para o alias de artefato ou pelo valor padrão gerado para o pipeline de liberação.

Nome da variável Description
Release.Artifacts. {alias}. DefinitionId O identificador do pipeline ou repositório de compilação.

Exemplo de Pipelines do Azure: 1
Exemplo do GitHub: fabrikam/asp
Release.Artifacts. {alias}. DefinitionName O nome do pipeline ou repositório de compilação.

Exemplo de Pipelines do Azure: fabrikam-ci
Exemplo de CVF: $/fabrikam
Exemplo do Git: fabrikam
Exemplo do GitHub: fabrikam/asp (main)
Release.Artifacts. {alias}. Número de compilação O número de compilação ou o identificador de confirmação.

Exemplo de Pipelines do Azure: 20170112.1
Exemplo de Jenkins/TeamCity: 20170112.1
Exemplo de CVF: Changeset 3
Exemplo do Git: 38629c964
Exemplo do GitHub: 38629c964
Release.Artifacts. {alias}. BuildId O identificador de compilação.

Exemplo de Pipelines do Azure: 130
Exemplo de Jenkins/TeamCity: 130
Exemplo do GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts. {alias}. BuildURI A URL para a compilação.

Exemplo de Pipelines do Azure: vstfs://build-release/Build/130
Exemplo do GitHub: https://github.com/fabrikam/asp
Release.Artifacts. {alias}. SourceBranch O caminho completo e o nome da ramificação a partir da qual a fonte foi construída.

Exemplo de Pipelines do Azure: refs/heads/main
Release.Artifacts. {alias}. SourceBranchName O nome apenas da ramificação a partir da qual a fonte foi construída.

Exemplo de Pipelines do Azure: main
Release.Artifacts. {alias}. FonteVersão O compromisso que foi construído.

Exemplo de Pipelines do Azure: bc0044458ba1d9298cdc649cb5dcf013180706f7
Release.Artifacts. {alias}. Repositório.Provedor O tipo de repositório a partir do qual a fonte foi construída.

Exemplo de Pipelines do Azure: Git
Release.Artifacts. {alias}. RequestedForID O identificador da conta que disparou a compilação.

Exemplo de Pipelines do Azure: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.Artifacts. {alias}. SolicitadoPara O nome da conta que solicitou a compilação.

Exemplo de Pipelines do Azure: Mateo Escobedo
Release.Artifacts. {alias}. Tipo O tipo de origem de artefato, como Build.

Exemplo de Pipelines do Azure: Build
Exemplo de Jenkins: Jenkins
Exemplo de TeamCity: TeamCity
Exemplo de CVF: TFVC
Exemplo do Git: Git
Exemplo do GitHub: GitHub
Release.Artifacts. {alias}. PullRequest.TargetBranch O caminho completo e o nome da ramificação que é o destino de uma solicitação pull. Essa variável é inicializada somente se a liberação for acionada por um fluxo de solicitação pull.

Exemplo de Pipelines do Azure: refs/heads/main
Release.Artifacts. {alias}. PullRequest.TargetBranchName O nome somente da ramificação que é o destino de uma solicitação pull. Essa variável é inicializada somente se a liberação for acionada por um fluxo de solicitação pull.

Exemplo de Pipelines do Azure: main

Consulte também Alias de origem do artefato

Artefato primário

Você designa um dos artefatos como um artefato primário em um pipeline de liberação. Para o artefato primário designado, o Azure Pipelines preenche as seguintes variáveis.

Nome da variável O mesmo que
Build.DefinitionId Release.Artifacts. {Alias de artefato primário}. DefinitionId
Build.DefinitionName Release.Artifacts. {Alias de artefato primário}. DefinitionName
Build.BuildNumber Release.Artifacts. {Alias de artefato primário}. Número de compilação
Build.BuildId Release.Artifacts. {Alias de artefato primário}. BuildId
Build.BuildURI Release.Artifacts. {Alias de artefato primário}. BuildURI
Build.SourceBranch Release.Artifacts. {Alias de artefato primário}. SourceBranch
Build.SourceBranchName Release.Artifacts. {Alias de artefato primário}. SourceBranchName
Build.SourceVersion Release.Artifacts. {Alias de artefato primário}. FonteVersão
Build.Repository.Provider Release.Artifacts. {Alias de artefato primário}. Repositório.Provedor
Build.RequestedForID Release.Artifacts. {Alias de artefato primário}. RequestedForID
Build.RequestedFor Release.Artifacts. {Alias de artefato primário}. SolicitadoPara
Build.Type Release.Artifacts. {Alias de artefato primário}. Tipo
Build.PullRequest.TargetBranch Release.Artifacts. {Alias de artefato primário}. PullRequest.TargetBranch
Build.PullRequest.TargetBranchName Release.Artifacts. {Alias de artefato primário}. PullRequest.TargetBranchName

Usar variáveis padrão

Você pode usar as variáveis padrão de duas maneiras - como parâmetros para tarefas em um pipeline de liberação ou em seus scripts.

Você pode usar diretamente uma variável padrão como entrada para uma tarefa. Por exemplo, para passar Release.Artifacts.{Artifact alias}.DefinitionName para a fonte do artefato cujo alias é ASPNET4.CI a uma tarefa, você usaria $(Release.Artifacts.ASPNET4.CI.DefinitionName).

Usando variáveis de artefato em argumentos para uma tarefa de Script do PowerShell

Para usar uma variável padrão em seu script, você deve primeiro substituir o . nos nomes de variáveis padrão por _. Por exemplo, para imprimir o valor da variável de artefato para a fonte Release.Artifacts.{Artifact alias}.DefinitionName de artefato cujo alias é ASPNET4.CI em um script do PowerShell, você usaria $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME.

Usando variáveis de artefato em um script PowerShell embutido

Observe que o nome original do alias de origem do artefato, ASPNET4.CI, é substituído por ASPNET4_CI.

Exibir os valores atuais de todas as variáveis

  1. Abra a visualização de pipelines do resumo da versão e escolha o estágio em que você está interessado. Na lista de etapas, escolha Inicializar trabalho.

    Abrindo o log para uma versão

  2. Isso abre o log para esta etapa. Role para baixo para ver os valores usados pelo agente para este trabalho.

    Visualizando os valores das variáveis em uma versão

Executar uma versão no modo de depuração

Mostrar informações adicionais à medida que uma versão é executada e nos arquivos de log executando a versão inteira, ou apenas as tarefas em um estágio de liberação individual, no modo de depuração. Isso pode ajudá-lo a resolver problemas e falhas.

  • Para iniciar o modo de depuração para uma versão inteira, adicione uma variável nomeada System.Debug com o valor true à guia Variáveis de um pipeline de versão.

  • Para iniciar o modo de depuração para um único estágio, abra a caixa de diálogo Configurar estágio no menu de atalho do estágio e adicione uma variável nomeada System.Debug com o valor true à guia Variáveis .

  • Como alternativa, crie um grupo de variáveis contendo uma variável nomeada System.Debug com o valor true e vincule esse grupo de variáveis a um pipeline de liberação.

Gorjeta

Se você receber um erro relacionado a uma conexão de serviço do Azure RM, consulte Como solucionar problemas de conexões de serviço do Azure Resource Manager.

Variáveis personalizadas

As variáveis personalizadas podem ser definidas em vários escopos.

  • Compartilhe valores em todas as definições em um projeto usando grupos de variáveis. Escolha um grupo de variáveis quando precisar usar os mesmos valores em todas as definições, estágios e tarefas em um projeto e quiser poder alterar os valores em um único local. Você define e gerencia grupos de variáveis na guia Biblioteca .

  • Compartilhe valores em todos os estágios usando variáveis de pipeline de liberação. Escolha uma variável de pipeline de liberação quando precisar usar o mesmo valor em todos os estágios e tarefas no pipeline de liberação e quiser poder alterar o valor em um único local. Você define e gerencia essas variáveis na guia Variáveis em um pipeline de versão. Na página Variáveis de pipeline, abra a lista suspensa Escopo e selecione "Liberar". Por padrão, quando você adiciona uma variável, ela é definida como Escopo da versão.

  • Compartilhe valores em todas as tarefas dentro de um estágio específico usando variáveis de estágio. Use uma variável de nível de estágio para valores que variam de estágio para estágio (e são os mesmos para todas as tarefas em um estágio). Você define e gerencia essas variáveis na guia Variáveis de um pipeline de versão. Na página Variáveis de pipeline, abra a lista suspensa Escopo e selecione o estágio necessário. Ao adicionar uma variável, defina o Escopo para o ambiente apropriado.

O uso de variáveis personalizadas no projeto, no pipeline de liberação e no escopo do estágio ajuda você a:

  • Evite a duplicação de valores, facilitando a atualização de todas as ocorrências como uma única operação.

  • Armazene valores confidenciais de uma forma que eles não possam ser vistos ou alterados pelos usuários dos pipelines de liberação. Designe uma propriedade de configuração para ser uma variável segura (secreta) selecionando o cadeado ícone (cadeado) ao lado da variável.

    Importante

    Os valores das variáveis ocultas (secretas) são armazenados com segurança no servidor e não podem ser visualizados pelos usuários depois de serem salvos. Durante uma implantação, o serviço de liberação do Azure Pipelines descriptografa esses valores quando referenciados pelas tarefas e os passa para o agente por meio de um canal HTTPS seguro.

Nota

A criação de variáveis personalizadas pode substituir variáveis padrão. Por exemplo, a variável de ambiente Caminho do PowerShell. Se você criar uma variável personalizada Path em um agente do Windows, ela substituirá a variável e o $env:Path PowerShell não poderá ser executado.

Usar variáveis personalizadas

Para usar variáveis personalizadas em suas tarefas de compilação e lançamento, basta colocar o nome da variável entre parênteses e precedê-la com um $ caractere. Por exemplo, se você tiver uma variável chamada adminUserName, poderá inserir o valor atual dessa variável em um parâmetro de uma tarefa como $(adminUserName).

Nota

Variáveis em diferentes grupos que estão ligadas a um pipeline no mesmo escopo (por exemplo, trabalho ou estágio) colidirão e o resultado pode ser imprevisível. Certifique-se de usar nomes diferentes para variáveis em todos os seus grupos de variáveis.

Definir e modificar suas variáveis em um script

Para definir ou modificar uma variável a partir de um script, use o task.setvariable comando log. Observe que o valor da variável atualizada tem como escopo o trabalho que está sendo executado e não flui entre trabalhos ou estágios. Os nomes das variáveis são transformados em maiúsculas e os caracteres "." e " " são substituídos por "_".

Por exemplo, Agent.WorkFolder passa a AGENT_WORKFOLDER. No Windows, você acessa isso como %AGENT_WORKFOLDER% ou $env:AGENT_WORKFOLDER. No Linux e macOS, você usa $AGENT_WORKFOLDERo .

Gorjeta

Você pode executar um script em:

Script em lote

Definir as sauce variáveis e secret.Sauce

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic

Leia as variáveis

Argumentos

"$(sauce)" "$(secret.Sauce)"

Script

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil
     the secret)

Saída do console a partir da leitura das variáveis:

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)