Executar e criar números

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

Este artigo explica como os Pipelines do Azure criam números e números de execução são construídos e como você pode personalizá-los em seus pipelines.

O número de execução é usado para identificar uma execução específica de um pipeline ou compilação. O número de compilação é sinônimo de número de execução.

Se você não especificar um nome de compilação em pipelines YAML ou deixar o campo Nome em branco em pipelines clássicos, sua execução obterá um inteiro exclusivo como nome. Você pode dar aos execuções nomes mais úteis que sejam significativos para sua equipe. Você pode usar uma combinação de tokens, variáveis e caracteres de sublinhado em nomes de compilação.

Em pipelines YAML, a propriedade build name é chamada name e deve estar no nível raiz de um pipeline. Os itens especificados no nível raiz de um arquivo YAML são propriedades de pipeline.

Observação

A propriedade name não funciona em arquivos de modelo.

O código de exemplo a seguir gera um número de compilação personalizado como project_def_master_20240828.1.

name: $(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:r)

steps:
  - script: echo '$(Build.BuildNumber)'

Número de execução

O valor padrão para um número de execução no Azure Pipelines é $(Date:yyyyMMdd).$(Rev:r). $(Rev:r) é um formato de variável especial que só funciona no campo de número de compilação. Quando uma compilação é concluída, se nada mais no número de compilação for alterado, o Rev valor inteiro aumentará em um.

$(Rev:r) Redefine para 1 quando qualquer outra parte do número de compilação é alterada. Por exemplo, se você configurar o formato de número de compilação como $(Build.DefinitionName)_$(Date:yyyyMMdd).$(Rev:r), o número de compilação será redefinido quando a data for alterada.

Se o número de compilação anterior era MyBuild_20230621.1, o próximo número de compilação naquele dia é MyBuild_20230621.2. O primeiro número de compilação no dia seguinte é MyBuild_20230622.1.

$(Rev:r) também redefine para 1 se você alterar o número de compilação para indicar uma alteração de versão. Por exemplo, se o formato de compilação for 1.0.$(Rev:r) e seu último número de compilação for 1.0.3, se você alterar o número de compilação para 1.1.$(Rev:r), o próximo número de compilação será 1.1.1.

Exemplo

Considere os seguintes dados para uma execução de compilação:

• Nome do projeto: Fabrikam
• Nome do pipeline: CIBuild
• Branch: principal
• ID de build/ID de execução: 752
• Data: 6 de maio de 2024
• Horário: 21:07:03
• Uma execução concluída hoje cedo.

Se você especificar o seguinte formato de número de compilação, a segunda execução em 6 de maio de 2024 será denominada Fabrikam_CIBuild_main_20240506.2.

$(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:.r)

Tokens

A tabela a seguir mostra como cada token é resolvido, com base no exemplo anterior. Você pode usar esses tokens apenas para definir números de execução. Eles não funcionam em nenhum outro lugar em um pipeline.

Token	Valor de exemplo	Observações
$(Build.DefinitionName)	CIBuild	O nome do pipeline não pode conter caracteres inválidos ou de espaço em branco.
$(Build.BuildId)	752	$(Build.BuildId) é uma ID interna e imutável, também chamada de ID de Execução, que é exclusiva em toda a organização de DevOps do Azure.
$(DayOfMonth)	6
$(DayOfYear)	126
$(Hours)	21
$(Minutes)	7
$(Month)	5
$(Rev:r)	2	A terceira corrida diária é 3, e assim por diante. Use $(Rev:r) para garantir que cada compilação concluída tenha um nome exclusivo.
$(Date:yyyyMMdd)	20240506	Você pode especificar outros formatos de data, como $(Date:MMddyy).
$(Seconds)	3
$(SourceBranchName)	main
$(TeamProject)	Fabrikam
$(Year:yy)	24
$(Year:yyyy)	2024

Importante

Se você quiser mostrar zeros de prefixo no número de execução, poderá adicionar mais r caracteres ao Rev token. Por exemplo, especifique $(Rev:rr) se você deseja que o Rev número comece com 01, 02e assim por diante.

Se você usar um zero-acolchoado Rev como parte de um esquema de numeração de versão, esteja ciente de que algumas tarefas de pipeline ou ferramentas populares, como pacotes NuGet, removem os zeros à esquerda. Esse comportamento faz com que uma incompatibilidade de número de versão nos artefatos que são produzidos.

Expressões

Se você usar uma expressão para definir o número de compilação, não poderá usar alguns tokens, porque seus valores não são definidos no momento em que as expressões são avaliadas. Esses tokens incluem $(Build.BuildId), $(Build.BuildURL) e $(Build.BuildNumber).

Variáveis

Você pode usar variáveis definidas pelo usuário e predefinidas em seu número de compilação. Por exemplo, se você definir My.Variable, poderá especificar o seguinte formato de número:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable)

No exemplo anterior, as quatro primeiras variáveis são predefinidas. Para obter informações sobre como definir variáveis de usuário, consulte Definir variáveis em pipelines.

Perguntas frequentes

Qual pode ser o tamanho de um número de execução e quais caracteres posso usar?

Os números de execução podem ter até 255 caracteres. Não é possível usar os caracteres , , , , , , , |, ?, , *@ou , e não é possível terminar o número com ..'><:/"

Em que fuso horário os valores de hora do número de compilação são expressos?

O fuso horário é UTC.

Como posso definir o número de build dinamicamente com condições?

Você pode usar variáveis como parte do número de execução. No exemplo a seguir, a variável why é usada como parte do número de execução e seu valor muda dependendo do Build.Reason.

variables:
  - name: why
    ${{ if eq(variables['Build.Reason'], 'PullRequest') }}:
      value: pr
    ${{ elseif eq(variables['Build.Reason'], 'Manual' ) }}:
      value: manual
    ${{ elseif eq(variables['Build.Reason'], 'IndividualCI' ) }}:
      value: indivci
    ${{ else }}:
      value: other

name: $(TeamProject)_$(SourceBranchName)_$(why)_$(Date:yyyyMMdd).$(Rev:.r)

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo '$(Build.BuildNumber)'

Como posso fazer referência à variável de número de execução dentro de um script?

Você pode definir uma nova variável que inclua o número de execução ou chamar o número de execução diretamente. No exemplo a seguir, $(MyRunNumber) é uma nova variável que inclui o número de execução. Você pode chamar a variável de número de execução usando MyRunNumber ou $(Build.BuildNumber).

# Set MyRunNumber
variables: 
  MyRunNumber: '1.0.0-CI+$(Build.BuildNumber)'

steps:
- script: echo $(MyRunNumber)
- script: echo $(Build.BuildNumber)

Conteúdo relacionado

Definir variáveis