Artifact retention policies in Jenkins - Step-by-Step Execution

Process Flow - Artifact retention policies

Build completes

↓

Store artifacts

↓

Check retention policy

↓

Is artifact older than limit?

No→Keep artifact

Yes↓

Delete artifact

↓

End

This flow shows how Jenkins stores build artifacts, then checks if they are older than the retention policy allows, deleting them if so.

Execution Sample

Jenkins

pipeline {
  agent any
  options {
    buildDiscarder(logRotator(numToKeepStr: '3', artifactNumToKeepStr: '2'))
  }
  stages {
    stage('Build') { steps { echo 'Building...' } }
  }
}

This Jenkins pipeline keeps only the last 3 builds and retains artifacts only for the last 2 builds.

Process Table

Step	Build Number	Artifacts Stored	Retention Policy Check	Action
1	Build #1	Stored	No older builds to delete	Keep artifacts
2	Build #2	Stored	No older builds to delete	Keep artifacts
3	Build #3	Stored	Build #1 artifacts older than 2 builds	Delete Build #1 artifacts
4	Build #4	Stored	Build #2 artifacts older than 2 builds	Delete Build #2 artifacts
5	Build #5	Stored	Build #3 artifacts older than 2 builds	Delete Build #3 artifacts
6	Build #6	Stored	Build #4 artifacts older than 2 builds	Delete Build #4 artifacts
7	Build #7	Stored	Build #5 artifacts older than 2 builds	Delete Build #5 artifacts
8	Build #8	Stored	Build #6 artifacts older than 2 builds	Delete Build #6 artifacts
9	Build #9	Stored	Build #7 artifacts older than 2 builds	Delete Build #7 artifacts
10	Build #10	Stored	Build #8 artifacts older than 2 builds	Delete Build #8 artifacts

💡 After Build #10, only artifacts from builds #9 and #10 are kept as per retention policy.

Status Tracker

Build Number	Artifacts Stored	Artifacts Deleted
#1	Yes	No
#2	Yes	No
#3	Yes	No
#4	Yes	No
#5	Yes	No
#6	Yes	No
#7	Yes	No
#8	Yes	No
#9	Yes	No
#10	Yes	No

Key Moments - 3 Insights

Why are artifacts from Build #1 deleted after Build #3?

Because the retention policy keeps artifacts only for the last 2 builds, so after Build #3, Build #1 is older than 2 builds and its artifacts are deleted (see execution_table row 3).

Does the retention policy delete the entire build or just the artifacts?

It deletes only the artifacts, not the entire build record. The build history remains but artifacts older than the limit are removed (see execution_table actions).

What happens if the retention policy is set to keep 0 artifacts?

No artifacts are kept after each build completes; all previous artifacts are deleted immediately (not shown in table but implied by policy).

Visual Quiz - 3 Questions

Look at the execution table, at which build number are artifacts from Build #2 deleted?

A Build #4

B Build #5

C Build #3

D Build #6

💡 Hint

Check the 'Retention Policy Check' and 'Action' columns for Build #4 in the execution_table.

According to the variable tracker, are artifacts from Build #5 stored or deleted after Build #7?

A Deleted

B Stored

C Partially stored

D Unknown

💡 Hint

Look at the 'Artifacts Stored' and 'Artifacts Deleted' columns for Build #5 in variable_tracker.

If the retention policy changed to keep 3 artifacts, what would happen at Build #5?

A Artifacts from Build #2 would be deleted

B Artifacts from Build #1 would be deleted

C No artifacts would be deleted yet

D All artifacts would be deleted

💡 Hint

Consider the retention policy effect on artifact age in execution_table rows around Build #5.

Concept Snapshot

Jenkins artifact retention policies control how many build artifacts to keep.
Use 'buildDiscarder' with 'logRotator' to set limits.
Example: keep last 3 builds, artifacts for last 2 builds.
Older artifacts are deleted automatically after new builds.
This saves disk space and keeps recent artifacts accessible.

Full Transcript

This visual execution shows how Jenkins handles artifact retention. After each build, Jenkins stores artifacts. It then checks if artifacts are older than the retention policy allows. If yes, Jenkins deletes those old artifacts. For example, with a policy to keep artifacts for only the last 2 builds, artifacts from Build #1 are deleted after Build #3 completes. The execution table tracks each build's artifacts storage and deletion actions. The variable tracker shows which builds have artifacts stored or deleted over time. Key moments clarify common confusions like why only artifacts are deleted, not builds, and how the retention policy affects artifact lifespan. The quiz tests understanding of when artifacts are deleted and how changing the policy affects retention. The snapshot summarizes how to configure and what the policy does in Jenkins pipelines.

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