skilld
All skills
akin-ozer avatar

/azure-pipelines-generator

@1b2342a
by Akin Ozerakin-ozer/cc-devops-skills316 stars
36

Generate/create/scaffold azure-pipelines.yml, stages, jobs, steps, or reusable templates.

Ask your Agent

Use this Skill: https://skilld.dev/gh/akin-ozer/cc-devops-skills/azure-pipelines-generator

This session only. Nothing lands on disk.

docsyaml-schema.md

≈3.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Azure Pipelines YAML Schema Reference

This document provides a comprehensive reference for Azure Pipelines YAML syntax and structure.

How to Use This Reference

Use this deterministic sequence:

  1. Confirm root structure (steps-only, jobs-based, or stages-based pipeline).
  2. Add required root keys (trigger, pr, pool, variables, resources) for the requested mode.
  3. Build hierarchy in order: stages -> jobs -> steps.
  4. Apply dependsOn, condition, and deployment environment settings.
  5. Validate YAML and schema compliance.

Fallback behavior:

  • If advanced expressions are uncertain, prefer simpler explicit conditions.
  • If schema details are missing locally, use the official schema links in this file and document assumptions.
  • If validation tooling is unavailable, run manual hierarchy and syntax sanity checks before delivery.

Pipeline Structure

Azure Pipelines follow a hierarchical structure:

Pipeline
└── Stages
    └── Jobs
        └── Steps

Basic Pipeline

# Minimal pipeline with implicit stage
trigger:
  - main

pool:
  vmImage: 'ubuntu-22.04'

steps:
- script: echo "Hello World"
  displayName: 'Run a one-line script'

Multi-Stage Pipeline

stages:
- stage: Build
  displayName: 'Build Stage'
  jobs:
  - job: BuildJob
    displayName: 'Build Job'
    pool:
      vmImage: 'ubuntu-22.04'
    steps:
    - script: npm run build
      displayName: 'Build Application'

- stage: Deploy
  displayName: 'Deploy Stage'
  dependsOn: Build
  jobs:
  - deployment: DeployJob
    displayName: 'Deploy to Production'
    environment: production
    strategy:
      runOnce:
        deploy:
          steps:
          - script: echo "Deploying..."
            displayName: 'Deploy'

Root-Level Keywords

trigger

Defines CI triggers (when the pipeline should run automatically).

# Simple trigger
trigger:
  - main
  - develop

# Advanced trigger with path filters
trigger:
  branches:
    include:
    - main
    - release/*
    exclude:
    - feature/*
  paths:
    include:
    - src/**
    exclude:
    - docs/**
  tags:
    include:
    - v*

pr

Defines pull request triggers.

pr:
  branches:
    include:
    - main
  paths:
    exclude:
    - docs/**

schedules

Defines scheduled triggers (cron syntax).

schedules:
- cron: "0 0 * * *"
  displayName: Daily midnight build
  branches:
    include:
    - main
  always: true

resources

Defines external resources used by the pipeline.

resources:
  repositories:
  - repository: templates
    type: github
    name: org/repo
    ref: refs/heads/main

  pipelines:
  - pipeline: upstream
    source: 'Upstream Pipeline'
    trigger:
      branches:
      - main

  containers:
  - container: linux
    image: ubuntu:22.04

  packages:
  - package: mypackage
    type: npm
    connection: npmConnection
    name: '@scope/package'
    version: '1.0.0'

pool

Defines the default agent pool for all jobs.

# Microsoft-hosted agent
pool:
  vmImage: 'ubuntu-22.04'

# Self-hosted agent pool
pool:
  name: 'MyAgentPool'
  demands:
  - agent.os -equals Linux

variables

Defines pipeline-level variables.

variables:
  buildConfiguration: 'Release'
  vmImage: 'ubuntu-22.04'

# Variable groups
variables:
- group: 'my-variable-group'
- name: customVar
  value: 'customValue'

# Template variables
variables:
- template: variables-template.yml

parameters

Defines runtime parameters (user input when pipeline runs).

parameters:
- name: environment
  displayName: 'Target Environment'
  type: string
  default: 'staging'
  values:
  - dev
  - staging
  - production

- name: runTests
  displayName: 'Run Tests'
  type: boolean
  default: true

- name: regions
  displayName: 'Deployment Regions'
  type: object
  default:
    - westus
    - eastus

Stages

Stages represent major divisions in your pipeline (e.g., Build, Test, Deploy).

stages:
- stage: Build
  displayName: 'Build Stage'

  # Stage condition
  condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

  # Stage dependencies
  dependsOn: []  # No dependencies, can run immediately

  # Stage variables
  variables:
    stageVar: 'value'

  jobs:
  - job: BuildJob
    steps:
    - script: npm run build

Stage Properties

  • stage: Unique identifier
  • displayName: Human-readable name
  • dependsOn: List of stages to wait for
  • condition: Condition to run the stage
  • variables: Stage-specific variables
  • jobs: Jobs to run in this stage

Jobs

Jobs represent a series of steps that run sequentially on the same agent.

Regular Job

jobs:
- job: BuildJob
  displayName: 'Build Application'

  # Job timeout (default: 60 minutes)
  timeoutInMinutes: 30

  # Job cancellation timeout
  cancelTimeoutInMinutes: 5

  # Pool for this job
  pool:
    vmImage: 'ubuntu-22.04'

  # Job dependencies
  dependsOn: []

  # Job condition
  condition: succeeded()

  # Continue on error
  continueOnError: false

  # Job variables
  variables:
    jobVar: 'value'

  # Job strategy (matrix, parallel)
  strategy:
    matrix:
      linux:
        imageName: 'ubuntu-22.04'
      mac:
        imageName: 'macOS-12'
      windows:
        imageName: 'windows-2022'

  steps:
  - script: npm run build

Deployment Job

Deployment jobs are special jobs for deploying to environments with deployment history and approvals.

jobs:
- deployment: DeployWeb
  displayName: 'Deploy Web App'

  # Target environment
  environment:
    name: production
    resourceName: web-app
    resourceType: Kubernetes

  # Deployment strategy
  strategy:
    runOnce:
      preDeploy:
        steps:
        - script: echo "Pre-deploy"

      deploy:
        steps:
        - script: echo "Deploying"

      routeTraffic:
        steps:
        - script: echo "Routing traffic"

      postRouteTraffic:
        steps:
        - script: echo "Post routing"

      on:
        failure:
          steps:
          - script: echo "Deployment failed"

        success:
          steps:
          - script: echo "Deployment succeeded"

Deployment Strategies

runOnce
strategy:
  runOnce:
    deploy:
      steps:
      - script: echo "Deploying"
rolling
strategy:
  rolling:
    maxParallel: 2
    preDeploy:
      steps:
      - script: echo "Pre-deploy"
    deploy:
      steps:
      - script: echo "Deploy"
    postDeploy:
      steps:
      - script: echo "Post-deploy"
canary
strategy:
  canary:
    increments: [10, 20, 50]
    preDeploy:
      steps:
      - script: echo "Pre-deploy"
    deploy:
      steps:
      - script: echo "Deploy $(strategy.canary.increment)%"
    postDeploy:
      steps:
      - script: echo "Post-deploy"

Steps

Steps are the individual tasks that run in a job.

Script Step

steps:
- script: echo "Hello World"
  displayName: 'Run Script'
  workingDirectory: $(Build.SourcesDirectory)
  failOnStderr: false
  condition: succeeded()
  env:
    MY_VAR: value

Bash Step

steps:
- bash: |
    echo "Multi-line bash script"
    npm install
    npm test
  displayName: 'Run Bash Script'

PowerShell Step

steps:
- powershell: |
    Write-Host "PowerShell script"
    Get-ChildItem
  displayName: 'Run PowerShell'

Task Step

steps:
- task: TaskName@version
  displayName: 'Task Display Name'
  inputs:
    inputName: value
  condition: succeeded()
  continueOnError: false
  enabled: true
  env:
    VARIABLE: value
  timeoutInMinutes: 0

Checkout Step

steps:
- checkout: self
  clean: true
  fetchDepth: 1
  lfs: false
  submodules: false
  persistCredentials: false

Download Step

steps:
- download: current
  artifact: artifactName
  patterns: '**/*.zip'

- download: upstream
  artifact: artifactName

Publish Step

steps:
- publish: $(Build.ArtifactStagingDirectory)
  artifact: drop
  displayName: 'Publish Artifact'

Conditions

Conditions control when stages, jobs, or steps run.

Built-in Conditions

condition: succeeded()           # Previous succeeded (default)
condition: failed()              # Previous failed
condition: succeededOrFailed()   # Previous completed
condition: always()              # Always run
condition: canceled()            # Pipeline was canceled

Custom Conditions

# Variable equality
condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

# Contains check
condition: contains(variables['Build.SourceBranch'], 'release')

# And/Or/Not
condition: and(succeeded(), eq(variables['environment'], 'prod'))
condition: or(eq(variables['Build.Reason'], 'PullRequest'), eq(variables['Build.Reason'], 'Manual'))
condition: not(eq(variables['Skip'], 'true'))

# StartsWith/EndsWith
condition: startsWith(variables['Build.SourceBranch'], 'refs/heads/feature/')
condition: endsWith(variables['artifactName'], '.zip')

Expressions and Variables

Predefined Variables

# Build variables
$(Build.BuildId)
$(Build.BuildNumber)
$(Build.SourceBranch)
$(Build.SourceVersion)
$(Build.Reason)
$(Build.ArtifactStagingDirectory)
$(Build.SourcesDirectory)

# Agent variables
$(Agent.OS)
$(Agent.MachineName)
$(Agent.WorkFolder)

# System variables
$(System.TeamProject)
$(System.StageName)
$(System.JobName)
$(System.HostType)

# Pipeline variables
$(Pipeline.Workspace)

Variable Syntax

# Macro syntax (processed at queue time)
$(variableName)

# Template expression syntax (processed at compile time)
${{ variables.variableName }}

# Runtime expression syntax (processed at runtime)
$[variables.variableName]

Accessing Job Outputs

# In the same stage
dependencies.jobName.outputs['stepName.variableName']

# Across stages
stageDependencies.stageName.jobName.outputs['stepName.variableName']

Template Syntax

Template Reference

# Include template
- template: path/to/template.yml
  parameters:
    paramName: value

# Extends template
extends:
  template: path/to/template.yml
  parameters:
    paramName: value

Template Parameters

# In template file
parameters:
- name: paramName
  type: string
  default: defaultValue
- name: paramList
  type: object
  default: []

# Use parameters
steps:
- script: echo ${{ parameters.paramName }}

Template Iteration

# Iterate over parameters
parameters:
- name: environments
  type: object
  default:
  - dev
  - staging
  - prod

stages:
- ${{ each env in parameters.environments }}:
  - stage: Deploy_${{ env }}
    jobs:
    - job: DeployTo${{ env }}
      steps:
      - script: echo "Deploying to ${{ env }}"

Container Jobs

Run jobs in Docker containers.

resources:
  containers:
  - container: node
    image: node:20-alpine

jobs:
- job: BuildInContainer
  container: node
  steps:
  - script: npm install
  - script: npm test

Service Containers

Run sidecar containers alongside your job.

resources:
  containers:
  - container: postgres
    image: postgres:15
    env:
      POSTGRES_PASSWORD: password
    ports:
    - 5432:5432

jobs:
- job: Test
  services:
    postgres: postgres
  steps:
  - script: npm test
    env:
      DATABASE_URL: postgres://postgres:password@postgres:5432/test

Matrix Strategy

Run the same job with different variable combinations.

strategy:
  matrix:
    linux_node18:
      imageName: 'ubuntu-22.04'
      nodeVersion: '18'
    linux_node20:
      imageName: 'ubuntu-22.04'
      nodeVersion: '20'
    mac_node18:
      imageName: 'macOS-12'
      nodeVersion: '18'
  maxParallel: 3

pool:
  vmImage: $(imageName)

steps:
- task: NodeTool@0
  inputs:
    versionSpec: $(nodeVersion)
- script: npm test

Environment and Approvals

Environments provide deployment history, approvals, and checks.

jobs:
- deployment: DeployProd
  environment:
    name: production
    resourceName: web-app
  strategy:
    runOnce:
      deploy:
        steps:
        - script: echo "Deploying"

Best Practices Summary

  1. Use specific versions: Pin vmImage and task versions
  2. Use displayName: Add clear display names for readability
  3. Use stages: Organize complex pipelines with stages
  4. Use templates: Create reusable templates for common patterns
  5. Use conditions: Control execution flow with conditions
  6. Use dependsOn: Optimize with explicit dependencies
  7. Use environments: Track deployments with environments
  8. Use parameters: Make pipelines configurable with runtime parameters
  9. Cache dependencies: Use Cache task for package managers
  10. Set timeouts: Prevent hung jobs with timeout settings

Official Documentation

Done Criteria

Schema usage is complete when:

  • Pipeline hierarchy is internally consistent (stages/jobs/steps are not mixed incorrectly).
  • Runtime conditions and dependencies are explicit for non-trivial flow.
  • Deployment stages use deployment jobs and environment where applicable.
  • Validation output or documented manual fallback confirms structural correctness.

Source: SKILL.md on GitHub

Third-party checks

1 warning16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill is a generator for Azure Pipelines YAML configurations with a strong focus on security and reliability. It includes extensive documentation, best practices, and a mandatory validation workflow. The skill explicitly forbids dangerous patterns like hardcoded secrets and requires pinning task versions and images. All command executions and network operations identified in the examples are standard practices for continuous integration and deployment.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer6mo

    4/16 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 1b2342a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Steadyupdated 7 months ago

README badge

README badge for akin-ozer/cc-devops-skills/azure-pipelines-generator