Create a version-controlled CI pipeline in Azure DevOps with YAML

Problem: CI that lives in source control and fails fast on bad commits

You need a build that runs automatically on pushes to main, compiles the solution, runs tests, and publishes build outputs. Keeping the definition in a YAML file in the repo makes changes reviewable and revertible without touching the Azure DevOps UI.

Useful takeaway: a minimal declarative pipeline is a trigger, a job with steps for restore/build/test/publish, and a reference to an agent pool. All of it is stored as azure-pipelines.yml in the repo.

Desired outcome

Push to main starts a pipeline run on a Microsoft-hosted or self-hosted agent. The run restores dependencies, builds, runs unit tests, and publishes artifacts. Runs are visible in the Runs tab, test results appear in the Tests tab, and artifacts are listed under Artifacts. Rollback is a git revert of the YAML file.

Prerequisites

• Azure DevOps organization and project with an Azure Repos Git repository.
• Permission to create pipelines in the project and Contribute access to the repo. The pipeline service principal needs Read access to the agent pool.
• An agent pool. Microsoft-hosted pools provide preinstalled toolsets; self-hosted pools require the required SDKs and tools installed on the agent machine.
• Repo contains source and a buildable solution. Secrets, if needed, must be stored in Azure Key Vault or as secret pipeline variables, not hard-coded in YAML.

Artifact retention is configured per project. Artifacts may be deleted after the retention period, so plan retention for releases you need to keep.

Create the YAML definition

Create azure-pipelines.yml at the repo root. YAML is indentation sensitive; incorrect spacing causes validation errors.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

variables:
  buildConfiguration: Release

steps:
- task: DotNetCoreCLI@2
  inputs:
    command: 'restore'
    projects: '**/*.csproj'
- task: DotNetCoreCLI@2
  inputs:
    command: 'build'
    projects: '**/*.csproj'
    arguments: '--configuration $(buildConfiguration)'
- task: DotNetCoreCLI@2
  inputs:
    command: 'test'
    projects: '**/*Tests.csproj'
    arguments: '--configuration $(buildConfiguration) --collect "Code coverage"'
- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)'
    ArtifactName: 'drop'

Placeholders like ubuntu-latest and project globs should match your repo. For self-hosted agents, ensure the agent has the .NET SDK required by the project.

Commit the file from your local working directory where the repo is cloned. Required permission: write access to the repo.

git add azure-pipelines.yml
git commit -m "Add initial CI pipeline"
git push origin main

Risks: pushing secrets in the file is insecure and irreversible in history. Flaky tests will fail the pipeline; consider retry policies if needed.

Create the pipeline in Azure DevOps

In Azure DevOps, open Pipelines > Create Pipeline. Choose Azure Repos Git, select the repo and branch. When prompted for existing YAML, select the azure-pipelines.yml file at the repo root.

The UI validates the YAML before saving and highlights syntax errors. Save the pipeline. The pipeline appears in Pipelines list with the name derived from the repo.

Expected checks

• Trigger check: push a commit to the target branch and observe a new run start in the Runs tab.
• Step logs: open the run and verify each step shows completed status and console output.
• Tests tab: confirm test results are displayed and no failures are reported.
• Artifacts: verify an artifact named drop is listed under Artifacts for the run.
• Agent tool check: in the logs for the first step, inspect the agent capabilities and tool versions to confirm required SDKs are present. For self-hosted agents, this confirms the machine is correctly configured.

Limitations: Microsoft-hosted image names and preinstalled tools change over time. Verify the current image capabilities in the Azure Pipelines documentation before relying on a specific tool version. Self-hosted agents require manual maintenance.

Recovery options

The pipeline definition is code. To roll back a change:

• Revert the YAML file in source control and push the revert commit. A new run will use the previous definition.
• In the pipeline history, use the Revert button to create a revert commit from the UI, if enabled.

Do not edit the pipeline via the UI to fix a broken YAML change; revert the file so history stays consistent.

Operational notes

Permissions: pipeline creation requires Project Administrator or User with Create pipeline permission. Repo Contribute is needed to update YAML.

Secrets: reference secret variables with $(SecretVar) and mark them secret in the pipeline variables UI or link to Key Vault.

Retention: set artifact and build retention policies in Project Settings to avoid unexpected deletion.