Artifact retention policies in Jenkins - Commands & Configuration

Introduction

When you run builds in Jenkins, they create files called artifacts. These files can take up space over time. Artifact retention policies help you keep only the important files and delete old ones automatically to save space.

When your Jenkins server is running low on disk space because of many build artifacts.

When you want to keep only the latest few builds' artifacts for quick access.

When you want to delete artifacts older than a certain number of days to keep your storage clean.

When you want to keep artifacts only for successful builds and remove those from failed builds.

When you want to automate cleanup so you don’t have to delete old files manually.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  options {
    buildDiscarder(logRotator(numToKeepStr: '5', artifactNumToKeepStr: '3', daysToKeepStr: '10'))
  }
  stages {
    stage('Build') {
      steps {
        echo 'Building...'
        // build steps here
      }
    }
    stage('Archive') {
      steps {
        archiveArtifacts artifacts: '**/target/*.jar', fingerprint: true
      }
    }
  }
}

This Jenkinsfile defines a pipeline with a retention policy using buildDiscarder. It keeps the last 5 builds, keeps artifacts from the last 3 builds, and deletes builds older than 10 days. The archiveArtifacts step saves the build files matching the pattern **/target/*.jar.

Commands

This command triggers a build of the Jenkins pipeline named 'example-pipeline'. It starts the process that will produce artifacts.

Terminal

jenkins-cli build example-pipeline

Expected Output

Started build #12

Finished: SUCCESS

This command retrieves the configuration of the 'example-pipeline' job to verify the retention policy is set.

Terminal

jenkins-cli get-job example-pipeline

Expected Output

<project>

  <logRotator>

    <daysToKeep>10</daysToKeep>

    <numToKeep>5</numToKeep>

    <artifactDaysToKeep>10</artifactDaysToKeep>

    <artifactNumToKeep>3</artifactNumToKeep>

  </logRotator>

</project>

This command lists recent builds of the pipeline to check which builds and artifacts are kept according to the retention policy.

Terminal

jenkins-cli list-builds example-pipeline

Expected Output

Build #12 SUCCESS

Build #11 SUCCESS

Build #10 FAILURE

Build #9 SUCCESS

Build #8 SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: artifact retention policies automatically delete old build files to save space and keep your Jenkins server clean.

Common Mistakes

Not setting artifactNumToKeep in the retention policy.

Artifacts from old builds will never be deleted, causing disk space to fill up.

Always specify artifactNumToKeep to limit how many builds' artifacts are kept.

Setting daysToKeep or numToKeep to zero or negative values.

This can cause Jenkins to delete all builds or none, leading to unexpected results.

Use positive integers for daysToKeep and numToKeep to control retention properly.

Archiving artifacts without a matching retention policy.

Artifacts accumulate indefinitely, wasting disk space.

Combine artifact archiving with a buildDiscarder retention policy.

Summary

Use the buildDiscarder option in Jenkins pipelines to set artifact retention policies.

Retention policies control how many builds and artifacts Jenkins keeps by number and age.

This helps automate cleanup and prevents disk space issues on Jenkins servers.