diff --git a/docs/input/docs/reference/build-servers/azure-devops.md b/docs/input/docs/reference/build-servers/azure-devops.md index b48840fbb1..8439d978d6 100644 --- a/docs/input/docs/reference/build-servers/azure-devops.md +++ b/docs/input/docs/reference/build-servers/azure-devops.md @@ -2,17 +2,12 @@ Order: 20 Title: Azure DevOps Description: | - Details on the Azure DevOps or Team Foundation Server Build Pipeline support - in GitVersion + Details on the Azure DevOps Build Pipeline support in GitVersion RedirectFrom: docs/build-server-support/build-server/azure-devops --- +## Installation and usage -## Basic Usage - -In Azure DevOps Pipeline (the web based build system) you can call GitVersion -either using the Command Line build step or install an extension / custom build -step. The custom build step requires a one-time setup to import the GitVersion -task into your TFS or Azure DevOps Pipeline instance. +For Azure DevOps Services or Azure DevOps Server you can install the [GitTools Bundle](https://marketplace.visualstudio.com/items?itemName=gittools.gittools). :::{.alert .alert-danger} **Important** @@ -22,160 +17,4 @@ without it, Azure DevOps Pipelines will perform a shallow clone, which will caus See [the Azure DevOps documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines#shallow-fetch) for more information. ::: -## Executing GitVersion - -### Using GitVersion with the MSBuild Task NuGet Package - -1. Add the [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/) - NuGet package to your projects. - -See [MSBuild Task](/docs/usage/msbuild) for further instructions how to use -the MS Build Task. - -### Using GitVersion with the Command Line build step - -1. Make sure to have GitVersion.exe under version control. There exists also a - [Chocolatey package](https://chocolatey.org/packages/GitVersion.Portable) for - installing GitVersion.exe on build agents. -2. Add a Command Line build step to your build definition. You'll probably want - to drag the task to be at or near the top to ensure it executes before your - other build steps. -3. Set the Tool parameter to `\GitVersion.exe`. -4. Set the Arguments parameter to `/output buildserver /nofetch`. -5. If you want the GitVersionTask to update AssemblyInfo files add - `updateAssemblyInfo true` to the Arguments parameter. -6. If you want to update the build number you need to send a - [logging command](https://github.com/microsoft/azure-pipelines-tasks/blob/main/docs/authoring/commands.md) - to TFS. - -### Using the custom GitVersion build step - -#### Installing - -##### Installing the extension - -For Visual Studio Team Service or TFS 2015 Update 2 or higher it is recommended -to install the GitVersion extension: - -1. Install the - [GitVersion Extension](https://marketplace.visualstudio.com/items?itemName=gittools.usegitversion). - -##### Manually installing/updating the custom build step - -If you run TFS 2015 RTM or Update 1 or don't want to install the GitVersion -extension you can install the build task manually: - -1. Install the `tfx` command line tool as shown [here](https://github.com/microsoft/tfs-cli/blob/master/README.md#setup). -2. For TFS 2015 On-Prem configure Basic Authentication in TFS as shown [here](https://github.com/microsoft/tfs-cli/blob/master/docs/configureBasicAuth.md). -3. Download the GitVersion TFS build task from the latest release on the - [GitVersion releases page](https://github.com/GitTools/GitVersion/releases) and - unzip. -4. Run `tfx login` as shown [here](https://github.com/microsoft/tfs-cli/blob/master/README.md#login). -5. From the directory outside of where you unzipped the task, run - `tfx build tasks upload --task-path .\GitVersionVsixTask --overwrite` where - GitVersionVsixTask is the directory containing the files. -6. It should successfully install. - -#### Using the GitVersion custom build step - -From a TFS build definition, select "Add a Step" and then in the Build category, -choose GitVersion and click Add. You'll probably want to drag the task to be at -or near the top to ensure it executes before your other build steps. - -If you want the GitVersionTask to update AssemblyInfo files, check the box in -the task configuration. For advanced usage, you can pass additional options to -the GitVersion exe in the Additional arguments section. - -The Azure DevOps Pipeline build step can update your build number with -GitVersion variables. See below for details. - -#### Using Pipelines yaml - -Add the following yaml task and variable to your `azure-pipelines.yml` file: - -```yml -variables: - GitVersion.SemVer: '' - -steps: -- task: UseGitVersion@5 - displayName: gitversion - inputs: - versionSpec: '5.x' - updateAssemblyInfo: true -``` - -You can now use the `GitVersion.SemVer` environment variable in any subsequent -tasks to refer to the semantic version number for your build. For example, you -can build your dotnet core application with a semantic version number like so: - -```yml -- task: DotNetCoreCLI@2 - displayName: Build - inputs: - command: build - projects: '$(solution)' - configuration: '$(buildConfiguration)' - versioningScheme: byEnvVar - versionEnvVar: 'GitVersion.SemVer' - -``` - -## Running inside TFS - -### Using the GitVersion Variables - -GitVersion passes variables in the form of `GitVersion.*` (Eg: -`GitVersion.Major`) to TFS Build and also writes `GITVERSION.*` -(Eg: `GITVERSION.MAJOR`) environment variables that are available for any -subsequent build step. - -To use these variables you can just refer to them using the standard variable -syntax. For instance `$(GitVersion.NuGetVersion)` in your nuget pack task to set -the version number. Since update 1 there are no known limitations. - -See [Variables](/docs/reference/variables) for an overview of available variables. - -#### Using GitVersion variables in build name - -To use GitVersion's variables in the build name, just add them in the form -`$(GITVERSION_FullSemVer)` into the Build definition's build number string. Then -just ensure GitVersion is called with `/output buildserver` and it will replace -those variables with the calculated version. The TFS GitVersion Build Step -(above) handles this too, so if you're already using that, there's nothing extra -to configure. - -If GitVersion does not find any substitutions it will just default to using `FullSemVer` - -:::{.alert .alert-danger} -**Important** - -If you currently use `$(rev:.r)` in your build number, that won't -work correctly if you -use GitVersion variables as well due to the delayed expansion of the GitVersion -vars. Instead, you might be able to use `$(GitVersion_BuildMetaData)` to achieve -a similar result. See [Variables](/docs/reference/variables) for more info on the -variables. -::: - -#### Known limitations - -* If you are using on premises TFS, make sure you are using at least - **TFS 2015 Update 1**, otherwise a few things will not work. -* Installing the extension on an on premise TFS requires at least TFS 2015 - Update 2. -* You need to make sure that all tags are fetched for the Git repository, - otherwise you may end with wrong versions (e.g. `FullSemVer` like `1.2.0+5` - instead of `1.2.0` for tagged releases) Just checking the `Clean Repository` - check box in the build definition settings might not be enough since this will - run a `git clean -fdx/reset --hard` without fetching all tags later. You can - force deletion of the whole folder and a re-clone containing all tags by - settings the variable `Build.Clean` to `all`. This will take more time during - build but makes sure that all tags are fetched. In the future it is planned to - allow using `git.exe` instead of current `libgit2sharp` for syncing the repos - which might allow other possibilities to solve this issue. For details see this - [GitHub issue](https://github.com/microsoft/azure-pipelines-tasks/issues/1218). -* If running a build for a certain commit (through passing the commit SHA while - queueing the build) all tags from the repository will be fetched, even the ones - newer than the commit. This can lead to different version numbers while - re-running historical builds. +More information can be found at [gittools/actions](https://github.com/GitTools/actions/blob/main/docs/examples/azure/gitversion/index.md). \ No newline at end of file diff --git a/docs/input/docs/reference/build-servers/bitbucket-pipelines.md b/docs/input/docs/reference/build-servers/bitbucket-pipelines.md index c06e5b3d9e..b809cee247 100644 --- a/docs/input/docs/reference/build-servers/bitbucket-pipelines.md +++ b/docs/input/docs/reference/build-servers/bitbucket-pipelines.md @@ -1,5 +1,5 @@ --- -Order: 35 +Order: 40 Title: BitBucket Pipelines Description: Details on the Atlassian BitBucket Pipelines support in GitVersion --- diff --git a/docs/input/docs/reference/build-servers/buildkite.md b/docs/input/docs/reference/build-servers/buildkite.md index 5531690ef1..d06e9d4aad 100644 --- a/docs/input/docs/reference/build-servers/buildkite.md +++ b/docs/input/docs/reference/build-servers/buildkite.md @@ -1,5 +1,5 @@ --- -Order: 40 +Order: 50 Title: Buildkite Description: Details on the Buildkite support in GitVersion RedirectFrom: docs/build-server-support/build-server/buildkite diff --git a/docs/input/docs/reference/build-servers/continua.md b/docs/input/docs/reference/build-servers/continua.md index 3605084d18..18f035eb04 100644 --- a/docs/input/docs/reference/build-servers/continua.md +++ b/docs/input/docs/reference/build-servers/continua.md @@ -1,5 +1,5 @@ --- -Order: 50 +Order: 60 Title: Continua CI Description: Details on the Continua CI support in GitVersion RedirectFrom: docs/build-server-support/build-server/continua diff --git a/docs/input/docs/reference/build-servers/github-actions.md b/docs/input/docs/reference/build-servers/github-actions.md new file mode 100644 index 0000000000..160498235a --- /dev/null +++ b/docs/input/docs/reference/build-servers/github-actions.md @@ -0,0 +1,18 @@ +--- +Order: 70 +Title: GitHunb Actions +Description: | + Details on the GitHunb Actions Workflow support in GitVersion +--- +## Installation and usage + +For GitHub Actions you can install the action from [GitTools Bundle](https://github.com/marketplace/actions/gittools). + +:::{.alert .alert-danger} +**Important** + +You must disable shallow fetch by setting `fetch-depth: 0` in your `checkout` step; +without it, GitHunb Actions might perform a shallow clone, which will cause GitVersion to display an error message. +::: + +More information can be found at [gittools/actions](https://github.com/GitTools/actions/blob/main/docs/examples/github/gitversion/index.md). \ No newline at end of file diff --git a/docs/input/docs/reference/build-servers/gitlab.md b/docs/input/docs/reference/build-servers/gitlab.md index b9495856e7..a3f9acde28 100755 --- a/docs/input/docs/reference/build-servers/gitlab.md +++ b/docs/input/docs/reference/build-servers/gitlab.md @@ -1,5 +1,5 @@ --- -Order: 60 +Order: 80 Title: GitLab CI Description: Details on the GitLab CI support in GitVersion RedirectFrom: docs/build-server-support/build-server/gitlab diff --git a/docs/input/docs/reference/build-servers/jenkins.md b/docs/input/docs/reference/build-servers/jenkins.md index 46b6355a29..70f376e8f1 100644 --- a/docs/input/docs/reference/build-servers/jenkins.md +++ b/docs/input/docs/reference/build-servers/jenkins.md @@ -1,5 +1,5 @@ --- -Order: 70 +Order: 90 Title: Jenkins Description: Details on the Jenkins support in GitVersion RedirectFrom: docs/build-server-support/build-server/jenkins diff --git a/docs/input/docs/reference/build-servers/myget.md b/docs/input/docs/reference/build-servers/myget.md index 383d61408a..fd9166aa52 100644 --- a/docs/input/docs/reference/build-servers/myget.md +++ b/docs/input/docs/reference/build-servers/myget.md @@ -1,5 +1,5 @@ --- -Order: 80 +Order: 100 Title: MyGet Description: Details on the MyGet support in GitVersion RedirectFrom: docs/build-server-support/build-server/myget diff --git a/docs/input/docs/reference/build-servers/octopus-deploy.md b/docs/input/docs/reference/build-servers/octopus-deploy.md index 79ce4035cd..d802be9e62 100644 --- a/docs/input/docs/reference/build-servers/octopus-deploy.md +++ b/docs/input/docs/reference/build-servers/octopus-deploy.md @@ -1,5 +1,5 @@ --- -Order: 90 +Order: 110 Title: Octopus Deploy Description: Details on the Octopus Deploy support in GitVersion RedirectFrom: docs/build-server-support/build-server/octopus-deploy diff --git a/docs/input/docs/reference/build-servers/teamcity.md b/docs/input/docs/reference/build-servers/teamcity.md index 55d663cc8d..da4e7aad01 100644 --- a/docs/input/docs/reference/build-servers/teamcity.md +++ b/docs/input/docs/reference/build-servers/teamcity.md @@ -1,5 +1,5 @@ --- -Order: 100 +Order: 120 Title: TeamCity Description: Details on the TeamCity support in GitVersion RedirectFrom: docs/build-server-support/build-server/teamcity