README.md

Azure DevOps Deployment Queuing for YAML Pipelines

Deployment Queue Settings is a feature of Classic Release pipelines that "define the behavior when multiple releases are queued for deployment." This includes a setting that specifies what should happen if a newer build is queued while an existing build is queued or waiting for approval. This extension aims to emulate the "Deploy latest and cancel the others" capability for YAML multi-stage pipelines.

By default, YAML pipelines will remain in a pending state until they timeout -- which by default is 30 days. This extension adds functionality that will auto-cancel older pipelines when a newer build completes successfully.

Notes:

• Only older builds that are in a pending state for the current stage are impacted.
• Only applies to multi-stage YAML pipelines with that use a deployment job. The stage must have an existing gate that pauses before execution.
• Each pipeline must opt-in to enable this behavior using the deploymentQueuing.enable variable, either as a global pipeline variable as a stage/job variable. See usage below.
• The pipeline agent user account must be granted to the "Stop Build" permission.

Without deployment queuing:

With deployment queuing, previously queued pipelines are automatically cancelled after a more recent build completes:

Usage

To enable deployment-queueing to your multi-stage YAML pipeline:

1. Install this extension into your Azure DevOps Organization.

2. Grant the identity of your pipeline agent the "Stop Build" permission per Project.

3. Add the deploymentQueuing.enable variable to your pipeline. This can be defined at the pipeline-level or per stage.

   variables:
     deploymentQueuing.enable: true

When the pipeline runs, it will automatically inject a step into your pipeline to cancel any pending pipelines.

Note:

The post-job task only appears if your stage uses a deployment job that is associated with an Enviroment.

Example

Consider a multi-stage pipeline with three stages. Each stage uses a deployment task and an Azure Pipeline Environment. The QA and Prod environments are defined with an approval gate that will pause pipelines runs until an approval is provided.

Because the Project has the policy "limit job authorization scope to current project for non-release pipelines" disabled, the pipeline will run under the Project Collection Build Service user account. This account has been granted the "Stop Build" permission in our Project.

trigger:
  branches:
    include:
    - main

variables:
  deploymentQueuing.enable: true

stages:
- stage: build
  jobs:
  - job: build
    steps:
    - script: echo 'hello world'

- stage: QA
  jobs:
  - deployment: qa_deploy
    environment: QA
    strategy:
      runOnce:
        deploy:
          steps:
          - script: echo 'deploy into qa'

- stage: PROD
  jobs:
  - deployment: prod_deploy
    environment: PROD
    strategy:
      runOnce:
        deploy:
          steps:
          - script: echo 'deploy into prod'

FAQ

How do I assign my pipeline agent the "Stop Build" permission?

First determine the authorization scope for your pipelines:

1. In your project, navigate to Settings
2. Select Pipelines > Settings
3. Review the setting for "Limit job authorization scope to current project for non-release pipelines"

If this value is enabled, your pipelines operate using a user account <Project Name> Build Service (<Organization Name>)

If this value is not enabled, your pipelines operate under Project Collection Build Service (<Organization Name>).

Next, configure the permissions for the build agent:

1. In the side-menu, select Pipelines > Pipelines
2. From the elipsis in the top-right, select Manage Security
3. In the search for users or groups textbox, type in the name of the user account identified above.
4. Set the "Stop Builds" permission to Allow

Why is the post-job step not being added?

The deployment-queuing feature requires the following:

• your stage uses a deployment job associated with a Pipeline Environment.
• the deploymentQueueing.enable variable must be set to true

What happens if I'm not using approval-checks or there are no queued pipelines?

Nothing. This extension adds a post-job task to cancel any pending builds that are pending for the stage that just completed. If there are no approval gates or previously pending builds, the script happily ignores them.

I'm running a self-hosted runner, does this have special requirements?

Your self-hosted runner needs to have PowerShell or PowerShell Core installed.