GitVersion est un outil open source qui automatise la gestion des versions sémantique (SemVer) dans les projets utilisant Git.
À quoi sert GitVersion ?
- Il génère automatiquement un numéro de version basé sur l’historique Git, la branche courante et la stratégie de workflow (par exemple GitFlow ou GitHub Flow).
- Il évite de devoir incrémenter manuellement la version dans vos fichiers.
- Il s’intègre facilement dans les pipelines CI/CD (Azure DevOps, GitHub Actions, etc.) pour versionner vos builds, packages NuGet, ou artefacts.
Comment ça marche ?
Analyse du dépôt Git
GitVersion lit les branches, tags et commits pour déterminer la version à appliquer selon la configuration (par défaut : GitFlow).
Le principe est toujours le même :
- Trouver la source de version : le dernier tag SemVer accessible (
1.2.0,v1.2.0), un nom de branche contenant une version (release/1.3.0), ou la valeurnext-versionde la configuration. - Appliquer l’incrément défini pour la branche courante (
Major,Minor,Patch), ou celui demandé dans un message de commit. - Ajouter le label de pré-release de la branche (
alpha,beta, nom de la feature…) et un numéro calculé à partir du nombre de commits depuis la source de version.
Stratégie de versionnement
Par défaut GitVersion suit la stratégie de Gitflow (décrite en détail dans l’article Git Flow & Git Flow AVH) :
- Sur
main: version stable (ex : 1.2.0) - Sur
release/1.3.0: version release (ex: 1.3.0-beta.1) - Sur
develop: version pré-release (ex : 1.3.0-alpha.5) - Sur une branche
feature/xyz: version snapshot (ex : 1.3.0-xyz.1)
Le calcul de version en image
Le schéma suivant montre les versions calculées par GitVersion (configuration GitFlow par défaut) au fil d’un cycle de développement. Le numéro après le label dépend du nombre de commits depuis la source de version : les valeurs sont données à titre indicatif.
---
config:
gitGraph:
mainBranchOrder: 1
---
gitGraph
commit id:"1.2.0" tag:"1.2.0"
branch develop order: 3
checkout develop
commit id:"1.3.0-alpha.1"
branch feature/login order: 4
checkout feature/login
commit id:"1.3.0-login.1"
commit id:"1.3.0-login.2"
checkout develop
merge feature/login id:"1.3.0-alpha.4"
branch release/1.3.0 order: 2
checkout release/1.3.0
commit id:"1.3.0-beta.1"
checkout main
merge release/1.3.0 id:"1.3.0" tag:"1.3.0"
checkout develop
merge release/1.3.0 id:"1.4.0-alpha.1"
checkout main
branch hotfix/1.3.1 order: 0
commit id:"1.3.1-beta.1"
checkout main
merge hotfix/1.3.1 id:"1.3.1" tag:"1.3.1"
Ce qu’il faut retenir :
mainne produit une version stable que grâce aux tags : c’est le tag1.3.0qui « fige » la version.developest toujours une version mineure en avance sur la dernière release (1.3.0-alpha, puis1.4.0-alphaune fois1.3.0publiée).release/1.3.0ethotfix/1.3.1tirent leur version du nom de la branche.- Une branche
featurehérite de la version de sa branche source et utilise son nom comme label.
Forcer un incrément depuis un message de commit
Sans toucher à la configuration, on peut demander un incrément particulier dans un message de commit :
git commit -m "Refonte de l'API publique +semver: major"
git commit -m "Ajout de l'export CSV +semver: minor"
git commit -m "Correction d'une coquille +semver: none"
Sortie
GitVersion peut générer :
- Des variables d’environnement (pour CI/CD)
- Un fichier
version.jsonouAssemblyInfo.cs - Des propriétés MSBuild pour .NET
Les principales variables produites :
| Variable | Exemple | Usage typique |
|---|---|---|
MajorMinorPatch |
1.3.0 |
Version « propre » |
SemVer |
1.3.0-beta.1 |
Version de package NuGet |
FullSemVer |
1.3.0-beta.1+3 |
Version avec métadonnées de build |
AssemblySemVer |
1.3.0.0 |
AssemblyVersion |
InformationalVersion |
1.3.0-beta.1+3.Branch.release-1.3.0.Sha.1a2b3c4... |
Traçabilité (branche + commit) |
BranchName, ShortSha |
release/1.3.0, 1a2b3c4 |
Nommage d’artefacts |
Exemple d’utilisation
- Installation :
installation globale :
dotnet tool install --global GitVersion.Tool
Installation au niveau de la solution dotnet
dotnet new tool-manifest
dotnet tool install GitVersion.Tool
- Afficher la version de la branche en cours :
dotnet gitversion
- Afficher une seule variable :
dotnet gitversion /showvariable SemVer
- Intégration dans un pipeline : Utilisez la version générée pour nommer vos packages, images Docker, etc.
GitVersion a besoin de l’historique complet du dépôt (branches et tags). Sur un clone superficiel (shallow clone, fréquent en CI), le calcul échoue : pensez à récupérer tout l’historique.
Configuration
Ajoutez un fichier GitVersion.yml à la racine du repo pour personnaliser le comportement (stratégie GitFlow, format des versions, etc.).
Exemple de GitVersion.yml (GitVersion 6.x)
# Modèle de départ : GitFlow/v1 (défaut), GitHubFlow/v1 ou TrunkBased/preview1
workflow: GitFlow/v1
# Mode de déploiement par défaut : ManualDeployment, ContinuousDelivery, ContinuousDeployment
mode: ContinuousDelivery
# Préfixe accepté pour les tags de version (ex : v1.2.0)
tag-prefix: '[vV]?'
# Version minimale à utiliser si aucun tag n'existe encore
next-version: 1.0.0
# AssemblyVersion = 1.3.0.0 (on évite d'y mettre le label de pré-release)
assembly-versioning-scheme: MajorMinorPatch
branches:
main:
label: '' # pas de label : version stable
increment: Patch
develop:
label: alpha
increment: Minor
release:
label: beta
mode: ManualDeployment
feature:
label: '{BranchName}' # le nom de la branche devient le label
increment: Inherit # hérite de l'incrément de la branche source
ignore:
sha: [] # commits à ignorer dans le calcul
La configuration ne fait que surcharger le modèle choisi par workflow : on ne déclare que ce que l’on veut changer.
Les trois modes de déploiement :
| Mode | Comportement |
|---|---|
ManualDeployment |
La version reste la même tant qu’elle n’est pas taguée ; les commits s’ajoutent dans les métadonnées (1.3.0-beta.1+3) |
ContinuousDelivery |
Le numéro de pré-release augmente à chaque commit (1.3.0-alpha.5) |
ContinuousDeployment |
Chaque commit produit une version distincte, pensée pour un déploiement automatique |
Pour vérifier une configuration, la commande dotnet gitversion /showconfig affiche la configuration effective (modèle + surcharges).
Migration depuis la v5 : la propriété
tagd’une branche s’appelle désormaislabel, le modeMainlinea disparu au profit du workflowTrunkBased, et la sémantique des modes a évolué. Une configuration v5 doit être relue avant de passer en v6.
Pour plus de détails la doc officielle
Intégration GitHub Actions
Le projet GitTools/actions fournit deux actions : setup installe l’outil, execute calcule la version et l’expose en sorties et variables d’environnement.
name: Build
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # obligatoire : GitVersion a besoin de tout l'historique
- name: Installer GitVersion
uses: gittools/actions/gitversion/setup@v4.7.0
with:
versionSpec: '6.x'
- name: Calculer la version
id: gitversion # id utilisé pour lire les sorties
uses: gittools/actions/gitversion/execute@v4.7.0
- name: Afficher la version
run: echo "Version : ${{ steps.gitversion.outputs.semVer }}"
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.0.x'
# Utilisation de la version pour le package NuGet
- name: Pack
run: dotnet pack -c Release -p:Version=${{ steps.gitversion.outputs.semVer }}
Les sorties sont accessibles via steps.<id>.outputs.<nom> (semVer, fullSemVer, majorMinorPatch, assemblySemVer, informationalVersion, shortSha…) et, pour les étapes suivantes du même job, via les variables d’environnement GitVersion_<Nom> (ex : env.GitVersion_SemVer).
Si GitVersion est déjà déclaré comme outil local (manifeste dotnet-tools.json), on peut aussi se contenter de dotnet tool restore puis dotnet gitversion /output buildserver.
GitVersion.MsBuild
GitVersion.MsBuild est un package NuGet qui permet d’intégrer automatiquement GitVersion dans le processus de build MSBuild/.NET, sans avoir besoin d’appeler la CLI séparément. Il est particulièrement utile pour les projets .NET qui utilisent dotnet build, ou des pipelines CI/CD.
Fonctionnement
- Ajout du package
Ajoutez le package NuGet à votre projet ou solution :
dotnet add package GitVersion.MsBuild
- Détection automatique
Lors de chaque build (dotnet build,msbuild, ou build Visual Studio), GitVersion analyse votre dépôt Git et génère la version appropriée selon la configuration (par défaut : GitFlow, personnalisable viaGitVersion.yml). - Injection dans le build
Les propriétés de version générées (par exemple :Version,AssemblyVersion,FileVersion,PackageVersion) sont injectées automatiquement dans le build .NET, vos assemblies et vos packages NuGet.
Le package étant uniquement utile au build, il est conseillé de le référencer avec PrivateAssets="all" pour qu’il n’apparaisse pas comme dépendance de vos propres packages :
<ItemGroup>
<PackageReference Include="GitVersion.MsBuild" Version="6.0.0">
<PrivateAssets>all</PrivateAssets>
</PackageReference>
</ItemGroup>
Avantages
- Aucune commande supplémentaire à exécuter : la version est calculée à chaque build.
- Intégration transparente : fonctionne avec Visual Studio,
dotnet build, et les pipelines CI/CD. - Versionnement cohérent : la version de vos DLL, EXE, et packages NuGet reflète toujours l’état du dépôt Git.
[!WARNING] la version 5 de
GitVersion.MsBuildne supporte plus dotnet framework, mais uniquement dotnet core. Visual studio 2022 étant en dotnet framework, lors d’une compilation de depuis visual studio il ne se passera rien. Les build depuis la CI via msbuild seront corrects.
GitVersion, MinVer ou Nerdbank.GitVersioning ?
GitVersion n’est pas le seul outil de versionnement basé sur Git dans l’écosystème .NET. Deux alternatives sont très répandues :
- MinVer : un package MSBuild minimaliste qui ne regarde que les tags. Après le tag
1.2.0, cinq commits plus loin, la version vaut1.2.1-alpha.0.5. Pour publier, on pose un tag. Configuration par propriétés MSBuild (MinVerTagPrefix,MinVerMinimumMajorMinor…). - Nerdbank.GitVersioning (NBGV) : la version majeure.mineure est écrite dans un fichier
version.jsonversionné, et le patch est calculé à partir du nombre de commits (git height). Un outilnbgvaide à préparer les releases (nbgv prepare-release). Utilisé par de nombreux projets de la fondation .NET.
| Critère | GitVersion | MinVer | Nerdbank.GitVersioning |
|---|---|---|---|
| Source de la version | Tags + branches + configuration | Tags uniquement | Fichier version.json + git height |
| Configuration | GitVersion.yml |
Propriétés MSBuild | version.json |
| Tient compte des branches | Oui (GitFlow, GitHub Flow, trunk) | Non | Partiellement (branches publiques / non publiques) |
| Intégration | CLI, package MSBuild, actions CI | Package MSBuild (+ CLI) | Package MSBuild, CLI nbgv |
| Exemple entre deux releases | 1.3.0-alpha.5 |
1.2.1-alpha.0.5 |
1.3.5-g1a2b3c4 |
| Complexité | Élevée, très paramétrable | Très faible | Moyenne |
| Idéal pour | Équipes en Git Flow, plusieurs branches de release | Bibliothèques simples, trunk-based | Gros dépôts, versions pilotées par fichier |
En résumé : MinVer si l’on veut « juste des tags », NBGV si l’on préfère une version explicite dans le code, GitVersion si le workflow de branches doit se refléter dans les numéros de version.
Résumé
| Besoin | Solution |
|---|---|
| Calculer la version en local | dotnet gitversion |
| Lire une variable | dotnet gitversion /showvariable SemVer |
| Personnaliser le calcul | GitVersion.yml (workflow, mode, branches) |
| Vérifier la configuration effective | dotnet gitversion /showconfig |
| Versionner automatiquement les assemblies | Package GitVersion.MsBuild |
| Versionner en CI GitHub | gittools/actions/gitversion/setup + execute, fetch-depth: 0 |
| Forcer un incrément | +semver: major / minor / patch / none dans le commit |
| Alternative minimaliste | MinVer (tags) ou Nerdbank.GitVersioning (version.json) |