Build History Manager Plugin

Jenkins plugin that allows to build complex rules to define which builds should be removed from the history and which preserved.

Usage

The motivation of creating this plugin is to deliver powerful tool that allows to define rules that are built from two types of objects:

Examples

Retain most recent broken build

Following configuration has two rules. First one makes sure that the newest build with failure status is not deleted. Second deletes all builds which are not success. In other words it keeps the most recent broken build and all stables.

pipeline {
    agent any

    options {
        buildDiscarder(BuildHistoryManager([
            [
                conditions: [
                    BuildResult(matchFailure: true)
                ],
                matchAtMost: 1,
                continueAfterMatch: false
            ],
            [
                conditions: [
                    BuildResult(matchAborted: true, matchFailure: true, matchUnstable: true)
                ],
                actions: [DeleteBuild()]
            ]
        ]))
    }

    stages {
        stage('Demo') {
            steps {
                echo "Hello!"
            }
        }
    }
}

Remove builds based on a parameter

Following configuration has three rules. The first uses the token macro condition to test the value of a parameter. It removes jobs where the string value of ENABLE_HISTORY is "false". The second rule will preserve the last 24 builds that do not match the first rule. The third rule deletes the remainder of jobs. Thus the 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!"
            }
        }
    }
}

Conditions

Following simple configuration allows to save last 5 builds, rest will be deleted: Condition filters out builds which should be performed by actions. So plugin can filter builds by:

build result
variables for which you can use Token Macro plugin

Actions

Actions defines how the build filtered by above condition) should be modified. Plugin can:

mark the build to be kept forever
delete the build
delete artifacts

Wiki

Read Wiki for more details. Check also information how to avoid problems when creating rules.

There is possibility to build complex rules. Each rule can define more than single condition and action. Plugin starts as BuildDiscarder class. Core method that is responsible for processing conditions and actions are stored in Rule.perform() method.

Troubleshooting

Plugin performs when the builds end. It is not connected to any particular run (like last completed job) which might be deleted by some actions. It logs helpful messages to Jenkins logs.

Configuration

Use cases

Using conditions and actions there is easy to realize following scenarios:

Delete builds which are unstable or aborted if they are not valuable from the history/audit point of view.
Keep only last build per result. So the history contain the most recent builds for result aborted, unstable, failure and success.
Keep builds only from master branch if the project builds all branches including feature branches
Remove builds which have build number lower than given value to easily drop all old builds at once.

Code quality

Once you developed your new feature or improvement you should test it by providing several unit or integration tests.

Release notes

Check release notes for changelog details.

Contribution

If you find the issue you can send pull request to fix it or file the bug. The same about missing Action or Condition Remember about:

doing tests on your local Jenkins instance
adding new unit tests according to given -> when -> then approach.
remember about integration tests and wiki update

mtughan/build-history-manager-plugin