For those who know me well, starting a bicep tips and tricks series would not be a surprise to them. The moment the Bicep language was introduced, I knew I would be completely obsessed. I love writing bicep templates and even more the clever refinement to make them reusable, configurable, manageable, readable… I really enjoy sharing my experiences with Bicep, so here it begins on the wider front. From one Bicep nerd to another, I hope you find these tips useful, happy templating!

Why is versioning important

Versioning is a fundamental practice in software development that helps us manage change effectively. It provides a structured way to track and communicate updates, ensuring clarity and consistency throughout the development lifecycle.

• Why apply a version to your templates?

  Applying versioning to templates ensures you can track changes, maintain consistency, and know exactly which version of your infrastructure code was used for any deployment. It supports best practices like binary promotion, simplifies troubleshooting, and helps teams coordinate updates and rollbacks with confidence.

• Why apply the version as a tag to Azure Resources?

  Tagging Azure resources with the template version gives you direct visibility into what was deployed, right from the Azure portal or API. This makes audits, governance, and troubleshooting much easier, as you can instantly see which template version created or updated a resource. It also helps correlate infrastructure changes with application releases and supports compliance requirements for traceability.

ARM templates have a Json property right at the top of the file underneath $schema called contentVersion. By default and if never changed, this will always be 1.0.0.0. As part of our versioning practice we can make sure that the templates that we deploy make use of the same version that is applied to other built artifacts. This allows us to track deployments and their respective templates through versions.

How to version templates using Azure DevOps

As part of a YAML CI/CD pipeline I typically have a build stage, with a inner Test and Version ARM Templates Job. The focus of the job is to do two things:

1. Using the az cli - Build the Bicep templates
   • I also include the Bicep linting file, this means that as the templates are being transpiled into ARM I am also getting any build errors and warnings. I output these as logissues to the Azure DevOps Pipeline for visibility.
2. Version the built ARM JSON artifacts to support Binary promotion and align with versioning practices.

I use the following tasks to complete the tasks:

1. AzureCLI@2 - used to build the Bicep templates (transpile into ARM) and log any warnings or errors.
2. VersionJSONFile@3 - used to version stamp the ARM templates.
3. CopyFiles@2 - Used to copy the versioned ARM artifacts to the staging directory.
4. PublishPipelineArtifact@1 - used to publish the ARM artifacts to the pipeline so they can be downloaded in future deployment stages.

Here is a sample YAML template:

# Yaml

...

- task: AzureCLI@2
  displayName: 'Build Bicep Files'
  inputs:
    azureSubscription: 'xxyyzz'
    scriptType: 'ps'
    scriptLocation: 'inlineScript'
    useGlobalConfig: true
    powershellerrorActionPreference: 'continue'
    inlineScript: |
      # create folder if it doesn't exist
      if (!(Test-Path -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput)) {
        New-Item -ItemType Directory -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput
      }
      write-host "Build the Bicep file"
      $output = az bicep build --file $(Build.SourcesDirectory)\{YourPath}\IAC\template.azuredeploy.bicep --outdir $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput 2>&1      
  
      write-host "Process the output"
      $output | foreach-object {
         if ($_ -match 'Error') {
            Write-Host "##vso[task.logissue type=error]$_"
         } 
         if ($_ -match 'Warning') {
             Write-Host "##vso[task.logissue type=warning]$_"
         }
      }

- task: VersionJSONFile@3
  displayName: 'Version stamp ARM templates'
  inputs:
    Path: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    recursion: True
    VersionNumber: $(Build.BuildNumber) # an example versioning option but can also be options like gitversion
    useBuildNumberDirectly: False
    VersionRegex: \d+\.\d+\.\d+\.\d+
    versionForJSONFileFormat: '{1}.{2}.{3}.{4}'
    FilenamePattern: '\w+.json'
    Field: 'contentVersion' # Versioning is applied to the templates contentVersion field
    OutputVersion: OutputedVersion

- task: CopyFiles@2
  displayName: 'Copy ARMOutput to Artifact Staging Directory'
  inputs:
    SourceFolder: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    Contents: '**/*.json'
    TargetFolder: '$(Build.ArtifactStagingDirectory)/templates'
    flattenFolders: true

- task: PublishPipelineArtifact@1
  displayName: 'Publish ARMOutput as template build artifact'
  inputs:
    targetPath: '$(Build.ArtifactStagingDirectory)/templates'
    publishLocation: 'pipeline'
    artifactName: 'ARMtemplates'

This setup ensures your ARM templates are built, versioned, and published as pipeline artifacts in a repeatable, traceable way. By stamping each template with a version number and making it available as an artifact, you enable binary promotion through environments and make it easy to track exactly which template version was used for each deployment. This improves auditability, supports rollback scenarios, and aligns with best practices for infrastructure as code in CI/CD pipelines.

How to apply the template version as a tag to Azure Resources

Versioning our ARM templates is one part of the transparency and traceability. But it would also be nice to be able to see which template version deployed the Azure Resources from the Azure Resources themselves. We can do this by applying a tag onto our resources and tying it back to our ARM contentVersion property field. We can do this by using the deployment() function as such deployment().properties.template.contentVersion.

On a resource it would look like the following:

// Bicep

resource AppService 'Microsoft.Web/sites@2024-11-01' = {
  name: appServiceName
  location: location
  tags: {
	...
    version: deployment().properties.template.contentVersion
  }
  ...
}

Applying template versioning and tagging resources with the deployed template’s version brings transparency and traceability to your Azure infrastructure. You’ll always know which version of your code and templates are running in each environment, making troubleshooting and governance much easier. These small practices help teams stay organised, reduce deployment risks, and build confidence in their automation. Happy Bicep-ing!

Modernising legacy applications is always a journey, and recently I tackled moving an existing WCF web service into Azure App Service. If you’ve worked with WCF, you’ll know the web.config file is the nerve centre, handling everything from parameters to connection strings.

But here’s the catch, this service needs to run in multiple environments (Development, Test, and Production) each with its own unique settings. That means multiple config files:

• Web.Dev.Config
• Web.Test.Config
• Web.Production.Config

The challenge

I didn’t want to build and maintain three separate web packages, one for each environment. That’s a recipe for drift and deployment headaches. Instead, I wanted a single build artifact that could be promoted through environments, swapping out only the environment-specific config as needed.

Enter web.config transformations. With these, you can:

• Keep a base web.config
• Layer on environment-specific transforms (Web.Dev.Config, etc.)

But when should the transformation happen? There are two main options, each with its own pros and cons:

1. At build time (using MSBuild):

   • The transformation is applied as part of the build process, so the output artifact already contains the environment-specific configuration.
   • This approach is simple if you only ever deploy to one environment per build, but it means you need to build a separate artifact for each environment. This breaks the principle of binary promotion, where the same artifact is promoted through Dev, Test, and Production. It also increases the risk of inconsistencies between builds.

2. At deployment (using the AzureRMWebAppDeployment@4 Azure DevOps Task):

   • The transformation is applied as part of the deployment process, allowing you to use a single, environment-agnostic build artifact and inject the correct configuration at deploy time.
   • This is the preferred approach for most modern pipelines, as it enables true binary promotion, reduces build times, and ensures that what you test is exactly what you deploy to production. It also aligns with best practices for repeatable, reliable deployments.

Solution: deploy-time transforms

Here’s how I set it up:

Build pipeline

# YAML
...

stages:
- stage: 'Build_Packages'
  jobs:
    - job: 'Build_WCFService'
      steps:

        - checkout: self
          fetchDepth: 0

        - task: VSBuild@1
          displayName: 'Build the WCF Service Solution'
          inputs:
            solution: '$(Build.SourcesDirectory)\*.sln'
            msbuildArgs: '/p:OutputPath=$(Build.ArtifactStagingDirectory)\WCFService /p:IsTransformWebConfigDisabled=true'
            platform: 'any cpu'
            vsVersion: 'latest'
            configuration: 'Release'
            clean: true

        - task: ArchiveFiles@2
          displayName: 'Archive WCF Service Build Output'
          inputs:
            rootFolderOrFile: '$(Build.ArtifactStagingDirectory)\WCFService\_PublishedWebsites\WCFService.Web'
            includeRootFolder: false
            archiveType: 'zip'
            archiveFile: '$(Build.ArtifactStagingDirectory)\WCFService\WCFService.zip'
            replaceExistingArchive: true

        - task: PublishPipelineArtifact@1
          displayName: 'Publish WCF Service Build Artifact'
          inputs:
            targetPath: '$(Build.ArtifactStagingDirectory)\WCFService\WCFService.zip'
            publishLocation: 'pipeline'
            artifactName: 'WCFService'

Release pipeline

Each environment (Dev, Test, Production) will get its own stage. The key is to ensure the correct environment name is set so the right transform is applied.

# YAML
...
- stage: 'Dev'
  displayName: 'Deploy to Dev Environment'
  variables:
  - group: 'Dev'
  dependsOn: 'Build_Packages'
  condition: succeeded()
  jobs:
    - deployment: Deploy_to_Dev
      environment: WCFServiceDev
      strategy:
        runOnce:
          deploy:
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                parameters:
                  ARMConn: 'Dev'

- stage: 'Test'
  displayName: 'Deploy to Test Environment'
  variables:
  - group: 'Test'
  dependsOn: 'Dev'
  condition: succeeded()
  jobs:
    - deployment: Deploy_to_Test
      environment: WCFServiceTest
      strategy:
        runOnce:
          deploy:
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                parameters:
                  ARMConn: 'Test'

- stage: 'Production'
  displayName: 'Deploy to Production Environment'
  variables:
  - group: 'Prod'
  dependsOn: 'Test'
  condition: succeeded()
  jobs:
    - deployment: Deploy_to_Production
      environment: WCFServiceProd
      strategy:
        runOnce:
          deploy:
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                parameters:
                  ARMConn: 'Production'

Deployment template

#YAML

steps:

  - download: current
    displayName: 'Download the wcf Service Web package'
    artifact: WCFService

  ...

  - task: AzureRMWebAppDeployment@4
    displayName: 'Deploy WCF Service Web App'
    inputs:
      ConnectionType: 'AzureRM'
      azureSubscription: ${{ parameters.ARMConn }}
      appType: 'webApp'
      WebAppName: '$(armOutput.AppServiceName)'
      Package: '$(Pipeline.Workspace)/WCFService/WCFService.zip'
      enableXmlTransform: true

Here’s the bit that tripped me up: in multi-stage pipelines, the Release.EnvironmentName variable isn’t set by default. Without it, Azure DevOps doesn’t know which transform to apply. The fix? Explicitly set the variable in each stage:

# YAML
- stage: 'Dev'
  displayName: 'Deploy to Dev Environment'
  variables:
  ...
  - name: 'Release.EnvironmentName'
    value: 'Dev'
  ...

- stage: 'Test'
  displayName: 'Deploy to Test Environment'
  variables:
  ...
  - name: 'Release.EnvironmentName'
    value: 'Test'
  ...

- stage: 'Production'
  displayName: 'Deploy to Production Environment'
  variables:
  ...
  - name: 'Release.EnvironmentName'
    value: 'Production'
  ...

Troubleshooting and tips

Common pitfalls:

• Ensure your transform files (e.g., Web.Dev.config) are included in your build artifacts. If they’re missing, check your .csproj or project file to confirm they’re marked as Content and set to Copy to Output Directory if needed.
• File names are case-sensitive on some systems, double-check spelling and casing.
• If transforms aren’t being applied, verify that the Release.EnvironmentName variable is set correctly and matches your transform file naming.

Security note: Avoid storing secrets or sensitive values directly in your config files. Use Azure Key Vault or pipeline secrets for sensitive data, and reference them via environment variables or pipeline variables where possible.

Wrapping up

With this approach, you get a single, reusable build artifact and environment-specific configuration at deployment, no more juggling multiple packages. It’s a small change that makes your pipeline cleaner and your deployments more reliable.

Hope this helps, happy deploying!

Deploying updates to production environments demands both speed and control. Azure App Service deployment slots, combined with Azure DevOps pipelines, offer a powerful way to manage releases, enabling teams to validate changes in a live-like environment before they go public. However, ensuring that only reviewed and approved changes reach your users is critical for maintaining reliability and compliance.

Azure App Service Slots unlock powerful advantages:

• Site Review. Preview and test your site before it goes live, ensuring everything works as expected.
• Warmed-up Instances. Swap with confidence. Your instances are pre-warmed, so there’s no downtime, seamless traffic redirection, and zero dropped requests.
• Instant Rollback. If something goes wrong after a swap, simply swap back to restore your last known good version in seconds.

Best of all, deployment slots come at no extra cost. Check the Azure App Service limits to see how many slots your App Service Tier supports.

Automatic vs. Manual Slot Swaps

When it comes to swapping slots, there are two main approaches: automatic and manual.

• Automatic swaps are ideal when you want to quickly promote changes without a review, while still benefiting from pre-warmed instances and instant rollback.
• Manual swaps give you the opportunity to review and verify your site before it goes live, adding an extra layer of confidence.

But how do you keep a manual swap process governed and controlled? That’s where Azure DevOps pipelines and approvals come in.

In this article, you’ll learn how to set up a robust, approval-driven slot swap process in Azure DevOps.

Defining Azure Resources with Bicep

First, we need to define the resources needed in Azure. To do this I am going to use Infrastructure as Code (IaC). The template shown below creates the following resources:

• App Service Plan.
• App Service linked to the App Service Plan
  • Sub Resource that defines the App Service App Settings
• App Service Deployment Slot. Only created for Production environments - this is enforced through a conditional on the resource

Bicep Template: App Service and Deployment Slot

// Bicep

/**********************************
Bicep Template: App Service Deploy
Author: Andrew Wilson
***********************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

@description('Org Project Name')
param projectName string

@description('Application Name sitting within the project')
param applicationName string

@description('location name')
param location string = resourceGroup().location

@description('Environment name')
param env string = 'dev'

@description('App Service Plan sku name')
param appServicePlanSkuName string

@description('App Service Plan sku tier')
param appServicePlanSkuTier string

@description('Name of the deployment slot')
param deploymentSlotName string = 'staging'

// ** Variables **
// ***************

var appServicePlanName string = 'asp-${applicationName}-${env}-${location}'
var appServiceName string = 'app-${applicationName}-${env}-${location}'

// ** Resources **
// ***************

@description('Deploy an Azure App Service Plan')
resource AppServicePlan 'Microsoft.Web/serverfarms@2024-11-01' = {
  name: appServicePlanName
  location: location
  tags: {
    project: projectName
    application: applicationName
    environment: env
    version: deployment().properties.template.contentVersion
  }
  sku: {
    name: appServicePlanSkuName
    tier: appServicePlanSkuTier
  }
}

@description('Deploy an Azure App Service')
resource AppService 'Microsoft.Web/sites@2024-11-01' = {
  name: appServiceName
  location: location
  tags: {
    project: projectName
    application: applicationName
    environment: env
    version: deployment().properties.template.contentVersion
  }
  properties: {
    serverFarmId: AppServicePlan.id
    httpsOnly: true
  }
  resource AppServiceAppSettings 'config@2024-11-01' = {
    name: 'appsettings'
    properties: {
      ...
    }
  }  
}

@description('Deploy a deployment slot for the App Service')
resource deploymentSlot 'Microsoft.Web/sites/slots@2024-11-01' = if (env == 'prod') {
  name: deploymentSlotName
  parent: AppService
  location: location
  tags: {
    project: projectName
    application: applicationName
    environment: env
    version: deployment().properties.template.contentVersion
  }
  properties: { }
}

// ** Outputs **
// *************

@description('Outputs the App Service Name')
output appServiceName string = appServiceName

Important Note: Avoiding AutoSwap for Manual Swaps

Make sure that the DeploymentSlot resource does not have AutoSwap setup as this will counteract when Manual Swap is used. Such that the following process would be observed:

1. Deploy to Staging slot.
2. AutoSwap kicks in and swaps Staging with Production.
3. After Manual Approval, Slots are swapped again
4. You are now in the originating position with the new site still in Staging and Production with the old.

Designing the Azure DevOps Pipeline

Next we will setup our Azure DevOps Yaml pipeline. The pipeline’s goal is to orchestrate artifact building and environment deployments while adhering to DevOps best practices, such as binary promotion.

Pipeline Stages Explained

The pipeline has the following stages:

1. Build_Packages. Build a single set of artifacts that have been tested and versioned. (Best practice of Binary Promotion)

   The stage has two jobs to handle both Azure Bicep Templates and the App Service Web Package.

2. Development. Deploy to the Development Environment using an environment agnostic pipeline template*.

3. Staging. Deploy to the Staging Environment using an environment agnostic pipeline template*.

4. Production. Deploy to the Production Environment using an environment agnostic pipeline template*.

*The environment agnostic pipeline template is a reusable template for all environments.

Pipeline YAML: Build and Environment Deployments

# Yaml
# Orchestrating Template: Build And Environment Deployments

...

stages:
- stage: 'Build_Packages'
  jobs:
    - job: 'Test_Build_And_Version_Bicep_Templates'
      steps:

        ...

        - task: PublishPipelineArtifact@1
          displayName: 'Publish ARMOutput as template build artifact'
          inputs:
            targetPath: '$(Build.ArtifactStagingDirectory)/templates'
            publishLocation: 'pipeline'
            artifactName: 'ARMtemplates'

    - job: 'Build_and_Version_AppService'
      steps:

		...

        - task: PublishPipelineArtifact@1
          displayName: 'Publish App Service Build Artifact'
          inputs:
            targetPath: '$(Build.ArtifactStagingDirectory)/AppService.zip'
            publishLocation: 'pipeline'
            artifactName: 'AppService'


- stage: 'Development'
  displayName: 'Deploy to Dev Environment'
  ...
  jobs:
    - deployment: Deploy_to_Dev
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...

- stage: 'Staging'
  displayName: 'Deploy to Staging Environment'
  ...
  jobs:
    - deployment: Deploy_to_Staging
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...

- stage: 'Production'
  displayName: 'Deploy to Production Environment'
  ...
  jobs:
    - deployment: Deploy_to_Production
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...

Once the Build_Packages stage has completed successfully, we now have two pipeline artifacts, ARMtemplates and AppService. In each environment deploy these two artifacts will be downloaded and used alongside environment specific Library Variable Groups to create specific environment deployments.

Environment-Agnostic Deployment Template

The environment agnostic template is shown below and has the following steps:

1. Artifact Downloads. Downloads the two pipeline artifacts, ARMtemplates and AppService.
2. Azure Resource Group Deployment. Using the built ARM template, specific environment library variable group and ARM Connection.
3. Custom PowerShell Script to Obtain Azure Deployment Outputs. Deployment output such as appServiceName will be created as job variables ready for future tasks to access.
4. Azure Web App Deploy (Specific for Dev and Staging). This task deploys straight to the production slot for non production environments.
5. Azure Web App Deploy (Specific for Prod). This task deploys to the staging slot ready for a manual slot swap.

Pipeline YAML Template: Reusable Environment-Agnostic Deployments

# Yaml
# Environment Deploy Template: Deploy Azure Resources and Obtain Outputs, Deploy App Service

steps:

  - download: current
    displayName: 'Download ARM templates'
    artifact: ARMtemplates

  - download: current
    displayName: 'Download the App Service Web package'
    artifact: AppService

  - task: AzureResourceManagerTemplateDeployment@3
    displayName: 'Deploy App Service ARM template'
    inputs:
      deploymentScope: 'Resource Group'
      azureResourceManagerConnection: ${{ parameters.ARMConn}}
      subscriptionId: '$(subscriptionId)'
      action: 'Create Or Update Resource Group'
      resourceGroupName: '$(resourceGroupName)'
      location: '$(location)'
      templateLocation: 'Linked artifact'
      csmFile: '$(Pipeline.Workspace)/ARMtemplates/AppService.azuredeploy.json'
      deploymentMode: 'Incremental'
      deploymentOutputs: deploymentOutputs
      overrideParameters: >-
        ...        

  - task: PowerShell@2
    name: armOutput
    displayName: 'Obtain Azure Deployment outputs'
    inputs:
      targetType: 'inline'
      script: |
        if (![string]::IsNullOrEmpty( '$(deploymentOutputs)' )) {
          $DeploymentOutputs = convertfrom-json '$(deploymentOutputs)'

          $DeploymentOutputs.PSObject.Properties | ForEach-Object {
              $keyname = $_.Name
              $value = $_.Value.value
              Write-Host "The value of [$keyName] is [$value]"
              Write-Host "##vso[task.setvariable variable=$keyname;isOutput=true]$value"
          }
        }        

  - task: AzureWebApp@1
    displayName: 'Deploy App Service - Dev and Staging Environment Only'
    condition: ne(variables['env'], 'prod')
    inputs:
      azureSubscription: ${{ parameters.ARMConn }}
      appType: 'webApp'
      appName: '$(armOutput.appServiceName)'
      package: '$(Pipeline.Workspace)/AppService/AppService.zip'

  - task: AzureWebApp@1
    displayName: 'Deploy App Service to Staging Slot - Prod Environment Only'
    condition: eq(variables['env'], 'prod')
    inputs:
      azureSubscription: ${{ parameters.ARMConn }}
      appType: 'webApp'
      appName: '$(armOutput.appServiceName)'
      deployToSlotOrASE: true
      resourceGroupName: '$(resourceGroupName)'
      slotName: '$(slotName)'
      package: '$(Pipeline.Workspace)/AppService/AppService.zip'

Accessing ARM Output Variables Across Jobs

Given that I will also need to access the appServiceName ARM Output that has been outputted from the armOutput task as a variable in future jobs, I have used the Output Variable for use in future jobs configuration.

Rather than job only:

##vso[task.setvariable variable=$keyname]$value

It uses the IsOutput so we can setup dependencies and access later:

##vso[task.setvariable variable=$keyname;isOutput=true]$value

Note: Accessing a Output Variable is different to a non-output variable:

Non-output Variable: '$(appServiceName)'

Output Variable: '$(armOutput.appServiceName)', you will need to reference the task name prior to the variable.

Manual Slot Swap with Azure DevOps Approvals

At this point, we now have our App Service resources deployed and the Site deployed to the production slots for Dev and Staging, and deployed to the Staging slot for Production.

But now down to the real question, how do I manually swap the slots using some Azure DevOps governance goodness?

To do this we are going to use the Azure DevOps Environment Approvals which will allow specific groups or users to approve the slot swap. Following this we will use the AzureAppServiceManage@0 task to conduct the slot swap.

Setting Up Azure DevOps Environments and Approvals

To setup an environment and approvals:

1. Sign in to your Azure DevOps organisation and open your project.
2. Select Pipelines > Environments > Create Environment.
3. Enter information for the environment, and then select Create. (For our purposes leave Resource as None)
4. In your Environment, Select Approvals and checks tab, and then select the + sign to add a new check.
5. Select Approvals, and then select Next.
6. Add users or groups as your designated Approvers, and if desired the following
   1. Instructions to approvers
   2. Allow approvers to approve their own runs
7. Make sure to Save.

Environments can be assigned to stages and jobs, but not to individual tasks. This means the slot swap task cannot reside within the environment-agnostic deployment template; it must be a separate, follow-on job.

To cater for the slot swap and environment approval, we are going to amend the orchestrating template to add another Job after the deployment Job in the Production deploy stage. This is shown below.

Adding the Slot Swap Job to the Pipeline

# Yaml
# Orchestrating Template: Build And Environment Deployments

...

- stage: 'Production'
  ...
  jobs:
    - deployment: Deploy_to_Production
      ...
            steps:
              - template: EnvironmentDeploy.azurepipelinetemplate.yml
                ...
    
    - deployment: Slot_Swap_to_Production
      dependsOn: Deploy_to_Production
      condition: succeeded()
      environment: ProductionEnv
      variables:
        appServiceName: $[ dependencies.Deploy_to_Production.outputs['Deploy_to_Production.armOutput.appServiceName'] ]
      strategy:
        runOnce:
          deploy:
            steps:
              - task: AzureAppServiceManage@0
                displayName: 'Swap App Service Staging Slot to Production'
                inputs:
                  azureSubscription: 'XXXYYYZZZ'
                  action: 'Swap Slots'
                  WebAppName: '$(appServiceName)'
                  ResourceGroupName: '$(resourceGroupName)'
                  SourceSlot: '$(slotName)'
                  SwapWithProduction: true

As can be seen in the amended template above, the Slot_Swap_to_Production job runs after the Deploy_to_Production job and expects it to have succeeded as a condition to running. The Slot_Swap_to_Production job also references the environment ProductionEnv for Approval prior to running.

Note: The first time the environment is used on the pipeline, the pipeline will ask for permission to use the resource.

Referencing Output Variables in the Slot Swap Job

The Azure App Service Manage task requires the WebAppName, which is set as an output variable in the environment-agnostic YAML pipeline template. To use this value in the Slot_Swap_to_Production job, define a new variable that references the output variable from the previous job. Once defined, you can use it within the current job as a standard variable (e.g., $(appServiceName)).

The variable reference uses the following syntax:

[dependencies.JobName.outputs[’JobName.TaskName.VariableName]]

You now have a pipeline that at the point of the slot swap job will wait for an appropriate approval prior to running and swapping your staging slot to production.

Summary

By combining Azure App Service deployment slots, Infrastructure as Code, and Azure DevOps environment approvals, you can create a robust, auditable deployment pipeline. This approach ensures that production releases are gated by manual approval, reducing risk and enabling rapid rollback if needed.

Ready to take your deployments to the next level? Try setting up manual slot swaps with approvals in your next release pipeline, and let your team experience stress-free, governed production launches.

Versioning is the unsung hero of software development—often overlooked but absolutely essential. Imagine trying to manage a project without a clear way to track changes, communicate updates, or ensure compatibility. Chaos, right? That’s where versioning steps in, providing structure and clarity.

In this post, I’ll share how I streamline versioning in my projects by combining the power of Semantic Versioning (SemVer) with GitVersion, an automation tool that eliminates the manual effort of version management. Whether you’re just beginning your journey or tackling the complexities of feature-rich projects, this post will show you how to automate semantic versioning in Azure DevOps for consistency, traceability, and peace of mind.

Why Version?

Versioning is a fundamental practice in software development that helps us manage change effectively. It provides a structured way to track and communicate updates, ensuring clarity and consistency throughout the development lifecycle.

What is Semantic Versioning?

Semantic Versioning (often abbreviated as SemVer) is a versioning scheme that provides a standardised way to communicate the nature of changes in a software release. It uses a three-part version number format: MAJOR.MINOR.PATCH, where each part conveys specific information about the release.

Breakdown of Semantic Versioning:

1. MAJOR Version: Incremented when there are breaking changes that are incompatible with previous versions.

   • Example: 1.0.0 → 2.0.0

2. MINOR Version: Incremented when new features are added in a backward-compatible manner.

   • Example: 1.0.0 → 1.1.0

3. PATCH Version: Incremented when backward-compatible bug fixes or small improvements are made.

   • Example: 1.0.0 → 1.0.1

Benefits of Semantic Versioning:

• Clarity: It clearly communicates the scope and impact of changes to users and developers.
• Predictability: Helps teams and users understand what to expect from a new release.
• Dependency Management: Makes it easier to specify compatible versions of libraries or APIs.
• Automation: Tools like GitVersion can automate the generation of semantic versions in CI/CD pipelines, ensuring consistency and reducing manual effort.

Versioning with GitVersion

GitVersion is an open source tool that can be used to automate semantic versioning by analysing our Git repository’s history. It streamlines the versioning process, ensuring consistency and reducing manual errors.

GitVersion has the following key features:

• Semantic Versioning (SemVer): Automatically calculates version numbers based on Git history, adhering to SemVer principles.
• Branching Strategy Support: Compatible with Continuous Delivery, GitFlow, GitHub Flow, and Mainline development workflows.
• Continuous Integration (CI) Friendly: Integrates seamlessly with CI/CD pipelines, generating version numbers for builds and releases.
• Flexible Configuration: Highly configurable to suit various project needs and versioning schemes.

GitVersion Configuration

GitVersion uses a configuration file (GitVersion.yml) to define how version numbers are calculated based on your Git repository’s history and branching strategy. This file allows us to customise the behaviour of GitVersion to suit our project’s needs.

How I Branch and Configure GitVersion for Projects

My projects tend to use the following setup:

• Continuous Delivery Branch Model. This model has the following features:
  • Main branch as release-ready: The main branch is always in a deployable state.
  • Frequent Deployments: Changes are deployed to production or staging environments frequently, often automatically.
  • Short-Lived Feature Branches: Feature branches are merged into main after review and testing.
  • Automated Pipelines: CI/CD pipelines handle building, testing, and deploying changes seamlessly.
• SemVer is incremented using the following strategies:
  • TaggedCommit. This strategy uses Git tags to determine the version. If a commit is tagged with a semantic version (e.g., 1.0.0), GitVersion will use that tag as the base for calculating the next version.
  • Fallback. This strategy is used when no other versioning information (e.g., tags or branch-specific rules) is available. It serves as a default versioning mechanism, especially for newly initiated projects.
• Two defined branches for GitVersion increments:

GitConfig Setup

The described GitVersion configuration looks like the following:

## YAML
strategies:
- TaggedCommit
- Fallback
branches:
   main:
      increment: Minor
      prevent-increment:
         when-current-commit-tagged: true
   pull-request:
      increment: Patch
      prevent-increment:
         when-current-commit-tagged: true

Azure DevOps CI/CD Pipeline Setup

The CI/CD pipeline would be configured as shown below:

## YAML
name: $(Build.DefinitionName)_$(GitVersion.FullSemVer)

trigger:
  branches:
    include: [ main ] # branch names which will trigger a build

pr: # will trigger on PR
  branches:
    include: [ main ] # branch names which will trigger a build.

variables:
  - name: Source_Branch_Ref
    value: $[replace(coalesce(variables['System.PullRequest.SourceBranch'], variables['Build.SourceBranch']), 'refs/heads/', '')]

resources:
  repositories:
    - repository: Source_Branch
      type: git
      name: GitVersionSemVerWithTags
      ref: "$(Source_Branch_Ref)"

stages:
  - stage: 'Build_Packages'
    jobs:
      - job: 'Increment_Version'
        condition: and(succeeded(), or(eq(variables['Build.Reason'], 'PullRequest'), and(eq(variables['Build.SourceBranch'], 'refs/heads/main'), ne(variables['Build.Reason'], 'Manual'))))
        pool:
          vmImage: 'windows-latest'
        steps:

        - checkout: Source_Branch
          persistCredentials: true
          fetchTags: true
          fetchDepth: 0 # Ensure we fetch all Git history for Semver

        - task: gitversion/setup@3
          displayName: 'Get current version of GitVersion'
          inputs:
            versionSpec: '6.0.x'

        - task: gitversion/execute@3
          displayName: 'Run GitVersion to generate SEMVER'
          inputs:
            targetPath: '$(Build.SourcesDirectory)\'
            useConfigFile: true
            configFilePath: '$(Build.SourcesDirectory)\GitVersion.yml'

        - task: PowerShell@2
          displayName: 'Increment the Version using Git Tag'
          inputs:
            targetType: 'inline'
            script: |
              cd '$(Build.SourcesDirectory)'
              git config --global user.email "$(Build.RequestedForEmail)"
              git config --global user.name "$(Build.RequestedFor)"
              git tag -a "$(GitVersion.MajorMinorPatch)" -m "Released by $(Build.RequestedFor)"
              git push origin tag "$(GitVersion.MajorMinorPatch)"              

Key Steps in the Pipeline

1. Pipeline Name: Combines the build definition name with the full semantic version: $(Build.DefinitionName)_$(GitVersion.FullSemVer).
2. Trigger: Builds are triggered on changes to the main branch.
3. Pull Request Trigger: Builds are triggered on pull requests targeting the main branch.
4. Variables: Defines Source_Branch_Ref to extract the source branch reference for the build or pull request.
5. Resources: Dynamically sets the branch reference for the Git repository (Source_Branch) to $(Source_Branch_Ref).
6. Job: Increment_Version: Executes if the build succeeds and is triggered by a pull request or the main branch but not part of a Manual Trigger.
7. Checkout: Checks out the Source_Branch repository with full Git history and tags for versioning.
8. GitVersion Setup: Installs GitVersion (6.0.x) to calculate semantic versions.
9. GitVersion Execute: Runs GitVersion using the GitVersion.yml configuration file to generate the semantic version.
10. PowerShell Script:
    • Configures Git by setting the user email and name to match the build requester.
    • Creates or updates a Git tag with the calculated version ($(GitVersion.MajorMinorPatch)).
    • Pushes the tag to the remote repository, ensuring the version is recorded.

⚠️ Important Note
The Source_Branch_Ref variable and resource in this pipeline are configured as shown above because pull requests (PRs) create their own Git branches which are a merger of the source branch and main. When tags are created during the pipeline execution, they are placed on the PR branch by default, not the source branch where GitVersion calculates automatic increments.
By setting up the Source_Branch_Ref variable and dynamically referencing the source branch in the resources section, the tag is placed on the source branch instead of the PR branch. This ensures that version increments are correctly applied to the source branch, maintaining accurate semantic versioning.
The PR branch should still be used for building and validating solution artifacts.

⚠️ Important Pipeline Permissions
The Azure DevOps [Project] Build Service must have the following Repository Permissions:

• Contribute: Permission to push changes to the repository.
• Create Tag: Permission to create and update tags in the repository.

Using GitVersion to Version Artifacts

Versioning artifacts involves two phases:

1. Generate a semantic version to use. This can be achieved by leveraging the GitVersion task.
2. Applying the sematic version to artifacts. This can be achieved by using a task such as VersionJSONFile@3.

As an example, when working with ARM templates in Azure, it’s important to version your artifacts for traceability and consistency. Using GitVersion in your Azure DevOps pipeline, you can generate a semantic version and apply it to the contentVersion field of your ARM template. This guarantees that each deployment is uniquely identifiable.

## YAML
      - job: 'Test_and_VersionBicepTemplates'
        pool:
          vmImage: 'windows-latest'
        steps:
        - checkout: self
          path: './s/selfBranch/'
          persistCredentials: true
          fetchTags: true
          fetchDepth: 0 # Ensure we fetch all Git history for Semver

        - checkout: Source_Branch
          path: './s/versionBranch/'
          persistCredentials: true
          fetchTags: true
          fetchDepth: 0 # Ensure we fetch all Git history for Semver

        # GitVersion task is needed in each job where the variables are referenced
        - task: gitversion/setup@3
          displayName: 'Get current version of GitVersion'
          inputs:
            versionSpec: '6.0.x'

        - task: gitversion/execute@3
          displayName: 'Run GitVersion to generate SEMVER'
          inputs:
            targetPath: '$(System.DefaultWorkingDirectory)/versionBranch/'
            useConfigFile: true
            configFilePath: '$(System.DefaultWorkingDirectory)/versionBranch/GitVersion.yml'

        - task: BicepInstall@0
          inputs:
            version: 0.35.1

        - task: BicepBuild@0
          inputs:
            process: "single"
            sourceFile: '$(Build.SourcesDirectory)\selfBranch\Deployment\azuredeploy.bicep'
            stdout: false
            outputFile: '$(Build.ArtifactStagingDirectory)\ARMOutput\azuredeploy.json'

        - task: VersionJSONFile@3
          displayName: 'Version stamp ARM templates'
          inputs:
            Path: '$(Build.ArtifactStagingDirectory)\ARMOutput'
            recursion: true
            VersionNumber: '$(GitVersion.AssemblySemFileVer)'
            useBuildNumberDirectly: False
            VersionRegex: '\d+\.\d+\.\d+\.\d+'
            versionForJSONFileFormat: '{1}.{2}.{3}.{4}'
            FilenamePattern: '\w+.json'
            Field: 'contentVersion'
            OutputVersion: 'OutputedVersion'

        - task: PublishPipelineArtifact@1
          displayName: 'Publish Versioned Solution Templates build artefact'
          inputs:
            targetPath: "$(Build.ArtifactStagingDirectory)/ARMOutput"
            publishLocation: "pipeline"
            artifactName: "ARM-Templates"

Key Steps in the Pipeline

1. Checkout Repositories

   • The pipeline checks out two branches:
     • Self Branch: Contains the Bicep files that will be compiled into ARM templates.
     • Source Branch: Used for versioning and fetching Git history.
   • Full Git history and tags are fetched (fetchTags: true, fetchDepth: 0) to ensure accurate semantic version calculation.

2. Generate Semantic Version with GitVersion

   • GitVersion Setup: The gitversion/setup@3 task installs GitVersion (6.0.x).
   • GitVersion Execution: The gitversion/execute@3 task calculates the semantic version based on the repository’s history and configuration (GitVersion.yml).
     • The version is exposed as pipeline variables, such as $(GitVersion.AssemblySemFileVer).

3. Build ARM Templates

   • The BicepBuild task compiles the Bicep file (azuredeploy.bicep) into an ARM template (azuredeploy.json).
   • The compiled ARM template is stored in the $(Build.ArtifactStagingDirectory)/ARMOutput directory.

4. Version Stamp the ARM Template

   • The VersionJSONFile task updates the contentVersion field in the ARM template (azuredeploy.json) with the semantic version generated by GitVersion.
     • Inputs:
       • VersionNumber: Uses $(GitVersion.AssemblySemFileVer) (Provides a 4-digit version format (MAJOR.MINOR.PATCH.0), which is ideal for ARM template versioning e.g., 1.2.3.0).
       • Field: Specifies the contentVersion field in the ARM template to be updated.
       • VersionRegex: Ensures only valid version formats (\d+\.\d+\.\d+\.\d+) are replaced.
     • This step ensures that the ARM template is uniquely versioned for traceability.

5. Publish the Versioned ARM Template

   • The PublishPipelineArtifact task publishes the versioned ARM template as a pipeline artifact.
     • The artifact is stored under the name ARM-Templates and can be used in subsequent deployment stages.

Summary

Automating semantic versioning in Azure DevOps CI/CD pipelines with GitVersion is a game-changer for maintaining consistency, traceability, and efficiency in your development workflow. By leveraging tools like GitVersion, you can eliminate the manual effort of version management, ensure accurate versioning across branches, and streamline the deployment of versioned artifacts like ARM templates.

Whether you’re managing simple projects or complex, feature-rich solutions, adopting semantic versioning practices ensures that your team and stakeholders have a clear understanding of changes, compatibility, and release impact. With the strategies and pipeline configurations shared in this post, you’re now equipped to implement a robust versioning system that aligns with industry best practices.

If you found this post useful, consider sharing it with your team or network to help others streamline their versioning workflows. Happy automating!

One of my recent projects has involved the use of a static module bundler called webpack to bundle a typescript site so I can serve static content from a Static Web App in Azure.

For a while now the site content has not deviated between environments [ dev / test / prod ] and therefore we have simply built and bundled the site for deployment.

Recent changes however have required that there be some deviation between environments, at which point the question raised, at what point should this deviation be set or retrieved?

const someConfigurationSetup = "Static but deviates between environments";
const someConfigurationSetupPartTwo = "Static but deviates between environments";

Due to the site having a backing Azure Function serving its API calls, I had two available options:

1. Is the deviation something that should be served at runtime?

   Points to the Azure Function APIs.

2. Is the deviation something that should be baked in at build time?

   Points to the webpack bundler.

The deviation in this case does not change throughout the running of the site and also has no security constraints preventing the deviation from being served as static content. My choice therefore proceeded with the second option: webpack bundler.

But how do I achieve this with the webpack bundler? I have a Azure DevOps CI/CD Yaml pipeline that builds and packages the site using npm and the webpack bundler ready for the environment deployments. What is the most appropriate method that will fit in with my current methods?

Solution

After some digging, I came across the webpack EnvironmentPlugin. The use of the Environment Plugin allows me to specify environment variables within my typescript that will then be resolved by the webpack bundler at build time.

This changes the typescript shown above to the following:

const someConfigurationSetup = process.env.CONFIG_SETUP_ONE;
const someConfigurationSetupPartTwo = process.env.CONFIG_SETUP_TWO;

By default if process.env.VARIABLE is not defined by your webpack.config.js, you will receive a ReferenceError: process is not defined.

Defining the environment variables in the webpack.config.js is done within the plugins section such as the following:

module.exports = async (env, options) => {

  const config = [
    {
      devtool: ...
      entry: {
        ...
      },
      resolve: {
        ...
      },
      module: {
        rules: [
          ...
        ],
      },
      plugins: [
        new DefinePlugin({
          'process.env.CONFIG_SETUP_ONE': JSON.stringify(process.env.CONFIG_SETUP_ONE),
          'process.env.CONFIG_SETUP_TWO': JSON.stringify(process.env.CONFIG_SETUP_TWO),
        }),
        ...
      ],
    },
    {
	...
    }
  ];

  return config;
};

With the plugin and variables defined, the webpack bundler will now resolve my variables with any environment variables defined through methods such as:

1. Setting through PowerShell (environment variable setup will differ per scripting language):

   $env:CONFIG_SETUP_ONE = ""
   $env:CONFIG_SETUP_TWO = ""
   npm run build
   

2. Setting through .env file

If no environment variables are found, the variable resolve will result in one of the following:

1. undefined for variables that must be provided during bundling.
2. null if they are optional.

In my case I would like the variables to be resolved within my Azure DevOps Yaml CI/CD Pipeline for the respective environment.

Thankfully, not much work was required here from my part. I am already making use of Library Variable Groups within my pipeline for the respective environment stages. In DevOps pipelines, variables are made available to scripts and tasks through environment variables such as the one I configured: CONFIG_SETUP_ONE. This has resulted in no change to the existing yaml task for the resolve to work:

      - job: 'Build_Test_Solution'
        pool:
          vmImage: windows-latest
        variables:
          - group: Dev # Holds the Environment Variables such as CONFIG_SETUP_ONE, CONFIG_SETUP_TWO
        steps:

          - task: Npm@1
            displayName: npm install
            inputs:
              workingDir: '$(System.DefaultWorkingDirectory)/Project'
              verbose: false

          - task: Npm@1
            displayName: npm run build for test environment
            inputs:
              command: custom
              workingDir: '$(System.DefaultWorkingDirectory)/Project'
              verbose: false
              customCommand: run build

Hope this helps, and have fun.

I have been recently working on building a new Yaml pipeline in Azure DevOps and wished to use the GitVersion Task, however, upon running the pipeline the task failed with the following error:

ERROR [../../.. ..:..:..:..] An unexpected error occurred:
System.NullReferenceException: Object reference not set to an instance of an object.

After some digging and a conversation with one of my colleagues, it turns out there has been a change on Azure DevOps pipelines. By default now when a pipeline is created, the ‘Get Sources’ Shallow fetch setting is enabled and set to a depth of 1.

The Shallow fetch setting if enabled will limit how far back in source history to download. Effectively using the following git command git fetch --depth=n.

This in turn causes the error seen above as the GitVersion task requires the whole repo branching model to calculate the SEMVER version.

Switching off Shallow Fetch

To switch off Shallow Fetch if using a Yaml pipeline:

1. Edit your Pipeline.
2. Selecting the ellipsis button, select Triggers.
3. Navigate to the Yaml tab, and select Get Sources.
4. There is a setting near the very bottom called Shallow fetch, switch the setting off and save.