Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see http://docs.buildbot.net/current/.

2.5.24.2. ChangeFilter

class buildbot.util.ChangeFilter

This class is used to filter changes. It is conceptually very similar to SourceStampFilter except that it operates on changes. The class accepts a set of conditions. A change is considered acepted if all conditions are satisfied. The conditions are specified via the constructor arguments.

The following parameters are supported by the ChangeFilter:

project, repository, branch, category, codebase

(optional, a string or a list of strings) The corresponding attribute of the change must match exactly to at least one string from the value supplied by the argument.

branch uses util.NotABranch as its default value which indicates that no checking should be done, because the branch may actually have None value to be checked.

project_not_eq, repository_not_eq, branch_not_eq, category_not_eq, codebase_not_eq

(optional, a string or a list of strings) The corresponding attribute of the change must not match exactly to any of the strings from the value supplied by the argument.

branch uses util.NotABranch as its default value which indicates that no checking should be done, because the branch may actually have None value to be checked.

project_re, repository_re, branch_re, category_re, codebase_re

(optional, a string or a list of strings or regex pattern objects) The corresponding attribute of the change must match to at least one regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

project_not_re, repository_not_re, branch_not_re, category_not_re, codebase_not_re

(optional, a string or a list of strings or regex pattern objects) The corresponding attribute of the change must not match to at least any regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

property_eq

(optional, a dictionary containing string keys and values each of which with a string or a list of strings) The property of the change with corresponding name must match exactly to at least one string from the value supplied by the argument.

property_not_eq

(optional, a string or a list of strings) The property of the change with corresponding name must not be present or not match exactly to at least one string from the value supplied by the argument.

property_re

(optional, a string or a list of strings or regex pattern objects) The property of the change with corresponding name must match to at least one regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

property_not_re

(optional, a string or a list of strings or regex pattern objects) The property of the change with corresponding name must not be present or not match to at least one regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

project_fn, repository_fn, branch_fn, category_fn, codebase_fn

(optional, a callable accepting a string and returning a boolean) The given function will be passed the value from the change that corresponds to the parameter name. It is expected to return True if the change is matched, False otherwise. In case of a match, all other conditions will still be evaluated.

filter_fn

(optional, a callable accepting a Change object and returning a boolean) The given function will be passed the change. It is expected to return True if the change is matched, False otherwise. In case of a match, all other conditions will still be evaluated.

Secrets in conditions

ChangeFilter does not support renderables. Accordingly, secrets cannot be used to construct the conditions that will later be used to filter changes.

This does not reduce security of the system because in order for secret values to be useful for filtering, they will need to be present in the changes themselves. The change information is stored in the database and frequently appears in the logs.

Best practice is to make sure secret values are not encoded in changes such as in repository URLs. Most of the source steps support passing authentication information separately from repository URL.

If encoding secrets is unavoidable, then changes should be filtered using regex (e.g. via repository_re argument) or custom callback functions (e.g. via repository_fn or filter_fn arguments).

Examples

ChangeFilter can be setup like this:

from buildbot.plugins import util
my_filter = util.ChangeFilter(project_re="^baseproduct/.*", branch="devel")

and then assigned to a scheduler with the change_filter parameter:

sch = SomeSchedulerClass(..., change_filter=my_filter)

buildbot.www.hooks.github.GitHubEventHandler has a special github_distinct property that can be used to specify whether or not non-distinct changes should be considered. For example, if a commit is pushed to a branch that is not being watched and then later pushed to a watched branch, by default, this will be recorded as two separate changes. In order to record a change only the first time the commit appears, you can use a custom ChangeFilter like this:

ChangeFilter(filter_fn=lambda c: c.properties.getProperty('github_distinct'))

For anything more complicated, a Python function can be defined to recognize the wanted strings:

def my_branch_fn(branch):
    return branch in branches_to_build and branch not in branches_to_ignore
my_filter = util.ChangeFilter(branch_fn=my_branch_fn)