What does a ws() block do in Jenkins?

Question

I'm trying to convert few Jenkinsfiles from Scripted Pipeline to Declarative Pipeline. I have a block like this in a Jenkinsfile:

ws("/path/to/dir") {
    // do stuff
}

I wonder what does it do exactly and what's the proper way to convert it to the Declarative Pipeline syntax.

Answer 1

ws allocates a new workspace. you would use this to ensure that nothing else interferes with the location on disk where you are running the enclosed steps.

• this is not as heavy-handed as the node step, since node will also ensure that it gets run with a separate executor.
• this provides more isolation than the dir step, since dir will not ensure an isolated location on the filesystem the way ws will.

you can use it in a declarative pipeline in the same way as scripted:

pipeline {
  agent { label 'docker' }
  stages {
    stage('hot_stage') {
      steps {
        sh 'pwd'
        ws('/tmp/hey') {
          sh 'pwd'
        }
      }
    }
  }
}

produces output:

+ pwd
/opt/jenkins/workspace/tool_jenkins2-test_master-R4LIKJR63O6POQ3PHZRAKWWWGZZEQIVXVDTM2ZWZEBAWE3XKO6CQ
[Pipeline] ws
Running in /tmp/hey
[Pipeline] {
[Pipeline] sh
[hey] Running shell script
+ pwd
/tmp/hey

references:

• https://jenkins.io/doc/pipeline/steps/workflow-durable-task-step/#code-ws-code-allocate-workspace
• https://github.com/jenkinsci/pipeline-plugin/blob/master/TUTORIAL.md#allocating-workspaces