What does Build.SourceVersion actually mean in Azure pipelines

A quick tip for anyone working in Azure Pipelines as I didn't see this particular thing documented very well in any public documentation.

I was recently working on a new Azure Pipeline definition to do some testing of our CI pipelines. What I wanted to do was allow our 1JS Engineering Systems team to run a "CI Validation" pipeline which basically takes their branch, and runs it against our CI pipeline, but with test accounts, and no publishing side effects.

Everything, seemed to be going fine, however, I was seeing random failures in the build that were sometimes there, and sometimes not.

The checkout we're using is a bit custom, but more or less is using a Predefined Variable called Build.SourceVersion which the docs describe as...

The latest version control change of the triggering repo that is included in this build.

We used it in our Pull Request pipelines, so my assumption was that it would do the same thing as our PRs and more or less give you a commit that is the result of merging your Source Branch with your Target Branch, aka something like feature-foo with main.

However, I found out after chatting with a co-worker, and digging around finding this issue, that Build.SourceVersion changes meaning depending on the context of the pipeline run.

On a pull request, Azure DevOps does not build the exact version of the code that you pushed, but rather a version merged with your target branch

If you manually trigger a run of a pipeline, then Build.SourceVersion points to the commit at which you triggered the run.

However, when Azure Pipelines triggers the build on your behalf in the context of a Pull Request, either set as a required or optional PR policy, the Build.SourceVersion gets set to effectively the result of doing this in a temporary branch.

git fetch origin main
git checkout <feature-branch>
git merge --no-ff origin/main
# Use the resulting merge commit SHA as Build.SourceVersion

You can see this in the difference when you click the sha under the Version header in the Sources Cards.

Here's the title of the commit when the run is triggered via a Pull Request...

And when it's triggered manually.

You can see in the first, that it clearly mentions the fact that it's taking the latest commit in the Pull Request, and merging it with main and using that result as the Build.SourceVersion automatically.

Therefore, if you want to create pipelines which actually run against a merge of your Source and Target, make sure not to manually trigger it, but instead have either a Pull Request Policy which is required or optional that allows you to trigger the pipeline from the PR itself.

An Optional policy would look like the following image.

This optional policy would attach itself to PRs you want, and be queue-able for any developer.

Hope that helps any of y'all out there using Azure Pipelines clarify what Build.SourceVersion really means.