Workspace Cleanup Plugin

• Introduction
• Getting started
  • Pipeline jobs
  • Declarative Pipeline
  • Freestyle jobs
• Configuration
  • Patterns
  • Deferred wipeout
• Issues
• Contributing
• License

Introduction

This plugin deletes the build workspace.

Getting started

Pipeline jobs

There is a single step to be used whenever a workspace is allocated.

Declarative Pipeline

The cleanWs step is available for use with Declarative Pipeline. When you want to clean the workspace after the build, you can add this step under a suitable condition in the post section of your Pipeline job. If you want to clean the workspace before the build starts, you need to add some extra configuration to be able to clean before the sources are checked out from SCM. See the examples below for details.

The snippet generator that is built into Jenkins can assist you with what configuration options are available. Click on the Pipeline Syntax button in your Pipeline job and select cleanWs from the Sample Step drop-down. For example:

pipeline {
    agent any
    options {
        // This is required if you want to clean before build
        skipDefaultCheckout(true)
    }
    stages {
        stage('Build') {
            steps {
                // Clean before build
                cleanWs()
                // We need to explicitly checkout from SCM here
                checkout scm
                echo "Building ${env.JOB_NAME}..."
            }
        }
    }
    post {
        // Clean after build
        always {
            cleanWs(cleanWhenNotBuilt: false,
                    deleteDirs: true,
                    disableDeferredWipeout: true,
                    notFailBuild: true,
                    patterns: [[pattern: '.gitignore', type: 'INCLUDE'],
                               [pattern: '.propsfile', type: 'EXCLUDE']])
        }
    }
}

Freestyle jobs

The plugin provides a build wrapper (Delete workspace before build starts) and a post build step (Delete workspace when build is done). These steps allow you to configure which files will be deleted and in what circumstances. The post build step can also take the build status into account.

This plugin also provides Job DSL support for Freestyle jobs. For example:

job("foo") {
    wrappers {
        preBuildCleanup { // Clean before build
            includePattern('**/target/**')
            deleteDirectories()
            cleanupParameter('CLEANUP')
        }
    }
    publishers {
        cleanWs { // Clean after build
            cleanWhenAborted(true)
            cleanWhenFailure(true)
            cleanWhenNotBuilt(false)
            cleanWhenSuccess(true)
            cleanWhenUnstable(true)
            deleteDirs(true)
            notFailBuild(true)
            disableDeferredWipeout(true)
            patterns {
                pattern {
                    type('EXCLUDE')
                    pattern('.propsfile')
                }
                pattern {
                    type('INCLUDE')
                    pattern('.gitignore')
                }
            }
        }
    }
}

Configuration

Patterns

Files to be deleted are specified by pattern using Ant pattern syntax. You can choose if the pattern is an include pattern (if the file matches this pattern, the file will be removed) or exclude pattern (if the file matches this pattern, the file won’t be removed). If there is only an exclude pattern, **/* (i.e., delete everything) will be used as the include pattern, which means that everything will be deleted except the files matching the exclude pattern. Patterns are applied only on files; if you want to apply them also on directories, check the appropriate box.

⚠️	The directory is deleted with all its contents. If the directory matches the include pattern, everything in the directory will be deleted regardless as to whether some files in the directory match the exclude pattern.

See the documentation for the Ant DirectoryScanner class for examples of patterns.

Deferred wipeout

When the whole workspace is supposed to be deleted (no patterns, external commands, etc.), the Workspace Cleanup plugin delegates to the Resource Disposer plugin to speed things up.

When deferred wipeout is disabled, the old implementation of filesystem content deletion is used. If you want the same behavior as with deferred wipeout, you have to set the plugin attribute deleteDirs to true as well. For Pipeline jobs, you can do this as follows:

cleanWs disableDeferredWipeout: true, deleteDirs: true

For e.g. cloud developers it might be useful to be sure deferred wipeout is never selected as a cleanup method. Therefore there is a new feature introduced to do this, implemented via a regular NodeProperty which you can attach to any node via the UI or via a Groovy script as follows:

Node.getNodeProperties().add(new DisableDeferredWipeoutNodeProperty());

Issues

Report issues and enhancements in the Jenkins issue tracker. Use the ws-cleanup-plugin component in the JENKINS project.

Contributing

Refer to our contribution guidelines.

License

Licensed under the MIT License.