Complete Guide to Obtaining Absolute Workspace Path in Jenkins Pipeline

Overview of Workspace Path Acquisition in Jenkins Pipeline

In Jenkins Pipeline development, obtaining the absolute path of the current workspace is a common yet critical requirement. The workspace path is essential for scenarios such as test execution, accessing build artifacts, and configuring tool paths. Early versions of Jenkins Pipeline indeed had limitations where the path could not be directly obtained via env.WORKSPACE, which caused difficulties for many developers.

Environment Variable Solution

Since version 2.5 of the Pipeline Nodes and Processes Plugin (released on September 23, 2016), the WORKSPACE environment variable has become available again. This plugin is a core component of the Pipeline plugin and is typically installed by default. In modern Jenkins instances, developers can safely rely on this variable.

Below is the standard example of using environment variables:

node('label') {
    // now you are on slave labeled with 'label'
    def workspace = WORKSPACE
    // ${workspace} will now contain an absolute path to job workspace on slave

    workspace = env.WORKSPACE
    // ${workspace} will still contain an absolute path to job workspace on slave

    // When using a GString, at least later Jenkins versions could only handle the env.WORKSPACE variant:
    echo "Current workspace is ${env.WORKSPACE}"

    // the current Jenkins instances will support the short syntax, too:
    echo "Current workspace is $WORKSPACE"
}

pwd() Function Alternative

When environment variables are unavailable, the pwd() function provides another method to obtain the workspace path. However, it is important to note that this method only works if the master and slave nodes have the same directory structure.

Example code using pwd():

node('label') {
    // now you are on slave labeled with 'label'
    def workspace = pwd()
    // ${workspace} will now contain an absolute path to job workspace on slave
}

Version Compatibility Considerations

Support for path acquisition methods varies across different Jenkins versions. For older Jenkins instances where the Pipeline Nodes and Processes Plugin version is below 2.5, developers may need to rely on the pwd() function or other workarounds. It is recommended to check the availability of environment variables at the beginning of the Pipeline script to ensure code robustness.

Practical Application Scenarios

Obtaining the workspace path plays a significant role in test execution, file operations, and tool configuration. For example, when running tests that require absolute path parameters, the path can be constructed as follows:

def files = findFiles glob: '**/reports/*.json'
for (def i = 0; i < files.length; i++) {
    jsonFilePath = "${files[i].path}"
    jsonPath = "${env.WORKSPACE}" + "/" + jsonFilePath
    echo jsonPath
}

Related Extended Discussion

In addition to the workspace path, developers sometimes need to obtain the path of the directory containing the Jenkinsfile. Although this is different from the workspace path, it is equally important in certain configuration management scenarios. As mentioned in the reference article, obtaining the script directory via Groovy code presents challenges related to permissions and variable availability, reflecting the security restrictions of the Jenkins Pipeline execution environment.

Best Practices Summary

For modern Jenkins environments, prioritize using the env.WORKSPACE environment variable as it provides the most direct and reliable method for path acquisition. When backward compatibility or special node configurations are required, consider pwd() as an alternative. Always test the path acquisition logic in the target environment to ensure correctness across different node types and directory structures.