Azure Pipelines Field Guide

Azure Pipelines Field Guide is a Visual Studio Code extension that adds context-aware IntelliSense, hover documentation, semantic highlighting, and syntax diagnostics for variables in Azure Pipelines YAML files.

It complements Microsoft's official Azure Pipelines extension. Microsoft’s extension owns the azure-pipelines language, YAML schema, file associations, and general pipeline language service. Field Guide adds the variable-focused features that are missing or limited today.

Requirements

The extension depends on Azure Pipelines by Microsoft, which VS Code installs automatically. The current document must use the azure-pipelines language mode; generic YAML files are intentionally excluded.

Microsoft's extension recognizes common names such as azure-pipelines.yml, .azure-pipelines.yml, and YAML files below .pipelines/ or azure-pipelines/. For another filename, use Change Language Mode and select Azure Pipelines.

Current functionality

Variable IntelliSense

Completion is offered only when the cursor is inside a supported Azure Pipelines variable form:

steps:
- script: echo $(Build.)
- script: echo ${{ variables.buildC }}
  condition: eq(variables['System.PullRequest.SourceBranch'], 'main')

Supported forms are:

Bare text such as Build. or displayName: Build. does not trigger variable completion.

Predefined Microsoft variables and variables declared in the current YAML document are included. Document variables support both mapping and list declaration forms and are ranked above predefined variables when names collide.

Multiline expressions and conditions

The same features work in multiline template/runtime expressions and block-scalar conditions:

condition: |
  and(
    succeeded(),
    eq(variables['Build.SourceBranch'], 'refs/heads/main')
  )

The extension detects ${{ ... }}, $[ ... ], inline condition: values, and condition: |/condition: > blocks across document lines.

Hover and completion documentation

Predefined variable hovers and completion details include:

• The full Microsoft-provided description.
• Macro, index, and—when valid—simple property syntax examples.
• Whether Microsoft documents the variable as available in templates.
• The equivalent environment variable name, such as BUILD_BUILDID.
• A section-anchored link to the official Microsoft Learn documentation.

The editor UI does not show links to the GitHub documentation source.

Highlighting

Recognized predefined variables and current-document variables receive semantic highlighting when used in valid macro, index, property, template, runtime, or condition syntax. Unknown names and bare text are not highlighted as known variables.

Diagnostics and Quick Fixes

The extension warns about malformed expression variable syntax:

# Warning: variable index names must be quoted.
condition: eq(variables[Build.BuildId], '123')

# Quick Fix result:
condition: eq(variables['Build.BuildId'], '123')

It also warns when a predefined variable in expression syntax does not use the documented casing and offers a Quick Fix. Macro syntax is recognized case-insensitively and does not receive expression-casing warnings.

Property dereference is valid for simple names only. Dotted predefined names must use index syntax:

# Valid
condition: eq(variables.buildConfiguration, 'Release')
condition: eq(variables['Build.BuildId'], '123')

# Warning with Quick Fix
condition: eq(variables.Build.BuildId, '123')

Comments are ignored by the variable scanner, so examples or commands in YAML comments do not produce highlighting or diagnostics.

Variable catalog sidebar

Open Azure Pipelines Field Guide from the Activity Bar, then open Azure Pipelines Variables to browse the complete bundled predefined-variable catalog in one compact alphabetical list. Expand a variable to reveal its wrapped full description, syntax examples, environment-variable equivalent, template availability, and official documentation link. The view includes filtering, a copy button, and a dynamic right-click menu with the exact syntax, such as Copy as "$(Build.BuildId)", Copy as "variables['Build.BuildId']", and Copy as "BUILD_BUILDID" for environment variables.

Right-click a variable to copy its macro syntax, expression syntax, or—when valid—simple property syntax. The webview builds these actions dynamically from the selected variable, so there are no per-variable command contributions in package.json.

The same view is available from the Command Palette with Azure Pipelines Field Guide: Browse Predefined Variables. The catalog is bundled with the extension and is updated by CI when the Microsoft documentation source changes.

If you previously moved the catalog into Explorer, use View: Reset View Locations once to return it to its own Activity Bar icon.

Settings

Catalog data and retrieval

The predefined-variable catalog is generated from Microsoft's Azure DevOps documentation source. The retrieval script follows Markdown includes, parses variable tables and special sections, extracts descriptions and section anchors, and writes a checked-in TypeScript catalog.

npm run update:variables  # retrieve and regenerate the catalog
npm run check:variables   # verify the committed catalog is current

The extension never retrieves documentation or contacts Azure DevOps while editing. Runtime use is local and offline.

Development

npm install
npm run build
npm test

Press F5 to launch an Extension Development Host. The integration tests install the official Azure Pipelines extension and verify the behavior through VS Code's public commands.

See Architecture for design boundaries and Contributing for the development workflow.

Known boundaries

• The extension analyzes the open file only. Variable groups, linked templates, pipeline UI variables, and runtime-created output variables are not resolved.
• The predefined catalog does not yet include dependencies, stageDependencies, parameters, or other Azure Pipelines expression contexts.
• Template availability describes Microsoft's documented template-scope flag; actual availability can still depend on pipeline scope, trigger, and job context.
• Dynamically generated variable names are skipped because their final names cannot be known statically.
• The catalog sidebar contains the bundled predefined catalog; it does not yet show variables from linked files or variable groups.

Background

This project addresses long-standing requests in the official extension for build-variable IntelliSense and better variable-scope awareness.

License

MIT