Milestone step for concurrency in Jenkins - Commands & Configuration

Introduction

When multiple builds run in parallel, sometimes you want to keep only the latest one and stop older ones. The milestone step in Jenkins helps control this by marking points in the pipeline where older builds can be discarded to avoid wasted work.

When you have frequent code changes and want to avoid running outdated builds that started earlier.

When multiple developers push code quickly and you want to keep the pipeline focused on the newest changes.

When running long pipelines and you want to save resources by canceling older builds that are no longer relevant.

When you want to ensure only one build passes a certain point before others proceed.

When you want to prevent race conditions by controlling concurrency in your pipeline.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        echo 'Building...'
        milestone 1
      }
    }
    stage('Test') {
      steps {
        echo 'Testing...'
        milestone 2
      }
    }
    stage('Deploy') {
      steps {
        echo 'Deploying...'
      }
    }
  }
}

This Jenkinsfile defines a simple pipeline with three stages: Build, Test, and Deploy.

The milestone step is used in the Build and Test stages to mark points where Jenkins will cancel older builds that have not reached these milestones yet.

This helps keep only the latest build running past these points, saving resources and avoiding conflicts.

Commands

This command updates the Jenkins pipeline job with the new Jenkinsfile containing milestone steps to control concurrency.

Terminal

jenkins-jobs --conf jenkins.ini update Jenkinsfile

Expected Output

Job updated successfully: pipeline-job

Starts a new build of the pipeline job to test the milestone concurrency control.

Terminal

jenkins build pipeline-job

Expected Output

Started build #1 for pipeline-job

Starts a second build quickly after the first to demonstrate that the milestone step will cancel the older build when it reaches the milestone.

Terminal

jenkins build pipeline-job

Expected Output

Started build #2 for pipeline-job

Build #1 canceled due to milestone step

Shows the console output of the second build to verify it proceeded while the first was canceled.

Terminal

jenkins console pipeline-job #2

Expected Output

[Pipeline] echo

Building...

[Pipeline] milestone

[Pipeline] echo

Testing...

[Pipeline] milestone

[Pipeline] echo

Deploying...

[Pipeline] End of Pipeline

Key Concept

If you remember nothing else, remember: the milestone step cancels older builds that have not reached the same milestone, keeping only the latest build running past that point.

Common Mistakes

Not placing milestone steps at key points in the pipeline.

Without milestones, Jenkins cannot cancel older builds, so concurrency control fails.

Add milestone steps at stages where you want to limit concurrency and cancel outdated builds.

Using milestone steps without understanding their order.

Milestones must be numbered in increasing order to work correctly; otherwise, builds may not cancel as expected.

Number milestone steps sequentially in the order they appear in the pipeline.

Summary

The milestone step marks points in a Jenkins pipeline to control concurrency.

Older builds that have not reached a milestone are canceled when a newer build passes it.

Place milestone steps in stages where you want to keep only the latest build running.