Azure DevOps: deploy to on-premises IIS and verify rollback

Deploy a release to IIS using Azure Pipelines, a self-hosted agent, approval, an HTTPS probe and verifiable rollback.

01

An end-to-end deployment to one pilot server

Fictional Boreal Workshop deploys a static page on IIS. The pipeline builds once, publishes an artifact, waits for approval, then verifies that the server serves the exact new version. A static page keeps the example reproducible: a real application also needs dependency checks and a business transaction. This example targets Azure DevOps Services even though IIS is on-premises.

02

1. Prepare the scope before connecting an agent

Use a dedicated IIS pilot server, supported Windows Server and Windows agent releases, and PowerShell 7. Set up an HTTPS site with a trusted certificate for iis-pilot.atelier.example and an existing index.html. In your lab replace the fictional name with one that resolves directly to the pilot, with no caching or redirection. Pre-create D:\Sites\IisDemo and D:\DeployState\IisDemo on the same NTFS volume; keep the latter outside the web root. Grant the agent service account Modify only on those folders; give IIS its required read access. Give the agent neither domain administration nor production access. Check current agent requirements and parallel-job capacity for both hosted and self-hosted pools. The sample’s Pipeline Artifacts tasks are specific to Services; for Azure DevOps Server, verify compatible tasks and pools.

03

2. Separate build from deployment

The Microsoft-hosted pool packages the artifact. The iis-pilot-only pool contains only the agent installed on the pilot server, with outbound HTTPS per Microsoft requirements; Azure DevOps does not need to initiate inbound connections to the agent. Restrict pool and environment use to the authorized pipeline. Protect main through review and build validation, restrict policy-editing rights, and configure manual approval and an exclusive lock on iis-pilot in the UI. Add protected branch control on the resource where available. A YAML condition alone is not a security boundary. Never run an unapproved PR on the deployment pool.

04

3. Create the three repository files

Put YAML at the root, the script at deploy/Deploy-IisDemo.ps1 and a dependency-free page at web/index.html. Minimal content: <!doctype html><title>IIS Demo</title><p>__RELEASE__</p>. Package substitutes the build identifier and bundles the page and script from the same commit. Pilot downloads only the artifact from the current run and does not check out the repo. Runs are manual; use separate, non-deploying PR validation. Retain approved runs according to your retention policy so deployed versions remain traceable.

YAML
# Azure DevOps Services. Run manually from protected main.
trigger: none
stages:
- stage: Package
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
  jobs:
  - job: BuildDemo
    pool:
      vmImage: windows-latest
    steps:
    - checkout: self
      persistCredentials: false
    - pwsh: |
        $page = Get-Content -Raw web/index.html
        if (-not $page.Contains('__RELEASE__')) { throw 'Missing release marker' }
        $out = New-Item -ItemType Directory -Force '$(Build.ArtifactStagingDirectory)/iis'
        $page.Replace('__RELEASE__', 'release-$(Build.BuildId)') |
          Set-Content -Encoding utf8 (Join-Path $out.FullName 'index.html')
        Copy-Item deploy/Deploy-IisDemo.ps1 $out.FullName
      displayName: Package the approved commit
    - publish: $(Build.ArtifactStagingDirectory)/iis
      artifact: iis-demo
- stage: Pilot
  dependsOn: Package
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
  jobs:
  - deployment: DeployIisPilot
    environment: iis-pilot
    pool:
      name: iis-pilot-only
    workspace:
      clean: all
    strategy:
      runOnce:
        deploy:
          steps:
          - checkout: none
          - download: none
          - download: current
            artifact: iis-demo
          - task: PowerShell@2
            displayName: Deploy and verify the pilot
            inputs:
              pwsh: true
              targetType: filePath
              filePath: $(Pipeline.Workspace)/iis-demo/Deploy-IisDemo.ps1
              arguments: -ArtifactPath "$(Pipeline.Workspace)/iis-demo/index.html" -BuildId "$(Build.BuildId)"
05

4. Deploy one file and verify the HTTPS result

This script changes the pilot. It stops if the HTTPS response differs from the currently served file, validates the artifact marker, then replaces the file while keeping a previous copy outside the web root. The probe compares content without suppressing TLS errors. If validation fails after replacement, the script restores the previous file and checks its response; the pipeline fails even after successful rollback to prevent promotion. If the agent stops or replacement is incomplete, inspect the live file, backup and response before any manual retry.

PowerShell
param(
    [Parameter(Mandatory)] [string] $ArtifactPath,
    [Parameter(Mandatory)] [ValidatePattern('^\d+$')] [string] $BuildId
)
$ErrorActionPreference = 'Stop'
# Preconfigured paths on the same NTFS volume. No IIS config changes.
$live = 'D:\Sites\IisDemo\index.html'
$work = 'D:\DeployState\IisDemo'
$uri = 'https://iis-pilot.atelier.example/index.html'
$id = [guid]::NewGuid().ToString('N')
$next = Join-Path $work "$id.next"
$backup = Join-Path $work "$id.previous"
$failed = Join-Path $work "$id.failed"

function Read-Page {
    $r = Invoke-WebRequest -Uri $uri -TimeoutSec 10 -MaximumRedirection 0
    if ($r.StatusCode -ne 200) { throw "Unexpected HTTP status: $($r.StatusCode)" }
    return ([string]$r.Content).Trim()
}

# Refuse deployment if IIS is already unhealthy or serves another copy.
$old = [IO.File]::ReadAllText($live).Trim()
if ((Read-Page) -cne $old) { throw 'Live file does not match the HTTPS response' }
Copy-Item -LiteralPath $ArtifactPath -Destination $next
$new = [IO.File]::ReadAllText($next).Trim()
if (-not $new.Contains("release-$BuildId<")) { throw 'Artifact version mismatch' }

$swapped = $false
try {
    [IO.File]::Replace($next, $live, $backup)
    $swapped = $true
    if ((Read-Page) -cne $new) { throw 'HTTPS response differs from the artifact' }
    Write-Host "Release $BuildId verified; previous file: $backup"
} catch {
    $cause = $_
    if (-not $swapped) {
        throw "Replacement did not complete; inspect live and staging files before retrying: $cause"
    }
    try {
        [IO.File]::Replace($backup, $live, $failed)
        if ((Read-Page) -cne $old) { throw 'Previous HTTPS response was not restored' }
    } catch {
        throw "Deployment and rollback verification failed. Stop the rollout. Deploy: $cause; rollback: $_"
    }
    throw "Deployment failed; previous page restored and verified. Cause: $cause"
}
06

5. Test success and a controlled failure

In a disposable lab, approve a run from main. Confirm that the log identifies the release and that the HTTPS URL returns its marker. To exercise rollback without changing networking or certificates, temporarily add a throw immediately after $swapped = $true on main in a separate lab repository, using a lab-only pipeline, pool, environment and checks. Expect a failed run and the previous content still being served. Remove the injection after testing. If rollback validation fails, stop promotion and use the retained copy and log; do not blindly rerun.

07

6. Adapt before deploying a real application

For multi-file IIS deployments, use version directories and a switch procedure appropriate to the framework; this file replacement does not cover locked files, SQL migrations or external side effects. Use readiness and business read checks in preproduction, then promote the same approved artifact without rebuilding it. For SQL, validate compatibility between both application versions and separate irreversible migrations. Agree on stop criteria, version retention and the emergency procedure with the service owner. An infrastructure assessment can complement this pilot.

08

Official documentation