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.
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.
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.
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.
# 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)"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.
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"
}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.
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.