If you’re running Azure DevOps pipelines without a consistent build tagging strategy, you’re flying blind. You might be shipping software, but when something breaks in production at 2am, can you immediately tell which commit caused it? Which features were in that release? What changed since the last deployment?
Probably not.
Build tagging isn’t just good hygiene—it’s the foundation for automated release notes, effective incident response, and actually knowing what you’ve shipped.
Note: This article builds on the semantic versioning foundation I covered in Azure DevOps YAML pipeline naming: from chaos to consistent versioning. If you haven’t implemented structured pipeline versioning yet, start there first. This article assumes you already have semantic versioning in place and focuses on automated tagging and traceability.
The Problem: Version Chaos
Without proper build tagging, your deployment history looks like this:
- Build #4523: What was in this? Who knows.
- Build #20251101-4524: Something changed. Maybe.
- Build #20234525.121: This one went to prod. Or was it 20234525.100?
When a customer reports a bug, you’re stuck asking:
- “Which version are they running?”
- “What commit is that?”
- “What changed between the working version and this one?”
Every question costs minutes you don’t have during an incident.
The Solution: Semantic Versioning + Automated Tagging
A proper build tagging strategy gives you three critical capabilities:
- Version traceability: Every build has a human-readable version number
- Git correlation: Every version maps to an exact commit and tag (this article)
- Release automation foundation: Clean versions enable automated release notes (next article)
This article focuses on #2: automatically creating Git tags that match your build versions, giving you bulletproof traceability from production deployments back to source code.
Step 1: Semantic Versioning in Your Pipeline
If you’ve followed my previous article on structured pipeline versioning, you should already have this in your azure-pipelines.yml:
variables:
majorVersion: 1
minorVersion: 0
patchVersion: 0
name: $(majorVersion).$(minorVersion).$(patchVersion)$(Rev:.r)
This creates semantic versions like 1.0.0.45 where the $(Rev:.r) auto-increments for each build.
The key point for this article: we’re going to take this version number and use it to create automated tags in both Azure DevOps and Git.
Step 2: Tag Everything Consistently
Critical rule: Your pipeline version must match your artifact versions.
If your build is 1.2.3.45, then:
- Docker image:
myapp:1.2.3.45 - NuGet package:
MyLibrary.1.2.3.45.nupkg - Deployment artifact:
myapp-1.2.3.45.zip
Example Docker tagging:
- task: Docker@2
inputs:
command: 'buildAndPush'
repository: 'myapp'
tags: |
$(Build.BuildNumber)
latest
Why consistency matters:
When production shows version 1.2.3.45, you can immediately:
- Pull that exact Docker image locally
- Find the Azure DevOps build
- Trace to the Git commit (this is what Step 3 enables!)
- See what changed since
1.2.3.44
Step 3: Automated Build Tagging
Create tag-build.yml as a reusable template:
steps:
- script: |
if [ "$(Build.SourceBranch)" = "refs/heads/main" ] || [ "$(Build.SourceBranch)" = "refs/heads/master" ]; then
echo "##vso[build.addbuildtag]$(Build.BuildNumber)"
else
echo "##vso[build.addbuildtag]$(Build.BuildNumber)-beta"
fi
displayName: 'Tag Build in Azure DevOps'
- pwsh: |
cd $(Build.SourcesDirectory)
$repoUrl = "$(Build.Repository.Uri)"
git tag $env:BuildNumber
git push "$repoUrl" $env:BuildNumber
displayName: 'Create Git Tag'
env:
BuildNumber: $(Build.BuildNumber)
SYSTEM_ACCESSTOKEN: $(System.AccessToken)
condition: and(succeeded(), or(eq(variables['Build.SourceBranch'], 'refs/heads/master'),eq(variables['Build.SourceBranch'], 'refs/heads/main')))
What this does:
- Tags the Azure DevOps build with the version number (or adds
-betafor non-main branches) - Creates a Git tag on the commit that triggered the build
- Pushes the Git tag back to your repository (only for main/master)
Include it in your pipeline:
stages:
- stage: Build
jobs:
- job: BuildJob
steps:
- template: templates/tag-build.yml
- task: Docker@2
# your build steps...
Step 4: Enable System.AccessToken Permissions
For the Git tagging to work, you need to grant your pipeline permission to push tags.
In your Azure DevOps project:
- Go to Project Settings → Repositories → Your repository
- Click Security
- Find [Your Project] Build Service
- Set Contribute to Allow
- Set Create tag to Allow
Without this, your pipeline will fail when trying to push the Git tag.
The Payoff: What You Get
With this in place, here’s what changes:
Before:
Customer: “The app is broken!”
You: “Which version?”
Customer: “I don’t know, the latest one?”
You: Spends 20 minutes figuring out what they’re running
After:
Customer: “Version 1.2.3.45 is broken!”
You: Clicks on build 1.2.3.45, sees the Git tag, checks the commits since 1.2.3.44, identifies the issue in 2 minutes
More specifically, you can now:
✅ Instant incident response
- Customer reports issue on version
1.2.3.45 - You click the Azure DevOps build
- View the Git tag to see exactly what code shipped
- Compare with previous version to find the regression
✅ Runtime version visibility
// In your API/application
[HttpGet("version")]
public string GetVersion()
{
return "1.2.3.45"; // Injected at build time or read from environment variable
}
Your support team can ask customers to hit /api/version and immediately know what they’re running.
✅ Audit trail
- Every production deployment has a version
- Every version has a Git tag
- Every Git tag shows exactly what changed
- Compliance and audit teams love you
✅ Foundation for automation (next article)
- Generate release notes automatically between versions
- Compare tags to see what PRs merged
- Extract commit messages and work items
- Build changelogs with zero manual effort
What About Pre-Release Versions?
Notice the -beta suffix for non-main branches in the tagging script? This gives you:
- Main branch:
1.2.3.45 - Feature branch:
1.2.3.46-beta - Pull request:
1.2.3.47-beta
Why this matters:
- QA knows they’re testing a pre-release build
- Production deployments only use non-beta versions
- You can filter Azure DevOps searches: “Show me all beta builds from last week”
(For more advanced branch-based versioning strategies, including version suffixes in the build name itself, see the previous article.)
Common Pitfalls to Avoid
❌ Don’t use different versioning schemes
- Bad: Pipeline is
1.2.3.45, Docker image isbuild-20250101-3 - Good: Everything is
1.2.3.45
❌ Don’t forget to increment major/minor versions
- Update the variables when you ship breaking changes or new features
2.0.0.1tells everyone “this is a major release”- (See the version bump strategies section in the previous article)
❌ Don’t skip tagging non-production builds
- Even dev/staging builds need versions
- The
-betasuffix is enough to distinguish them
❌ Don’t manually create versions
- Let the pipeline do it automatically
- Manual versions = human error
The Bottom Line
Build tagging takes 30 minutes to implement and may well save you hours every week. More importantly, it transforms how your team operates:
- Incidents resolve faster because you can trace issues immediately
- Deployments are less scary because you know exactly what changed
- Customer support improves because you can answer “which version?” instantly
- Release notes become automated (stay tuned for the next article)
Every mature engineering team does this. If you’re not tagging builds yet, start today.
Next Steps
- First: If you haven’t already, implement the semantic versioning foundation from the previous article
- Create the
tag-build.ymltemplate - Grant build service permissions for tagging
- Include the template in your build stage
- Run a build and verify the tags appear in Azure DevOps and Git
Once you’ve got consistent versioning in place, you’re ready for the next level: automatically generating release notes from your build tags. We’ll cover that in the next article, including a free tool you can start using immediately.
