How to Lock a Resource for Concurrency in Jenkins

By Daniel Zoghalchali·Latchkey

The lock step queues builds so only one holds a named resource at a time.

Wrap the critical stage in a lock so concurrent builds wait their turn for a shared environment. The Lockable Resources plugin tracks the named lock across the controller.

Serialize a staging deploy

Lock a named resource around the deploy and smoke-test steps.

pipeline {
  agent any
  stages {
    stage('Deploy to staging') {
      steps {
        lock(resource: 'staging-env') {
          sh './deploy.sh staging'
          sh './smoke-test.sh staging'
        }
      }
    }
  }
}

Notes

• Other builds reaching the same lock wait until the holder releases it, preventing clobbered deploys.
• Use a label and quantity for pools of interchangeable resources instead of a single named lock.

Verify it actually works

Validate the pipeline definition against the running controller before committing. Jenkins parses declarative pipelines strictly, and a syntax error surfaces as a failed build rather than a clear parse message.

# validate a Jenkinsfile against the live controller
curl -X POST -F "jenkinsfile=<Jenkinsfile" \
  https://your-jenkins/pipeline-model-converter/validate

# replay a build with modified script to test a change without committing
# Build page -> Replay -> edit -> Run

Agent and workspace assumptions that break in CI

• An agent label that matches no online agent leaves the build queued indefinitely rather than failing.
• Workspaces are reused between builds by default, so stale files from a previous run can mask or cause failures. Use cleanWs() or a fresh workspace when correctness matters.
• Tools resolved from the controller PATH are not necessarily on the agent PATH. Declare them in a tools block or install them in the pipeline.
• Credentials bound with withCredentials are masked in logs but still visible to any process you launch; avoid passing them as command-line arguments.

Frequently asked questions

Related guides

References

• GitHub Actions documentation