Numéros d’exécution et de build

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

Cet article explique comment les numéros de build et d’exécution Azure Pipelines sont construits, et comment vous pouvez les personnaliser dans vos pipelines.

Le numéro d’exécution est utilisé pour identifier une exécution spécifique d’un pipeline ou d’un build. Le numéro de build est synonyme du numéro d’exécution.

Si vous ne spécifiez pas de nom de build dans les pipelines YAML, ou si vous laissez le champ Name vide dans les pipelines Classiques, votre exécution obtient un entier unique comme nom. Vous pouvez donner aux exécutions des noms plus utiles, qui sont significatifs pour votre équipe. Vous pouvez utiliser une combinaison de jetons, de variables et de caractères de soulignement dans les noms de build.

Dans les pipelines YAML, la propriété de nom de build est appelée name et doit être au niveau racine d’un pipeline. Les éléments spécifiés au niveau racine d’un fichier YAML sont des propriétés de pipeline.

Remarque

La propriété name ne fonctionne pas dans les fichiers de modèle.

Le code d’exemple suivant produit un numéro de build personnalisé comme project_def_master_202408281.

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

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

Nombre d’exécutions

La valeur par défaut pour un numéro d’exécution dans Azure Pipelines est $(Date:yyyyMMdd).$(Rev:r). $(Rev:r) est un format de variable spéciale qui ne fonctionne que dans le champ de numéro de build. Lorsqu’un build se termine, si rien d’autre dans le numéro de build n’a changé, la valeur entière Rev augmente de un.

$(Rev:r) est réinitialisé à 1 lorsque toute autre partie du numéro de build change. Par exemple, si vous configurez votre format de numéro de build en $(Build.DefinitionName)_$(Date:yyyyMMdd).$(Rev:r), le numéro de build est réinitialisé lorsque la date change.

Si le numéro de build précédent était MyBuild_20230621.1, le prochain numéro de build ce jour-là est MyBuild_20230621.2. Le premier numéro de build le lendemain est MyBuild_20230622.1.

$(Rev:r) est également réinitialisé à 1 si vous changez le numéro de build pour indiquer un changement de version. Par exemple, si votre format de build est 1.0.$(Rev:r) et que votre dernier numéro de build était 1.0.3, si vous changez le numéro de build en 1.1.$(Rev:r), le prochain numéro de build sera 1.1.1.

Exemple

Considérez les données suivantes pour une exécution de build :

• Nom du projet : Fabrikam
• Nom du pipeline : CIBuild
• Branche : main
• ID de build/ID d’exécution : 752
• Date : 6 mai 2024
• Heure : 21h07m03s
• Une seule exécution s’est terminée plus tôt dans la journée.

Si vous spécifiez le format de numéro de build suivant, la deuxième exécution du 6 mai 2024 est nommée Fabrikam_CIBuild_main_20240506.2.

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

Jetons

Le tableau suivant montre comment chaque jeton se résout, basé sur l’exemple précédent. Vous pouvez utiliser ces jetons uniquement pour définir des numéros d’exécution. Ils ne fonctionnent nulle part ailleurs dans un pipeline.

par jeton	Valeur d’exemple	Notes
$(Build.DefinitionName)	CIBuild	Le nom du pipeline ne peut pas contenir de caractères non valides ou d’espaces blancs.
$(Build.BuildId)	752	$(Build.BuildId) est un identifiant interne immuable, également appelé Run ID, qui est unique dans l’organisation Azure DevOps.
$(DayOfMonth)	6
$(DayOfYear)	126
$(Hours)	21
$(Minutes)	7
$(Month)	5
$(Rev:r)	2	La troisième exécution quotidienne est 3, et ainsi de suite. Utilisez $(Rev:r) pour vous assurer que chaque build terminé possède un nom unique.
$(Date:yyyyMMdd)	20240506	Vous pouvez spécifier d’autres formats de date tels que $(Date:MMddyy).
$(Seconds)	3
$(SourceBranchName)	main
$(TeamProject)	Fabrikam
$(Year:yy)	24
$(Year:yyyy)	2024

Important

Si vous souhaitez afficher des zéros de préfixe dans le numéro d’exécution, vous pouvez ajouter plus de caractères r au jeton Rev. Par exemple, spécifiez $(Rev:rr) si vous voulez que le numéro Rev commence par 01, 02, et ainsi de suite.

Si vous utilisez un Rev avec remplissage de zéros dans le cadre d’un schéma de numérotation de version, sachez que certaines tâches de pipeline ou des outils populaires, comme les packages NuGet, suppriment les zéros en tête. Ce comportement provoque une incompatibilité de numéro de version dans les artefacts produits.

Expressions

Si vous utilisez une expression pour définir le numéro de build, vous ne pouvez pas utiliser certains jetons, car leurs valeurs ne sont pas définies au moment de l’évaluation des expressions. Ces jetons incluent $(Build.BuildId), $(Build.BuildURL) et $(Build.BuildNumber).

Variables

Vous pouvez utiliser des variables définies par l’utilisateur et des variables prédéfinies dans votre numéro de build. Par exemple, si vous définissez My.Variable, vous pouvez spécifier le format de numéro suivant :

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

Dans l’exemple précédent, les quatre premières variables sont prédéfinies. Pour obtenir des informations sur la définition des variables utilisateur, veuillez consulter la section Définir des variables dans les pipelines.

Forum aux questions

Quelle est la longueur maximale d’un numéro d’exécution et quels caractères puis-je utiliser ?

Les numéros d’exécution peuvent comporter jusqu’à 255 caractères. Vous ne pouvez pas utiliser les caractères ", /, :, <, >, ', |, ?, @, ou *, et vous ne pouvez pas terminer le numéro par ..

Dans quel fuseau horaire sont exprimées les valeurs de temps du numéro de build ?

Le fuseau horaire est UTC.

Comment puis-je définir dynamiquement le numéro de build avec des conditions ?

Vous pouvez utiliser des variables dans le cadre de votre numéro d’exécution. Dans l’exemple suivant, la variable why est utilisée comme partie du numéro d’exécution, et sa valeur change en fonction de 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)'

Comment puis-je référencer la variable de numéro d’exécution dans un script ?

Vous pouvez définir une nouvelle variable qui inclut le numéro d’exécution, ou appeler directement le numéro d’exécution. Dans l’exemple suivant, $(MyRunNumber) est une nouvelle variable qui inclut le numéro d’exécution. Vous pouvez appeler la variable du numéro d’exécution en utilisant MyRunNumber ou $(Build.BuildNumber).

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

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

Contenu connexe

Définir des variables