Números de execução e compilação

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

Este artigo explica como os números de execução e os números de compilação do Azure Pipelines 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 do 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 seu nome. Você pode dar a execuções nomes mais úteis que são 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 de nome de compilação é chamada de 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_202408281.

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 funciona apenas no campo número de compilação. Quando uma compilação é concluída, se nada mais no número de compilação tiver sido alterado, o valor inteiro Rev aumentará em um.

$(Rev:r) redefine para 1 quando qualquer outra parte do número de compilação é alterada. Por exemplo, se você tiver configurado 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 for MyBuild_20230621.1, o próximo número de compilação nesse dia será MyBuild_20230621.2. No dia seguinte, o número de compilação será MyBuild_20230622.1.

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

Exemplo

Considere os seguintes dados para a execução de uma 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
  • Hora: 21h07min03
  • Uma execução concluída hoje cedo.

Se você especificar o formato de número de compilação a seguir, a segunda execução em 6 de maio de 2024 será chamada de 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 de espaço em branco ou inválidos.
$(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 do Azure DevOps.
$(DayOfMonth) 6
$(DayOfYear) 126
$(Hours) 21
$(Minutes) 7
$(Month) 5
$(Rev:r) 2 A terceira execução 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, você pode adicionar mais caracteres r ao token Rev. Por exemplo, especifique $(Rev:rr) se você deseja que o número Rev comece com 01, 02, e assim por diante.

Se você usar um preenchimento de zero 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 causa uma incompatibilidade de número de versão nos artefatos produzidos.

Expressões

Se você usar uma expressão para definir o número de build, 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ê tiver definido 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 é 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. Você não pode usar os caracteres ", /, :, <, >, ', |, ?, @, ou *, e não pode terminar o número com ..

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

O fuso horário é UTC.

O fuso horário é o mesmo que o fuso horário do sistema operacional do computador que está executando o servidor da camada de aplicação.

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 eu posso referenciar a variável de número de execução em um script?

Você pode definir uma nova variável que inclui 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)

Definir variáveis