Instruction file imported from soofoove/copilot-knowledge (.github/instructions/azure-devops-pipelines.instructions.md). Copyright stays with the author.

Reviewed Azure DevOps Pipelines Guidance

Pipeline Structure

• Use YAML pipelines over classic (UI) pipelines for version control and review.
• Prefer multi-stage pipelines (stages → jobs → steps) for clear separation of build, test, and deploy.
• Use trigger and pr sections explicitly; avoid relying on default triggers.
• Set pool at the pipeline or stage level; prefer vmImage: 'ubuntu-latest' unless Windows-specific.

Templates and Reuse

• Extract repeated logic into templates (template references) stored in a shared folder.
• Use parameters with types and defaults in templates for type safety.
• Prefer extends templates for enforcing pipeline patterns across teams.
• Use template expressions (${{ }}) for compile-time logic; use runtime expressions ($[ ]) only when values are not known until runtime.

Security

• Never hardcode secrets, tokens, or connection strings in pipeline YAML.
• Use variable groups and Azure Key Vault integration for secrets.
• Mark secret variables as isSecret: true or use the secret type in variable groups.
• Use service connections with least-privilege access; prefer Workload Identity Federation over secrets.
• Set checkout: self with fetchDepth: 1 for shallow clones unless full history is needed.
• Use permissions and branch policies to restrict who can modify pipelines.

Variables and Parameters

• Define variables at the top of the pipeline or in variable groups for reuse.
• Use parameters for user-facing inputs with defined type, default, and values.
• Prefer variables templates for shared variable sets across pipelines.
• Avoid $(System.AccessToken) in scripts; use env mapping instead.

.NET Build Steps

• Run dotnet restore, dotnet build, and dotnet test as separate steps for clear failure diagnostics.
• Use DotNetCoreCLI@2 task or inline dotnet script steps.
• Cache NuGet packages with the Cache@2 task using $(NUGET_PACKAGES) or ~/.nuget/packages as the path.
• Publish test results with PublishTestResults@2 and code coverage with PublishCodeCoverageResults@2.
• Use --configuration Release for build and publish steps in non-dev stages.

Artifacts and Deployment

• Use PublishPipelineArtifact@1 and DownloadPipelineArtifact@2 over the older PublishBuildArtifacts.
• Name artifacts descriptively (e.g., drop-api, drop-web).
• Use environments with approval gates and checks for production deployments.
• Prefer deployment jobs (deployment) with strategies (runOnce, canary, rolling) over plain jobs for deploy stages.

Quality and Maintainability

• Add displayName to every step and job for readable logs.
• Use condition to control step execution; prefer succeeded(), failed(), always() over custom expressions when possible.
• Use dependsOn and condition for stage and job orchestration.
• Set timeoutInMinutes on long-running jobs to prevent runaway pipelines.
• Use continueOnError: false (the default) to fail fast on errors.