Options de pipeline pour les dépôts Git

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

Lors de la modification d’un pipeline qui utilise un dépôt Git (dans un projet Azure DevOps, GitHub, GitHub Enterprise Server, Bitbucket Cloud ou un autre dépôt Git), vous disposez des options suivantes.

Fonctionnalité	Azure Pipelines	Azure DevOps Server 2019 et versions ultérieures	TFS 2018
Branche	Oui	Oui	Oui
Clean	Oui	Oui	Oui
Sources d’étiquettes	Projet ; Classique uniquement	Projet d'équipe	Projet d'équipe
Rapport sur l’état de la build	Oui	Oui	Oui
Extraire les sous-modules	Oui	Oui	Oui
Extraire les fichiers de LFS	Oui	Oui	Oui
Cloner un deuxième dépôt	Oui	Oui	Oui
Ne pas synchroniser les sources	Oui	Oui	Oui
Récupération (fetch) superficielle	Oui	Oui	Oui

Notes

Cliquez sur Paramètres avancés dans la tâche Obtenir des sources pour afficher certaines des options ci-dessus.

Branche

Il s’agit de la branche par défaut que vous souhaitez lorsque vous mettez manuellement en file d’attente cette build. Si vous définissez un déclencheur planifié pour la build, il s’agit de la branche à partir de laquelle votre build obtient les dernières sources. Le branche par défaut n’a aucune incidence lorsque la build est déclenchée par le biais de l’intégration continue (CI). En règle générale, vous définissez cette valeur sur la même valeur que la branche par défaut du dépôt (par exemple, « master »).

Nettoyer le dépôt local sur l’agent

Vous pouvez effectuer différentes formes de nettoyage du répertoire de travail de votre agent auto-hébergé avant l’exécution d’une build.

En général, pour des performances plus rapides de vos agents auto-hébergés, ne nettoyez pas le dépôt. Dans ce cas, pour obtenir les meilleures performances, assurez-vous que vous générez également de manière incrémentielle en désactivant toute option Nettoyer de la tâche ou de l’outil que vous utilisez pour générer.

Si vous avez besoin de nettoyer le dépôt (par exemple, pour éviter les problèmes causés par les fichiers résiduels d’une build précédente), vos options sont présentées ci-dessous.

Notes

Le nettoyage n’est pas efficace si vous utilisez un agent hébergé par Microsoft, car vous obtiendrez un nouvel agent à chaque fois. Lorsque vous utilisez des agents auto-hébergés, selon la façon dont vos pools d’agents sont configurés, vous pouvez obtenir un nouvel agent pour les exécutions de pipeline suivantes (ou les phases ou travaux dans le même pipeline), de sorte que ne pas nettoyer n’est pas une garantie que les exécutions, travaux ou phases suivants seront en mesure d’accéder aux sorties des exécutions, travaux ou phases précédents.

YAML

Azure Pipelines, Azure DevOps Server 2019 et versions ultérieures

Il existe plusieurs options de nettoyage différentes disponibles pour les pipelines YAML.

• L’étape checkout a une option clean. Lorsqu’elle est définie sur true, le pipeline exécute execute git clean -ffdx && git reset --hard HEAD avant d’extraire le dépôt. Pour plus d’informations, consultez Validation.
• Le paramètre workspace pour job a plusieurs options de nettoyage (sorties, ressources, tout). Pour plus d’informations, consultez Espace de travail.
• L’interface utilisateur des paramètres de pipeline a un paramètre Nettoyer, qui, lorsqu’il est défini sur true, équivaut à spécifier clean: true pour chaque étape checkout de votre pipeline. Pour configurer le paramètre Nettoyer :

  1. Modifiez votre pipeline, choisissez …, puis sélectionnez Déclencheurs.

     

  2. Sélectionnez YAML et Obtenir des sources, puis configurez le paramètre Nettoyer souhaité. La valeur par défaut est true.

     

Pour remplacer les paramètres de nettoyage lors de l’exécution manuelle d’un pipeline, vous pouvez utiliser les paramètres de runtime. Dans l’exemple suivant, un paramètre d’exécution est utilisé pour configurer le paramètre de nettoyage de l’extraction.

parameters:
- name: clean
  displayName: Checkout clean
  type: boolean
  default: true
  values:
  - false
  - true

trigger:
- main

pool: FabrikamPool
#  vmImage: 'ubuntu-latest'

steps:
- checkout: self
  clean: ${{ parameters.clean }}

Par défaut, clean est défini sur true, mais peut être substitué lors de l’exécution manuelle du pipeline en décochant la case Nettoyage de l’extraction qui est ajoutée pour le paramètre de runtime.

Classique

Azure Pipelines, TFS 2018, TFS 2017.2, TFS 2017.3

Sélectionnez l’une des options suivantes :

• Sources : le pipeline de build effectue une annulation des modifications apportées dans $(Build.SourcesDirectory). Plus précisément, les commandes Git suivantes sont exécutées avant d’extraire la source.

  git clean -ffdx
  git reset --hard HEAD
  

• Sources et répertoire de sortie : même opération que l’option Sources ci-dessus, plus : supprime et recrée $(Build.BinariesDirectory). Notez que $(Build.ArtifactStagingDirectory) et $(Common.TestResultsDirectory) sont toujours supprimés et recréés avant chaque build, peu importe leur valeur.

• Répertoire des sources : supprime et recrée $(Build.SourcesDirectory). Cela entraîne l’initialisation d’un nouveau dépôt Git local pour chaque build.

• Tous les répertoires de build : supprime et recrée $(Agent.BuildDirectory). Cela entraîne l’initialisation d’un nouveau dépôt Git local pour chaque build.

Étiqueter les sources

Vous pouvez étiqueter vos fichiers de code source pour permettre à votre équipe d’identifier facilement la version de chaque fichier incluse dans la build terminée. Vous avez également la possibilité de spécifier si le code source doit être étiqueté pour toutes les builds ou uniquement pour les builds réussies.

Notes

Vous pouvez uniquement utiliser cette fonctionnalité lorsque le dépôt source de votre build est un dépôt GitHub ou un dépôt Git ou TFVC de votre projet.

Dans Format de l’étiquette, vous pouvez utiliser des variables définies par l’utilisateur et prédéfinies qui ont une étendue de « Tout ». Par exemple :

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

Les quatre premières variables sont prédéfinies. Vous pouvez définir My.Variable sous l’onglet Variables.

Le pipeline de build étiquette vos sources avec une étiquette Git.

Certaines variables de build peuvent produire une valeur qui n’est pas une étiquette valide. Par exemple, des variables comme $(Build.RequestedFor) et $(Build.DefinitionName) peuvent contenir des espaces blancs. Si la valeur contient des espaces blancs, l’étiquette n’est pas créée.

Une fois que les sources sont étiquetées par votre pipeline de build, un artefact avec la référence Git refs/tags/{tag} est automatiquement ajouté à la build terminée. Cela offre à votre équipe une traçabilité supplémentaire et un moyen plus convivial de naviguer de la build vers le code qui a été généré. L’étiquette est considérée comme un artefact de build, car elle est produite par la build. Lorsque la build est supprimée manuellement ou via une stratégie de rétention, l’étiquette est également supprimée.

Signaler l’état de la build (Azure Pipelines, TFS 2018 et versions ultérieures)

Vous avez la possibilité de donner à votre équipe une vue de l’état de build à partir de votre référentiel source distant.

Si vos sources se trouvent dans un dépôt Git Azure Repos de votre projet, cette option affiche un badge sur la page Code pour indiquer si la build réussit ou échoue. L’état de build s’affiche dans les onglets suivants :

• Fichiers : indique l’état de la dernière build pour la branche sélectionnée.
• Commits : indique l’état de build de chaque validation (cela nécessite l’activation du déclencheur d’intégration continue (CI) pour vos builds).
• Branches : indique l’état de la dernière build pour chaque branche.

Si vous utilisez plusieurs pipelines de build pour le même dépôt dans votre projet, vous pouvez choisir d’activer cette option pour un ou plusieurs pipelines. Dans le cas où cette option est activée sur plusieurs pipelines, le badge sur la page Code indique l’état de la dernière build sur tous les pipelines. Les membres de votre équipe peuvent cliquer sur le badge d’état de build pour afficher l’état de build le plus récent pour chacun des pipelines de build.

GitHub

Si vos sources se trouvent dans GitHub, cette option publie l’état de votre build sur GitHub à l’aide de Vérifications GitHub ou d’API Status. Si votre build est déclenchée à partir d’une demande de tirage GitHub, vous pouvez afficher l’état sur la page des demandes de tirage GitHub. Cela vous permet également de définir des stratégies d’état dans GitHub et d’automatiser les fusions. Si votre build est déclenchée par l’intégration continue (CI), vous pouvez afficher l’état de génération sur la validation ou la branche dans GitHub.

Autres types de dépôts distants Git

Si votre source se trouve dans un autre type de dépôt distant, vous ne pouvez pas utiliser Azure Pipelines ou TFS pour publier automatiquement l’état de build dans ce dépôt. Toutefois, vous pouvez utiliser un badge de build comme moyen d’intégrer et d’afficher l’état de build dans vos expériences de contrôle de version.

Chemin de l’extraction

Si vous extrayez un seul dépôt, par défaut, votre code source est extrait dans un répertoire appelé s. Pour les pipelines YAML, vous pouvez modifier ce paramètre en spécifiant checkout avec path. Le chemin spécifié est relatif à $(Agent.BuildDirectory). Par exemple : si la valeur du chemin d’extraction est mycustompath, et que $(Agent.BuildDirectory) est C:\agent\_work\1, le code source est extrait dans C:\agent\_work\1\mycustompath.

Si vous utilisez plusieurs étapes checkout et que vous extrayez plusieurs dépôts, sans spécifier explicitement le dossier à l’aide de path, chaque dépôt est placé dans un sous-dossier nommé s d’après le dépôt. Par exemple, si vous extrayez deux référentiels nommés tools et code, le code source est extrait dans C:\agent\_work\1\s\tools et C:\agent\_work\1\s\code.

Notez que la valeur du chemin d’extraction ne peut pas être définie pour atteindre les niveaux de répertoire au-dessus de $(Agent.BuildDirectory), path\..\anotherpath engendre donc un chemin d’extraction valide (C:\agent\_work\1\anotherpath), mais une valeur comme ..\invalidpath non (C:\agent\_work\invalidpath).

Si vous utilisez plusieurs étapes checkout et extrayez plusieurs dépôts et que vous souhaitez spécifier explicitement le dossier à l’aide de path, envisagez d’éviter de définir le chemin d’accès d’une autre étape d’extraction (C:\agent\_work\1\s\repo1 et C:\agent\_work\1\s\repo1\repo2), sinon, le sous-dossier de l’étape d’extraction sera effacé par le nettoyage d’un autre dépôt. Notez que ce cas est valide si l’option Nettoyer a la valeur true pour repo1)

Notes

Le chemin d’extraction ne peut être spécifié que pour les pipelines YAML. Pour plus d’informations, consultez Extraction dans le schéma YAML.

Valider les sous-modules

Sélectionnez si vous souhaitez télécharger des fichiers à partir de sous-modules. Vous pouvez choisir d’obtenir les sous-modules immédiats ou tous les sous-modules imbriqués à n’importe quelle profondeur de récursivité. Si vous souhaitez utiliser LFS avec des sous-modules, consultez la note sur l’utilisation de LFS avec des sous-modules.

Notes

Pour plus d’informations sur la syntaxe YAML pour l’extraction des sous-modules, consultez Extraction dans le schéma YAML.

Le pipeline de build vérifie vos sous-modules Git tant qu’ils sont :

• Non authentifié : Dépôt public non authentifié sans informations d’identification requises pour le clonage ou l’extraction.

• Authentifié :

  • Contenu dans le même projet, la même organisation GitHub ou le même compte Bitbucket Cloud que le dépôt Git spécifié ci-dessus.

  • Ajouté à l’aide d’une URL relative au dépôt principal. Par exemple, cet exemple serait extrait : git submodule add /../../submodule.git mymodule Cet exemple ne serait pas extrait : git submodule add https://dev.azure.com/fabrikamfiber/_git/ConsoleApp mymodule

Sous-modules authentifiés

Notes

Vérifiez que vous avez inscrit vos sous-modules à l’aide de HTTPS et non de SSH.

Les mêmes informations d’identification utilisées par l’agent pour obtenir les sources du dépôt principal sont également utilisées pour obtenir les sources des sous-modules.

Si votre dépôt principal et vos sous-modules se trouvent dans un dépôt Git Azure Repos dans votre projet Azure DevOps, vous pouvez sélectionner le compte utilisé pour accéder aux sources. Sous l’onglet Options, dans le menu Étendue d’autorisation du travail de build, sélectionnez l’une des options suivantes :

• Collection de projets pour utiliser le compte de service de build de collection de projets

• Projet actuel pour utiliser le compte de service de build de projet.

Assurez-vous que le compte que vous utilisez a accès au référentiel principal ainsi qu’aux sous-modules.

Si votre dépôt principal et vos sous-modules se trouvent dans la même organisation GitHub, le jeton stocké dans la connexion de service GitHub est utilisé pour accéder aux sources.

Alternative à l’utilisation de l’option Extraire les sous-modules

Dans certains cas, vous ne pouvez pas utiliser l’option Extraire les sous-modules. Vous pouvez avoir un scénario où un autre ensemble d’informations d’identification est nécessaire pour accéder aux sous-modules. Cela peut se produire, par exemple, si vos dépôts principaux et sous-modules ne sont pas stockés dans la même organisation Azure DevOps ou service Git.

Si vous ne pouvez pas utiliser l’option Extraire les sous-modules, vous pouvez utiliser une étape de script personnalisée pour extraire les sous-modules. Tout d’abord, obtenez un jeton d’accès personnel (PAT) et préfixez-le avec pat:. Ensuite, encodez cette chaîne préfixée en base64 pour créer un jeton d’authentification de base. Enfin, ajoutez ce script à votre pipeline :

git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: basic <BASE64_ENCODED_TOKEN_DESCRIBED_ABOVE>" submodule update --init --recursive

Veillez à remplacer < BASIC_AUTH_TOKEN> par votre jeton encodé en base64.

Utilisez une variable secrète dans votre projet ou pipeline de build pour stocker le jeton d’authentification de base que vous avez généré. Utilisez cette variable pour remplir le secret dans la commande Git ci-dessus.

Notes

Q : Pourquoi ne puis-je pas utiliser un gestionnaire d’informations d’identification Git sur l’agent ?R : Le stockage des informations d’identification du sous-module dans un gestionnaire d’informations d’identification Git installé sur votre agent de build privé n’est généralement pas efficace, car le gestionnaire d’informations d’identification peut vous inviter à entrer à nouveau les informations d’identification chaque fois que le sous-module est mis à jour. Cela n’est pas souhaitable pendant les builds automatisées lorsque l’interaction utilisateur n’est pas possible.

Extraire les fichiers de LFS

Sélectionnez si vous souhaitez télécharger des fichiers à partir d’un stockage de fichiers volumineux (LFS).

Dans l’éditeur classique, activez la case à cocher pour activer cette option.

Dans une build YAML, ajoutez une étape d’extraction en définissant lfs sur true :

steps:
- checkout: self
  lfs: true

Si vous utilisez TFS ou si vous utilisez Azure Pipelines avec un agent auto-hébergé, vous devez installer git-lfs sur l’agent pour que cette option fonctionne. Si vos agents hébergés utilisent Windows, envisagez d’utiliser la variable System.PreferGitFromPath pour vous assurer que les pipelines utilisent les versions de git et git-lfs que vous avez installées sur l’ordinateur. Pour plus d’informations, consultez Quelle version de Git mon agent exécute-t-il ?

Utilisation de Git LFS avec des sous-modules

Si un sous-module contient des fichiers LFS, Git LFS doit être configuré avant d’extraire les sous-modules. Les agents macOS et Linux hébergés par Microsoft sont préconfigurés de cette façon. Les agents Windows et les agents macOS/Linux auto-hébergés ne le sont pas nécessairement.

Pour contourner ce problème, si vous utilisez YAML, vous pouvez ajouter l’étape suivante avant votre checkout :

steps:
- script: |
    git config --global --add filter.lfs.required true
    git config --global --add filter.lfs.smudge "git-lfs smudge -- %%f"
    git config --global --add filter.lfs.process "git-lfs filter-process"
    git config --global --add filter.lfs.clean "git-lfs clean -- %%f"
  displayName: Configure LFS for use with submodules
- checkout: self
  lfs: true
  submodules: true
# ... rest of steps ...

Cloner un deuxième dépôt

Par défaut, votre pipeline est associé à un dépôt provenant d’Azure Repos ou d’un fournisseur externe. Il s’agit du dépôt qui peut déclencher des builds sur des validations et des demandes de tirage.

Vous pouvez inclure des sources d’un deuxième dépôt dans votre pipeline. Pour ce faire, écrivez un script.

git clone https://github.com/Microsoft/TypeScript.git

Si le dépôt n’est pas public, vous devez passer l’authentification à la commande Git.

Azure Repos

Vous pouvez cloner plusieurs dépôts dans le même projet que votre pipeline à l’aide de l’extraction de plusieurs dépôts.

Si vous devez cloner un dépôt à partir d’un autre projet qui n’est pas public, vous devez vous authentifier en tant qu’utilisateur ayant accès à ce projet.

Notes

Utilisez une variable secrète pour stocker les informations d’identification en toute sécurité.

Les variables secrètes ne sont pas automatiquement mises à la disposition des scripts en tant que variables d’environnement. Consultez Variables secrètes pour savoir comment les mapper.

Pour Azure Repos, vous pouvez utiliser un jeton d’accès personnel avec l’autorisation Code (Lecture). Envoyez-le en tant que champ de mot de passe dans un en-tête d’autorisation « basique » sans nom d’utilisateur. (En d’autres termes, codez en base64 la valeur de :<PAT>, y compris les deux-points.)

AUTH=$(echo -n ":$REPO_PAT" | openssl base64 | tr -d '\n')
git -c http.<repo URL>.extraheader="AUTHORIZATION: basic $AUTH" clone <repo URL> --no-checkout --branch master

Ne pas synchroniser les sources

Les travaux hors déploiement récupèrent automatiquement les sources. Utilisez cette option si vous souhaitez ignorer ce comportement. Cette option peut être utile dans les cas où vous souhaitez :

• Utiliser Git init, config et fetch à l’aide de vos propres options personnalisées.

• Utiliser un pipeline de build pour exécuter simplement un travail d’automatisation (par exemple, certains scripts) qui ne dépend pas du code dans le contrôle de version.

Si vous souhaitez désactiver le téléchargement des sources :

• Azure Pipelines, TFS 2018 et versions ultérieures : Cliquez sur Paramètres avancés, puis sélectionnez Ne pas synchroniser les sources.

Notes

Lorsque vous utilisez cette option, l’agent ignore également l’exécution des commandes Git qui nettoient le dépôt.

Récupération (fetch) superficielle

Sélectionnez si vous souhaitez limiter le nombre de téléchargements dans l’historique. Cela aboutit effectivement à git fetch --depth=n. Si votre dépôt est volumineux, cette option peut rendre votre pipeline de build plus efficace. Votre dépôt peut être volumineux s’il est utilisé depuis longtemps et s’il a un historique important. Il peut également être volumineux si vous avez ajouté et supprimé ultérieurement des fichiers volumineux.

Dans ce cas, cette option peut vous aider à conserver les ressources réseau et de stockage. Cela peut également vous faire gagner du temps. La raison pour laquelle cela n’économise pas toujours du temps est que, dans certaines situations, le serveur peut avoir besoin de passer du temps à calculer les validations à télécharger pour la profondeur que vous spécifiez.

Notes

Lorsque la build est mise en file d’attente, la branche à générer est résolue en ID de validation. Ensuite, l’agent extrait la branche et extrait la validation souhaitée. Il existe une petite fenêtre entre le moment où une branche est résolue en ID de validation et le moment où l’agent effectue l’extraction. Si la branche est mise à jour rapidement et que vous définissez une valeur très petite pour la récupération superficielle, la validation peut ne pas exister lorsque l’agent tente de l’extraire. Si cela se produit, augmentez le paramètre de profondeur de récupération superficielle.

Après avoir sélectionné la case à cocher pour activer cette option, dans la zone Profondeur, spécifiez le nombre de validations.

Conseil

La variable Agent.Source.Git.ShallowFetchDepth mentionnée ci-dessous fonctionne également et remplace les contrôles de case à cocher. De cette façon, vous pouvez modifier le paramètre lorsque vous mettez en file d’attente la build.

Préférer Git à partir du chemin d’accès

Par défaut, l’agent Windows utilise la version de Git fournie avec le logiciel de l’agent. Il s’agit de la version recommandée par Microsoft. Néanmoins, vous disposez de plusieurs options pour remplacer ce comportement par défaut et choisir la version de Git que l’ordinateur de l’agent a installée dans le chemin.

• Définissez sur true une variable de pipeline nommée System.PreferGitFromPath dans vos pipelines.
• Sur les agents autohébergés, vous pouvez créer un fichier nommé .env dans le répertoire racine de l’agent et ajouter une ligne System.PreferGitFromPath=true au fichier. Pour plus d’informations, consultez Comment définir des variables d’environnement différentes pour chaque agent ?.

Pour voir la version de Git utilisée par un pipeline, vous pouvez examiner les journaux d’activité d’une étape checkout dans votre pipeline, comme illustré dans l’exemple suivant.

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

Ce paramètre a toujours la valeur true sur les agents non Windows.

Options de déclencheur pour d’autres Git

Lorsqu’un dépôt Git autre/externe est spécifié, les builds CI nécessitent que le dépôt soit accessible à partir d’Internet. Si le dépôt se trouve derrière un pare-feu ou un proxy, seules les builds planifiées et manuelles fonctionnent.

Questions fréquentes (FAQ)

Quels protocoles l’agent de build peut-il utiliser avec Git ?

L’agent prend en charge HTTPS.

L’agent ne prend pas encore en charge SSH. Consultez Autoriser la build à utiliser l’authentification SSH lors de l’extraction des sous-modules Git.