Automate Software Versioning in CICD with Azure DevOps

6 min readJul 14, 2020

During the release planning, we always face challenges on how to tag our Software Version and how to prepare our release Changelog, and this question becomes a routine during the release flow. Some team will inject a manual process to create a Release PR that includes all the release information and update the version manually. This manual process slows the team down, and it’s not integrated smoothly in the CICD flow. In this article, I am going to demonstrate a real-life example on one of my CICD projects to automate your software versioning, and this time we will explore Azure DevOps.

The following diagram explains the simple workflow in Azure DevOps that auto-tag the version when the developer merges a PR to the master branch.

Introducing Azure DevOps

Azure DevOps is a Software as a service (SaaS) platform from Microsoft that provides an end-to-end DevOps toolchain for developing and deploying software. It also integrates with most leading tools on the market and is a great option for orchestrating a DevOps toolchain. In this article, we will focus on Azure Repo which is the Git repository service, and Azure Pipeline , which is the build service.

Introducing Conventional Commit Specification

In order to automate the software version, we need a specification that can work together between humans and Machine. Here we choose Conventional Commit Specification, which is a very common specification used in a lot of NPM packages. The specification provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

The commit message should be structured as follows:-

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

One example of commit message with breaking changes:-

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Introducing Standard-Version NPM tool

Besides the specification, we will need a tool that can understand the specification and work for us to automate the software version. We select Standard-Version to help us do that. Standard-Version is an NPM package that does the following thing:-

Retrieve the current version of your repository.
bump the version based on your commits. (Conventional Commit Specification)
Generates a changelog based on your commits.
Creates a new commit including new version and updated CHANGELOG.
Creates a new tag with the new version number.

Preparing your Application Repository

To make it relevant to development workflow, we create a DotNet API project using DotNet core New CLI, and you need to create your new repository in Azure Repo. Checkout or initialize your new repository and run the following command, you can use your existing repository to implement auto versioning.

dotnet new webapi -o SimpleApi
cd SimpleApi
dotnet build
dotnet run

Adding the setting for Standard Version

As Standard Version tool was originally built for Github and the changelog link is following Github page URL, we need to override this setting to use in Azure DevOps Repo. Create a new file .versionrc under the root of the folder and paste the following content:-

You are required to replace your_azure_repo_link in the content with your actual Azure Repo URL and it should be in the form of OrganizationName/ProjectName/_git/RepositoryName.

Adding Azure DevOps Pipeline YAML

Azure DevOps Pipeline uses declarative YAML to configure the pipeline stage. We shall use a simple structure to test our automation versioning stage; feel free to read here to know more about Azure DevOps Pipeline YAML schema.

Create a new file azure-pipelines.yml under root of the repo, and fill in the following contents:-

The pipeline script above will perform the dotnet build and dotnet test, the command for non Master branch , execute Bump Version stage on Master branch and a fake Continues Deployment script. You can now commit all your changes to Azure DevOps Repo, and your new pipeline will appear on the Pipelines page. The first run of Pipeline needs to be manually performed; click to run it on the Master branch , and wait for the step result.

Ops, there is an error, let's fix the permission issue

When you run the pipeline, it generates a new version successfully but it fails to push changes to the repository. This is expected as we need to grant Azure DevOps Pipeline to have permission to update source code.

Navigate to Repository Permission under Project Settings > Repos > Repositories > Permission Tab.

Under the Permission page, select your Build Service Account under the Users section. Your build service name should be something with {Project Name} Build Service. On the right-hand side of the permission setting, allow the following permission:-

Contribute, Create tag, Bypass policies when pushing (If you implement policies).

Let's try to trigger the pipeline again, and it successfully Bumps the version, and commit changes. If you review the log, you can see it generate new CHANGELOG.md file and tag new version:-

If you do not tag a minor or patch version previously, it will assume you are doing the first release

Trying to add a new feature

Now we have the auto version working, we will now try to commit the first feature. You can follow the PR process by creating a new feature branch and modify your API response, and merge to master. Use the following format for your commit message:-

git commit -m "feat: Update API"

After merge to master, and you should notice your pipeline automatically trigger and increase minor version by 1 as below:-

The changelog will generate something like below, as we modify the URL, in .versionrc. You can click on the version link and see what changes between the version, and you are able to click on the feature commit tag to see what changes on each feature commits.

Summary

In this article, we introduce Azure DevOps pipeline which allows you to declare your pipeline by YAML file. We also introduce Commitizen Commit specification to standardize your commit message. Lastly, Standard Version npm package is introduced to automate your software version and generate a traceable Software Changelog.

Automate Software Version allows the development team to focus on feature development and Changelog and software version are automatically handled by pipeline.

PS: There are many Commitizen Commit compatible plugin for popular IDE, such as VSCode and Visual Studio