This is a Jenkins plugin that allows the building of simple but powerful rules to define which builds should be removed from the history and which ones should be preserved.
The rules use conditionals to filter (select) completed builds from the build history and actions to operate on the builds selected by the conditionals.
Users can add Build History Manager rules to Jenkins jobs. The rules are composed of three types of objects:
The plugin has three built-in conditions that control the flow of operations. Users cannot remove these conditions. The first one is built-in to the plugin for all rules, and the other two are configurable on a per-rule basis.
The built-in conditions are:
matchAtMost
counter (Process this rule at most (times)
in the UI) that limits the number of times a rule can be applied
(default is -1
, meaning there is no limit).continueAfterMatch
boolean (Proceed to the next rule if the conditions of this rule are met
in the UI)
that causes the plugin to apply the next rule to the same build after the current rule has been applied
(default is true
, meaning to continue to apply rules to the build being processed).Users can add a list of Conditions to each rule, in any order they need. The conditions are checked in the order they are defined.
The conditions are:
Providing the built-in conditions allow, the optional condition checks have the following effects:
Users can add a list of Actions to each rule, in any order they need. The actions are applied in the order they are defined.
The actions are:
If the first action is to delete the build, the other actions will still be applied but have no real effect.
The plugin starts by initializing the internal match counters for each rule to zero.
The plugin then loops through all the completed builds in the build history, starting from the most recent, and processes each build with possibly every rule (depending on the conditions) by looping through the rule list once for each completed build.
matchAtMost
value,
stop processing the current rule and move on to the next rule (next iteration of "for each rule")continueAfterMatch
is true
,
the next rule is applied to the same build, and goes to the next iteration of the "for each rule" loop.continueAfterMatch
is false
,
the plugin stops applying rules to this build, and goes to the next iteration of the "for each completed build" loop.Notes:
matchAtMost
value is set to zero, the rule is effectively disabled.
This is useful if the user wants to disable a rule while keeping its other configuration values.matchAtMost
value is reached, the rule is effectively disabled and is no longer applied.By using conditions and actions, it becomes straightforward to achieve a number of scenarios, including:
master
branch if the project builds all branches including feature branchesThe following configuration allows to save the last 5 builds, while deleting the rest of the build history:
The following configuration has two rules.
The first rule ensures that the latest build with a failure
result
is not deleted. The second rule deletes all builds which are not success
.
In other words, it keeps the most recent broken build and all stable builds.
pipeline {
agent any
options {
buildDiscarder(BuildHistoryManager([
[
conditions: [
BuildResult(matchFailure: true)
],
matchAtMost: 1,
continueAfterMatch: false
],
[
conditions: [
BuildResult(matchNotBuilt: true, matchAborted: true, matchFailure: true, matchUnstable: true)
],
actions: [DeleteBuild()]
]
]))
}
stages {
stage('Demo') {
steps {
echo "Hello!"
}
}
}
}
The following configuration has three rules.
The first rule uses the token macro condition to test the value of a parameter.
It removes builds where the string value of ENABLE_HISTORY
is "false".
The second rule preserves the most recent 24 builds that do not match the first rule.
The third rule deletes the remaining build.
Consequently, these three rules work together to preserve the last 24 builds where ENABLE_HISTORY
is true.
pipeline {
agent any
options {
buildDiscarder(BuildHistoryManager([
[
conditions: [
TokenMacro(template: '"${ENABLE_HISTORY}"', value: '"false"')
],
actions: [DeleteBuild()],
continueAfterMatch: false
],
[
matchAtMost: 24,
continueAfterMatch: false
],
[
actions: [DeleteBuild()]
]
]))
}
parameters {
booleanParam(
name: 'ENABLE_HISTORY',
defaultValue: true,
description: 'Check to preserve build.'
)
}
stages {
stage('Demo') {
steps {
echo "Hello!"
}
}
}
}
Please refer to the Wiki for more detailed information. Additionally, make sure to review the provided guidance on avoiding issues while creating rules.
It is possible to create complex rules with multiple conditions and actions. Each rule can define multiple conditions and actions. The plugin entry point is the BuildHistoryManager class, which extends from the Jenkins core BuildDiscarder class. The Rule.perform() method serves as the core function responsible for processing conditions and actions.
The plugin is called by the Jenkins core when the build is completed. It is not tied to any particular run such as the last completed run, which could potentially be deleted by certain actions. To assist with troubleshooting and analysis, the plugin logs helpful messages to the Jenkins logs.
For debugging purposes, you can use the ChangeBuildDescriptionAction action. This action allows you to update the build description, making it convenient to test and debug conditions before applying actual deletions as actions.
Once you have developed a new feature or improvement, it is essential to conduct thorough testing by implementing multiple unit or integration tests. This ensures the reliability and functionality of the implemented changes.
Please refer to the release notes for the changelog and specific details about the changes made in each version.
If you come across an issue, you can contribute by either sending a pull request to resolve it or filing a bug report.
This applies similarly if you come across a missing Action
or Condition
.
In addition, it is important to remember the following steps: