Automate Multi‑Environment Deployments with Azure DevOps YAML Pipelines

What You’ll Achieve

By the end of this guide you will have a single, version‑controlled YAML pipeline that builds your code once, publishes an artifact, and deploys it to Dev, QA, and Prod environments. Each environment will enforce its own approval gate and use environment‑specific secrets from a Variable Group. The pipeline will be ready to run on demand or on a schedule, and you’ll know exactly how to verify each step.

Prerequisites

• A project in Azure DevOps with a Git repo containing your source code.
• Permissions: Build administrator on the project and the ability to create pipelines and environments.
• Variable Groups: One for each environment (e.g., dev-secrets, qa-secrets, prod-secrets) stored in the Library tab.
• Artifacts: Your build output must be publishable, e.g., a Docker image or a ZIP file.
• Environment setup: Create three environments named dev, qa, and prod under the Environments hub. Attach the appropriate approval gate to prod.

Step‑by‑Step Procedure

1. Create the YAML File

Place the following file at the root of your repo as azure-pipelines.yml. Adjust the paths, artifact names, and deployment strategy to match your stack.

# azure-pipelines.yml
trigger:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  # Common variables
  buildConfiguration: 'Release'
  artifactName: 'drop'

stages:
  - stage: Build
    displayName: 'Build & Publish'
    jobs:
      - job: BuildJob
        steps:
          - task: DotNetCoreCLI@2
            inputs:
              command: 'build'
              projects: '**/*.csproj'
              arguments: '--configuration $(buildConfiguration)'

          - task: DotNetCoreCLI@2
            inputs:
              command: 'publish'
              publishWebProjects: true
              arguments: '--configuration $(buildConfiguration) --output $(Build.ArtifactStagingDirectory)'

          - publish: $(Build.ArtifactStagingDirectory)
            artifact: $(artifactName)

  - stage: DeployDev
    displayName: 'Deploy to Dev'
    dependsOn: Build
    environment: dev
    variables:
      - group: dev-secrets
    jobs:
      - deployment: DeployDevJob
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: $(artifactName)
                - script: echo Deploying to Dev
                  displayName: 'Deploy Script'

  - stage: DeployQA
    displayName: 'Deploy to QA'
    dependsOn: DeployDev
    environment: qa
    variables:
      - group: qa-secrets
    jobs:
      - deployment: DeployQAJob
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: $(artifactName)
                - script: echo Deploying to QA
                  displayName: 'Deploy Script'

  - stage: DeployProd
    displayName: 'Deploy to Prod'
    dependsOn: DeployQA
    environment: prod
    variables:
      - group: prod-secrets
    jobs:
      - deployment: DeployProdJob
        strategy:
          runOnce:
            deploy:
              steps:
                - download: current
                  artifact: $(artifactName)
                - script: echo Deploying to Prod
                  displayName: 'Deploy Script'

Key points:

• The environment keyword ties a stage to an Azure DevOps environment, enabling approvals.
• Variable groups are injected per stage, keeping secrets out of the YAML file.
• Artifacts are published in the Build stage and downloaded in each deployment stage using the download task.
• Using runOnce keeps the example simple; replace with canary or rolling if your deployment strategy requires it.

2. Validate the YAML

Open the file in the Azure DevOps web UI and click the Validate button. The editor will highlight any syntax errors or indentation problems before you commit.

3. Commit and Push

Commit the azure-pipelines.yml file and push to the main branch. Azure DevOps will automatically trigger the pipeline because of the trigger section.

4. Verify the Build Stage

Navigate to Pipelines > Runs and open the latest run. Ensure the Build stage completes successfully and that an artifact named drop appears in the Artifacts tab.

5. Check Environment Approvals

When the pipeline reaches the DeployProd stage, it should pause at the prod environment gate. In the run view, you’ll see a Waiting for approval status. Approve the deployment manually or set up a service account with the Approver role to automate it.

6. Inspect Deployment Logs

Open the Logs tab for the DeployProdJob job. Look for the line Deploying to Prod to confirm the artifact was downloaded and the script executed. If you replaced the script with a real deployment command, check that the command succeeded.

Expected Checks & Recovery

Verification Steps

• Pipeline syntax is valid: no red error bars in the editor.
• Build stage publishes an artifact: artifact appears in the run view.
• Each deployment stage downloads the artifact: log contains download task output.
• Environment approvals trigger: prod stage pauses until approved.
• Deployment scripts run: log shows expected output.

Common Pitfalls

• Indentation errors: YAML is whitespace sensitive. Use spaces only, not tabs.
• Variable group names miss‑typed: the pipeline will fail at runtime with “Variable group not found.”
• Artifact name mismatch: the download task must reference the exact artifact name.
• Missing permissions: ensure the agent has rights to read environment secrets.

Rollback Options

Because the pipeline does not alter any state outside the deployment environment, a rollback is typically a manual operation in the target environment (e.g., redeploy a previous release). If you need to revert a failed deployment automatically, add a deployment job that runs a rollback script and place it after the failing stage, guarded by a condition such as if: failure().

Limitations & Practical Checks

• Azure DevOps limits the number of concurrent deployments per environment. If you hit this limit, the pipeline will queue.
• The example uses simple shell scripts; replace them with Azure CLI, PowerShell, or container commands as appropriate.
• Secrets stored in Variable Groups are encrypted at rest but can be viewed by users with the Variable Group Reader role. Use Azure Key Vault for higher security.
• To confirm that the deployed application is running, add a health‑check task after the deployment step and fail the job if the check fails.

Conclusion

This YAML pipeline demonstrates how to orchestrate a full CI/CD workflow across multiple environments with minimal manual intervention. By leveraging Azure DevOps environments, variable groups, and artifact passing, you keep secrets safe and maintain a single source of truth for your deployment logic.