az-pipelines
Manage Azure Pipelines from the command line
TLDR
Create a new Azure Pipeline (YAML based)
Delete a specific pipeline
List pipelines
Enqueue a specific pipeline to run
Get the details of a specific pipeline
Update a specific pipeline
List all agents in a pool
SYNOPSIS
az pipelines <subcommand> [options]
Common subcommands and their typical usage:
az pipelines run --definition-id <id> [--branch <branch>] [--org <organization_url>] [--project <project_name>]
az pipelines list [--org <organization_url>] [--project <project_name>]
az pipelines show --definition-id <id> [--org <organization_url>] [--project <project_name>]
az pipelines create --name <pipeline_name> --repository <repo_name> --repository-type <type> --yml-path <path> [--org <organization_url>] [--project <project_name>]
PARAMETERS
run
Queues a new run for a pipeline. Requires --definition-id or --definition-name.
--definition-id
ID of the pipeline definition. Required for 'run', 'show'.
--definition-name
Name of the pipeline definition. Alternative to --definition-id.
--branch
Branch to queue the run for. Default is the pipeline's default branch.
list
Lists all pipelines in a project.
show
Gets the details of a specific pipeline definition.
create
Creates a new pipeline. Requires repository details and path to YAML file.
--name
Name of the new pipeline to create.
--repository
Name of the repository where the pipeline YAML is located.
--repository-type
Type of the repository (e.g., TfsGit, GitHub, Bitbucket). Defaults to TfsGit.
--yml-path
Path to the YAML file within the repository (e.g., azure-pipelines.yml).
update
Updates an existing pipeline definition.
delete
Deletes a pipeline definition. Requires --definition-id or --definition-name.
--org
Azure DevOps organization URL (e.g., https://dev.azure.com/myorg). Required if not set as default.
--project
Name or ID of the Azure DevOps project. Required if not set as default.
--output
Output format: json (default), jsonc, table, tsv, yaml, none.
--query
JMESPath query string. Filters and formats output.
--verbose
Increase logging verbosity to show all debug logs.
--debug
Show debug logs.
--help -h
Show help for the command or subcommand.
DESCRIPTION
az pipelines is a powerful command within the Azure Command Line Interface (CLI) that enables developers and operations teams to manage Azure DevOps build and release pipelines directly from the terminal. It provides a comprehensive set of functionalities to interact with CI/CD (Continuous Integration/Continuous Delivery) processes, including creating new pipelines, listing existing ones, viewing details, initiating runs, updating configurations, and deleting pipelines.
This command is an essential tool for automating pipeline management tasks, integrating with scripts, and streamlining DevOps workflows. It allows for programmatic control over the entire lifecycle of a pipeline, from definition to execution and monitoring, making it a cornerstone for efficient and repeatable software delivery in an Azure DevOps environment.
CAVEATS
- Requires the Azure CLI to be installed and the azure-devops extension to be enabled.
- Authentication: Users must be logged in to Azure CLI (az login) and have appropriate permissions within the target Azure DevOps organization and project to perform operations.
- Context: az pipelines commands operate within the context of an Azure DevOps organization and project, which often need to be specified using --org and --project or set as defaults.
- Network Connectivity: A stable internet connection is required to communicate with Azure DevOps services.
- YAML-based Pipelines: While the command can interact with both Classic and YAML pipelines, the create command primarily focuses on YAML-based definitions.
AUTHENTICATION AND DEFAULTS
Before using az pipelines, ensure you are logged into Azure CLI using az login. You can also set default organization and project using az devops configure --defaults organization=YOUR_ORG project=YOUR_PROJECT to avoid specifying them with every command.
PIPELINE YAML DEFINITION
For creating new pipelines, az pipelines create often requires specifying a path to a YAML file that defines the pipeline's steps, stages, and triggers. This YAML file is typically stored in a Git repository connected to Azure DevOps.
HISTORY
The az pipelines command is a key part of the azure-devops extension for the Azure CLI. The Azure CLI itself was introduced to provide a cross-platform command-line experience for managing Azure resources. As Microsoft's DevOps story evolved from Team Foundation Server (TFS) and Visual Studio Team Services (VSTS) to Azure DevOps, the Azure CLI adapted to include rich functionality for managing these services. The az pipelines command specifically matured to support the increasing adoption of YAML-based pipelines, offering programmatic control over CI/CD definitions and runs, which became crucial for Git-centric and infrastructure-as-code workflows. Its development has focused on parity with the web portal's capabilities, enabling full automation of DevOps practices.
SEE ALSO
az devops, az login, az extension, git(1)