B+
ci cdazure pipelines toolkit

Azure Pipelines Generator

Generates production-ready Azure DevOps Pipelines (azure-pipelines.yml) following current best practices, security standards, and naming conventions. Use when creating or updating ADO YAML pipelines, configuring build triggers, defining multi-stage deployments, setting up template references, creating variable groups, writing release pipelines, or structuring CI/CD workflows for Azure DevOps Services or Azure DevOps Server. Handles build pipelines, YAML pipelines, Docker container builds, Kubernetes/AKS deployments, language-specific pipelines (.NET, Node.js, Python, Go, Java), and reusable step/job/stage templates. All generated configurations are validated using the devops-skills:azure-pipelines-validator skill before delivery.

npx skills add github:pantheon-org/tekhne --skill ci-cd--azure-pipelines--generator

Overview

Generate production-ready Azure DevOps Pipeline configurations following current best practices, security standards, and naming conventions. After generating any complete pipeline file, always validate it using the devops-skills:azure-pipelines-validator skill, fix any reported issues, and re-validate before presenting to the user. Skip validation only for partial snippets, documentation examples, or when the user explicitly requests it.

Philosophy

  • Generate pipelines that are deterministic: pin every image, task and runtime version.
  • Keep secrets out of YAML; reference service connections, variable groups or Key Vault instead.
  • Prefer reusable templates over long inline pipelines, and validate every complete file before delivery.

When to Use

  • Creating or updating an azure-pipelines.yml for build, test or deploy.
  • Defining multi-stage deployments with environments, variable groups and service connections.
  • Writing Docker build and Kubernetes/AKS deployment pipelines.
  • Producing reusable step, job or stage templates and the pipelines that consume them.

When Not to Use

  • Reviewing or linting an existing pipeline without changing it: use the validator skill alone.
  • Targeting other CI systems such as GitHub Actions, GitLab CI or Jenkins.
  • Classic (UI-based) release pipelines that have no YAML definition.
  • Provisioning the Azure DevOps organisation, agents or service connections themselves.

Core Capabilities

1. Basic CI Pipelines

Read references/yaml-schema.md, references/best-practices.md, references/tasks-reference.md, and assets/examples/basic-ci.yml.

Example:

trigger:
  branches:
    include:
    - main
    - develop

pool:
  vmImage: 'ubuntu-22.04'

variables:
  buildConfiguration: 'Release'

steps:
- task: NodeTool@0
  displayName: 'Install Node.js'
  inputs:
    versionSpec: '20.x'

- task: Cache@2
  displayName: 'Cache npm packages'
  inputs:
    key: 'npm | "$(Agent.OS)" | package-lock.json'
    path: $(Pipeline.Workspace)/.npm

- script: npm ci --cache $(Pipeline.Workspace)/.npm
  displayName: 'Install dependencies'

- script: npm run build
  displayName: 'Build application'

- script: npm test
  displayName: 'Run tests'

- task: PublishTestResults@2
  condition: succeededOrFailed()
  inputs:
    testResultsFormat: 'JUnit'
    testResultsFiles: '**/test-results.xml'

2. Multi-Stage CI/CD Pipelines

Read references/yaml-schema.md and assets/examples/multi-stage-cicd.yml. Use deployment jobs for environment tracking; publish artifacts between stages.

Example:

stages:
- stage: Build
  displayName: 'Build Stage'
  jobs:
  - job: BuildJob
    displayName: 'Build Application'
    pool:
      vmImage: 'ubuntu-22.04'
    steps:
    - script: npm run build
      displayName: 'Build'
    - publish: $(Build.SourcesDirectory)/dist
      artifact: drop

- stage: Test
  displayName: 'Test Stage'
  dependsOn: Build
  jobs:
  - job: TestJob
    displayName: 'Run Tests'
    steps:
    - script: npm test
      displayName: 'Test'

- stage: DeployProd
  displayName: 'Deploy to Production'
  dependsOn: Test
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
  jobs:
  - deployment: DeployProd
    environment: production
    strategy:
      runOnce:
        deploy:
          steps:
          - script: echo "Deploying"

3. Docker Build Pipelines

Read references/tasks-reference.md for Docker@2 and assets/examples/kubernetes-deploy.yml. Use service connection for authentication; tag with $(Build.BuildId) as primary.

Example:

variables:
  dockerRegistryServiceConnection: 'myACR'
  imageRepository: 'myapp'
  containerRegistry: 'myregistry.azurecr.io'
  tag: '$(Build.BuildId)'

steps:
- task: Docker@2
  displayName: 'Build and Push'
  inputs:
    command: buildAndPush
    repository: $(imageRepository)
    dockerfile: '$(Build.SourcesDirectory)/Dockerfile'
    containerRegistry: $(dockerRegistryServiceConnection)
    tags: |
      $(tag)
      latest

Tagging rule: Push with $(tag) AND latest; deploy/pull using only the specific $(tag) — never :latest in production deployments.

4. Kubernetes Deployment Pipelines

Read references/tasks-reference.md and assets/examples/kubernetes-deploy.yml. Use KubernetesManifest@0 or Kubernetes@1; include namespace management and health checks.

Example:

- task: KubernetesManifest@0
  displayName: 'Deploy to Kubernetes'
  inputs:
    action: 'deploy'
    kubernetesServiceConnection: 'myK8sCluster'
    namespace: 'production'
    manifests: |
      k8s/deployment.yml
      k8s/service.yml
    containers: '$(containerRegistry)/$(imageRepository):$(tag)'

5. Language-Specific Pipelines

Supported languages: .NET/C#, Node.js, Python, Java, Go, Docker multi-stage

Read references/tasks-reference.md and the matching example file:

Language Example File
Go assets/examples/go-cicd.yml
.NET/C# assets/examples/dotnet-cicd.yml
Python assets/examples/python-cicd.yml
Node.js assets/examples/basic-ci.yml or multi-stage-cicd.yml

Include: runtime setup, package manager caching, build, test with reporting, artifact publish.

Go-specific notes:

  • Use GoTool@0 (only major version available — @0 is correct)
  • Cache Go modules at $(GOPATH)/pkg/mod using go.sum as key
  • Run go vet ./... before tests; use -race -coverprofile flags for test coverage
  • Build with CGO_ENABLED=0 for container images

Matrix testing pattern:

strategy:
  matrix:
    node18:
      nodeVersion: '18.x'
    node20:
      nodeVersion: '20.x'
    node22:
      nodeVersion: '22.x'
  maxParallel: 3
steps:
- task: NodeTool@0
  inputs:
    versionSpec: $(nodeVersion)
- script: npm test

6. Template-Based Pipelines

Read references/templates-guide.md and assets/examples/templates/. Use ${{ parameters.name }} syntax; generate both template and consuming pipeline.

Example:

# templates/build.yml
parameters:
- name: nodeVersion
  type: string
  default: '20.x'

steps:
- task: NodeTool@0
  inputs:
    versionSpec: ${{ parameters.nodeVersion }}
- script: npm ci
- script: npm run build

# Main pipeline
steps:
- template: templates/build.yml
  parameters:
    nodeVersion: '20.x'

7. Task Documentation Lookup

When local docs are sufficient (most cases):

  • references/tasks-reference.md covers .NET, Node.js, Python, Go, Docker, Kubernetes, Azure tasks
  • references/yaml-schema.md covers complete YAML syntax

When to use external sources (tasks not in local docs, version-specific questions, troubleshooting):

  • Context7 MCP (preferred): mcp__context7__resolve-library-id → query “azure-pipelines” → mcp__context7__get-library-docs
  • WebSearch (fallback): "[TaskName]@[version] Azure Pipelines task documentation"

Analyze retrieved docs for: task name/version, required vs optional inputs, service connection requirements, and outputs.

# Example: task found via documentation lookup
- task: AzureFunctionApp@1
  displayName: 'Deploy Azure Function'
  inputs:
    azureSubscription: 'AzureServiceConnection'   # Required: ARM service connection
    appType: 'functionAppLinux'
    appName: 'myfunctionapp'
    package: '$(Build.ArtifactStagingDirectory)/**/*.zip'
    runtimeStack: 'NODE|20'

Best Practices to Enforce

Reference references/best-practices.md for comprehensive guidelines.

Mandatory Standards

  1. Security: Never hardcode secrets; use service connections; mark variables as secret in ADO
  2. Version pinning:
    • vmImage: ubuntu-22.04 not ubuntu-latest
    • Tasks: Docker@2 not Docker (pin to major version; @0 is correct for GoTool@0, NodeTool@0, KubernetesManifest@0)
    • Runtimes: '20.x' for Node.js, explicit Go versions
  3. Performance: Use Cache@2 for all package managers; use dependsOn for parallelism; set artifact expiration; shallow clone when full history is unnecessary
  4. Naming conventions:
    • Stages/Jobs: PascalCase (BuildAndTest, DeployProduction)
    • displayName: Sentence case ('Build application', 'Run tests')
    • Variables: camelCase or snake_case (be consistent)
  5. Organization: Use stages for complex pipelines; deployment jobs for environment tracking; templates for reusable logic; variable groups for environment-specific config
  6. Error handling: Set timeoutInMinutes; use condition: succeededOrFailed() for test publishing; continueOnError for non-critical steps
  7. Testing: Always publish test results (PublishTestResults@2) and code coverage (PublishCodeCoverageResults@1)

Workflow Process

For a complete end-to-end workflow example (Understanding → Reading → Lookup → Generate → Validate → Present), see references/typical-workflow.md.

Anti-Patterns

NEVER use latest for task version pins

WHY: ADO task versions introduce breaking changes across major versions. Using @latest or an unpinned reference creates non-deterministic builds where a task update can silently break your pipeline overnight.

BAD: - task: UseNode@latest

GOOD: - task: UseNode@0 with a pinned versionSpec input (e.g., versionSpec: '20.x').

NEVER store secrets in pipeline YAML variables

WHY: YAML variables are committed to source control and visible in pipeline run logs, exposing credentials to anyone with repository read access or pipeline view permissions.

BAD: variables: API_KEY: 'abc123'

GOOD: Use Azure Key Vault task or pipeline variable groups with the “secret” flag enabled in the ADO UI.

NEVER omit displayName: on tasks and steps

WHY: Pipelines without display names produce cryptic logs like Task 1 of 12 that are impossible to interpret when diagnosing a failure, especially in multi-stage pipelines.

BAD: - script: npm ci with no displayName.

GOOD: - script: npm ci followed by displayName: 'Install dependencies'.

NEVER use trigger: none on templates used as main pipelines

WHY: trigger: none disables all automatic triggers, meaning the pipeline never runs on code push. This is appropriate only for templates called by other pipelines, not for CI entry-point pipelines.

BAD: trigger: none on a pipeline intended to run on every commit.

GOOD: Configure explicit branch includes, for example trigger: branches: include: [main, develop].

NEVER define all logic inline in a single flat YAML

WHY: Single-file pipelines exceeding a few hundred lines become unmaintainable, impossible to test in isolation, and prone to merge conflicts when multiple teams update them simultaneously.

BAD: A 400-line azure-pipelines.yml with all stages, jobs, and scripts inlined.

GOOD: Extract stage and job logic into separate templates/*.yml files and reference them with - template: templates/build.yml.

NEVER use ubuntu-latest or other floating vmImage values

WHY: a floating image changes underneath the pipeline, so builds stop being reproducible and can break without any code change.

BAD: vmImage: 'ubuntu-latest'

GOOD: vmImage: 'ubuntu-22.04'

NEVER deploy or pull the latest image tag in production

WHY: latest is mutable, so the running version cannot be traced to a build and rollbacks are ambiguous.

BAD: a Kubernetes manifest deploying $(imageRepository):latest.

GOOD: push with $(tag) and latest, but deploy using only $(tag) (the $(Build.BuildId)).

NEVER use a regular job for an environment deployment

WHY: only deployment jobs give environment tracking, approvals and deployment history.

BAD: a job: that runs kubectl apply for the production stage.

GOOD: a deployment: job with environment: production and a runOnce strategy.

NEVER skip test result publishing or run it only on success

WHY: failed runs are exactly where the test report is needed, and a skipped publish hides which tests failed.

BAD: PublishTestResults@2 with no condition, or no publish step at all.

GOOD: condition: succeededOrFailed() on PublishTestResults@2, plus code coverage publishing.

NEVER deliver a complete pipeline without validating it

WHY: unvalidated YAML ships syntax, hierarchy and security errors straight to the user.

BAD: presenting a generated azure-pipelines.yml straight away.

GOOD: run the azure-pipelines-validator skill, fix reported issues, and re-validate before presenting.

Troubleshooting

If devops-skills:azure-pipelines-validator reports errors

Error type Resolution
Syntax errors Fix YAML indentation or structure
Task version errors Ensure format is TaskName@version
Pool/vmImage errors Use specific versions, not latest
Stage/Job errors Verify stages → jobs → steps hierarchy
Security warnings Remove hardcoded secrets; avoid :latest in deployments

If task documentation is not found

  1. Try alternative search queries
  2. Check Microsoft Learn task reference
  3. Check azure-pipelines-tasks on GitHub
  4. Ask the user for specific version requirements

References

Topic Reference When to Use
YAML schema references/yaml-schema.md Pipeline structure, triggers, pools, variables, conditions, expressions
Task catalogue references/tasks-reference.md Task inputs, outputs and service connection requirements
Best practices references/best-practices.md Security, performance, naming and anti-patterns
Templates references/templates-guide.md Template types, parameter definitions, expressions, iteration
End-to-end workflow references/typical-workflow.md A complete worked example including validation steps
Basic CI example assets/examples/basic-ci.yml Simple CI, single-stage builds
Multi-stage example assets/examples/multi-stage-cicd.yml Multi-environment deployments
Kubernetes example assets/examples/kubernetes-deploy.yml Docker plus K8s/AKS deployments
Go example assets/examples/go-cicd.yml Go applications
.NET example assets/examples/dotnet-cicd.yml .NET/C# applications
Python example assets/examples/python-cicd.yml Python applications
Template usage example assets/examples/template-usage.yml Template-consuming pipelines
Build template assets/examples/templates/build-template.yml Reusable build templates
Deploy template assets/examples/templates/deploy-template.yml Reusable deployment templates
Edit this page on GitHub