Managing Build Workspaces

1. Understanding Workspace Structure

Component	Description	Location
workspace	Root directory for the build workspace	`$JENKINS_HOME/workspace/<job_name>`
workspace.root	Base directory where Jenkins stores all workspaces	`$JENKINS_HOME/workspace/`
job.name	Name of the job being executed	Derived from job configuration

Example: Workspace Path Calculation

echo "Workspace path: $JENKINS_HOME/workspace/MyJob"

Note: The workspace is automatically cleaned or reused based on job configuration settings.

Key Points

Each job has its own dedicated workspace directory.
Workspaces are managed under $JENKINS_HOME/workspace/.
Workspace contents can be preserved or cleaned between builds.

2. Cleaning Workspace Before Build

Option	Values	Notes
cleanBeforeBuild	`true` / `false`	Whether to clean the workspace before each build. Default is `false`.

Example: Configure cleanBeforeBuild in Jenkinsfile

pipeline {
    agent any
    options {
        cleanBeforeBuild true
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: Enabling cleanBeforeBuild ensures that the workspace is cleaned before each build, which helps avoid issues caused by stale files from previous builds.

3. Cleaning Workspace After Build

Option	Values	Notes
cleanBeforeBuild	`true` / `false`	Whether to clean the workspace before each build. Default is `false`.
cleanAfterBuild	`true` / `false`	Whether to clean the workspace after each build. Default is `false`.

Example: Configure workspace cleaning in Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building..."'
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}

Note: The cleanWs() step removes all files from the workspace except for those that are marked as keep or are part of a build artifact.

Warning: Cleaning the workspace can lead to loss of important data if not configured properly. Ensure that necessary files are backed up or stored in a separate location.

4. Using Custom Workspace Locations

Property	Value	Description
workspace	`custom/path`	Defines the custom workspace path for a Jenkins job

Example: Setting Custom Workspace Path

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building in custom workspace"'
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}

Note: The cleanWs() step ensures the workspace is cleaned up after each build.

Warning: Ensure that the custom workspace path has appropriate permissions for Jenkins to read/write files.

5. Managing Workspace Concurrency

Property	Values	Description
jenkins.workspace.concurrentBuilds	`false`	Controls whether concurrent builds are allowed in the same workspace
jenkins.workspace.maxConcurrentBuilds	`1`	Maximum number of concurrent builds allowed per job
jenkins.workspace.lockStrategy	`none`	Locking strategy to prevent workspace conflicts: `none`, `job`, or `workspace`

Example: Configure Concurrent Builds

pipeline {
    agent any
    stages {
        stage('Build') {
            concurrent {
                branch('feature-branch') {
                    steps {
                        sh 'echo "Building feature branch"'
                    }
                }
                branch('release-branch') {
                    steps {
                        sh 'echo "Building release branch"'
                    }
                }
            }
        }
    }
}

Note: Enabling concurrent builds can lead to race conditions if jobs modify shared resources. Use with caution and ensure proper locking mechanisms.

Warning: Setting maxConcurrentBuilds to a value higher than 1 without proper locking may cause build failures due to workspace conflicts.

6. Using Workspace Cleanup Plugins

Plugin	Description	Configuration	Notes
Workspace Cleanup Plugin	Automatically cleans up workspace files after builds	`cleanAfterEachBuild`, `cleanAfterEachBuildOnFailure`	Default Jenkins plugin; supports regex patterns for file matching
Build Timeout Plugin	Enforces timeout on builds and cleans up workspace if exceeded	`timeoutMinutes`, `timeoutAction`	Can be combined with cleanup to prevent stale builds

Example: Configure Workspace Cleanup

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building..."'
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}

Note: The cleanWs() step removes all files in the workspace except for those that are explicitly preserved.

Workspace Cleanup vs Manual Cleanup

Manual: Requires developer to write cleanup scripts
Plugin-based: Automates cleanup using predefined rules or patterns

7. Accessing Workspace Files

Property	Description	Default Value	Notes
workspace	Path to the workspace directory	`${JENKINS_HOME}/workspace`	Can be customized in Jenkins configuration
workspace.dir	Workspace directory path for a specific job	`${workspace}`	Can be overridden per job

Example: Accessing workspace files in a pipeline script

pipeline {
    agent any
    stages {
        stage('Access Workspace') {
            steps {
                sh 'ls -la'
                sh 'cat Jenkinsfile'
            }
        }
    }
}

Note: Workspace files are automatically cleaned up after a build unless configured otherwise.

Warning: Direct file system access may cause issues in distributed builds or when using Docker agents.

Workspace Access Methods

Pipeline Steps: Use sh or bat steps to execute shell commands in the workspace.
Environment Variables: Access ${WORKSPACE} to reference the current workspace path.
File Operations: Use archiveArtifacts to save files from the workspace.

8. Using External Workspace

Property	Value	Description
workspace	`external`	Configures Jenkins to use an external workspace directory instead of the default one.
externalWorkspacePath	`/path/to/external/workspace`	Specifies the absolute path to the external workspace directory.

Example: Configure External Workspace

pipeline {
    agent {
        label 'master'
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building in external workspace"'
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}

Note: Ensure that the external workspace directory has appropriate permissions for Jenkins to read and write files.

9. Preserving Workspace Between Builds

Note: By default, Jenkins cleans the workspace before each build to ensure a fresh environment. However, in some cases, preserving the workspace between builds can be useful for caching dependencies or retaining artifacts.

Option	Values	Description
workspace.cleanup	`false`	Disables automatic cleanup of the workspace before each build.
workspace.preserve	`true`	Enables preservation of workspace content between builds.

Example: Configuring Workspace Preservation

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building..."'
            }
        }
    }
    post {
        always {
            // Preserve workspace between builds
            cleanWs()
        }
    }
}

Workspace Preservation Best Practices

Use cleanWs() in the post block to explicitly control workspace cleanup.
Consider using cleanWs(cleanCopy: true) to copy workspace contents to a new location before cleaning.
Be cautious with preserving large workspaces as it can lead to disk space issues.

10. Troubleshooting Workspace Issues

Issue	Description	Solution
Workspace not clean	Builds run in a workspace that contains files from previous builds, causing conflicts or unexpected behavior.	Use `clean` workspace option in job configuration or `delete workspace before build starts` checkbox.
Permission denied	Build fails due to insufficient permissions on workspace directory or files.	Ensure Jenkins user has read/write access to the workspace directory. Check file system permissions and ownership.
Disk space full	Builds fail when the disk where workspace resides is full.	Monitor and manage disk space. Configure Jenkins to clean up old workspaces or use external storage.
Workspace locked	Another process or job is using the workspace, preventing new builds from starting.	Check for running jobs or processes locking the workspace. Restart Jenkins or manually unlock if needed.

Example: Cleaning Workspace in Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                cleanWs()
                sh 'make'
            }
        }
    }
}

Note: The cleanWs() step ensures a clean workspace before each build.

Warning: Cleaning the workspace deletes all files, so ensure backups or version control is used for important data.