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.

Practice

1. What is the main purpose of artifact retention policies in Jenkins?

easy

A. To manage disk space by deleting old build files

B. To speed up the build process by caching dependencies

C. To increase the number of builds stored indefinitely

D. To automatically trigger builds on code changes

Solution

1. Step 1: Understand artifact retention policies

   Artifact retention policies control how long build files are kept to avoid using too much disk space.

2. Step 2: Identify the main goal

   The main goal is to delete old build files to free up disk space.

3. Final Answer:

   To manage disk space by deleting old build files -> Option A

4. Quick Check:

   Artifact retention = disk space management [OK]

Hint: Retention policies delete old builds to save space [OK]

Common Mistakes:

• Confusing retention with build triggering
• Thinking retention speeds up builds
• Assuming retention keeps all builds forever

2. Which Jenkins pipeline syntax correctly sets a retention policy to keep only the last 5 builds?

easy

A. archiveArtifacts(numToKeepStr: '5')

B. buildDiscarder(keepLast: 5)

C. buildDiscarder(logRotator(numToKeepStr: '5'))

D. archiveArtifacts(logRotator(numToKeepStr: '5'))

Solution

1. Step 1: Identify correct syntax for retention

   Retention uses buildDiscarder with logRotator to specify how many builds to keep.

2. Step 2: Check option correctness

   buildDiscarder(logRotator(numToKeepStr: '5')) uses correct syntax: buildDiscarder(logRotator(numToKeepStr: '5')). Others misuse archiveArtifacts or wrong parameters.

3. Final Answer:

   buildDiscarder(logRotator(numToKeepStr: '5')) -> Option C

4. Quick Check:

   Retention uses buildDiscarder + logRotator [OK]

Hint: Retention = buildDiscarder with logRotator [OK]

Common Mistakes:

• Using archiveArtifacts to set retention
• Wrong parameter names like keepLast
• Nesting logRotator inside archiveArtifacts

3. Given this Jenkins pipeline snippet:

pipeline {
  options {
    buildDiscarder(logRotator(numToKeepStr: '3', daysToKeepStr: '7'))
  }
  stages {
    stage('Build') {
      steps {
        echo 'Building...'
      }
    }
  }
}

What happens to builds older than 7 days or beyond the last 3 builds?

medium

A. They are deleted to free disk space

B. They are archived permanently

C. They trigger a new build automatically

D. They are kept indefinitely

Solution

1. Step 1: Understand logRotator parameters

   It keeps only the last 3 builds and deletes builds older than 7 days.

2. Step 2: Determine effect on old builds

   Builds older than 7 days or beyond the last 3 are deleted to save space.

3. Final Answer:

   They are deleted to free disk space -> Option A

4. Quick Check:

   logRotator deletes old builds [OK]

Hint: logRotator deletes builds older than days or count [OK]

Common Mistakes:

• Thinking builds are archived permanently
• Assuming builds trigger new builds
• Believing builds are kept forever

4. You wrote this Jenkins pipeline snippet to keep artifacts for 10 days:

options {
  buildDiscarder(logRotator(artifactDaysToKeep: '10'))
}

But artifacts are not deleted after 10 days. What is the likely problem?

medium

A. logRotator does not support artifact retention

B. The buildDiscarder option must be inside stages

C. You must use archiveArtifacts to delete old artifacts

D. The parameter name should be artifactDaysToKeepStr, not artifactDaysToKeep

Solution

1. Step 1: Check logRotator parameter names

   logRotator parameters for strings end with 'Str', like artifactDaysToKeepStr.

2. Step 2: Identify the syntax issue

   Missing 'Str' means the parameter is not recognized, so default retention applies and artifacts aren't deleted after 10 days.

3. Final Answer:

   The parameter name should be artifactDaysToKeepStr, not artifactDaysToKeep -> Option D

4. Quick Check:

   logRotator params end with 'Str' [OK]

Hint: logRotator params like artifactDaysToKeepStr end with Str [OK]

Common Mistakes:

• Using wrong parameter names
• Expecting logRotator to delete artifacts
• Placing buildDiscarder outside options block

5. You want to keep artifacts only for the last 4 builds and delete older artifacts automatically, while keeping older builds. Which Jenkins pipeline snippet correctly applies this retention policy?

hard

A. steps { archiveArtifacts artifacts: '**/*', onlyIfSuccessful: true, retentionDays: 4 }

B. options { buildDiscarder(logRotator(artifactNumToKeepStr: '4')) }

C. options { buildDiscarder(logRotator(numToKeepStr: '4')) } steps { archiveArtifacts artifacts: '**/*', onlyIfSuccessful: true }

D. steps { archiveArtifacts artifacts: '**/*', keepOnlyLast: 4 }

Solution

1. Step 1: Understand roles for artifact-specific retention

   To keep artifacts from only the last 4 builds while retaining builds, use artifactNumToKeepStr.

2. Step 2: Check option correctness

   options { buildDiscarder(logRotator(artifactNumToKeepStr: '4')) }: buildDiscarder(logRotator(artifactNumToKeepStr: '4')) keeps artifacts from last 4 builds, deletes older artifacts, keeps all builds. C deletes old builds too. B/D use invalid params.

3. Final Answer:

   options { buildDiscarder(logRotator(artifactNumToKeepStr: '4')) } -> Option B

4. Quick Check:

   artifactNumToKeepStr for artifacts only [OK]

Hint: artifactNumToKeepStr keeps artifacts from last N builds [OK]

Common Mistakes:

• Using invalid parameters like retentionDays or keepOnlyLast
• Trying to control retention only via archiveArtifacts
• Misplacing buildDiscarder outside options block