4.8.2 Change Filters

Several schedulers perform filtering on an incoming set of changes. The filter can most generically be specified as a ChangeFilter. Set up a ChangeFilter like this:

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

and then add it to a scheduler with the change_filter parameter:

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

There are four attributes of changes on which you can filter:

• project the project string, as defined by the ChangeSource.
• repository the repository in which this change occurred.
• branch the branch on which this change occurred. Note that 'trunk' or 'master' is often denoted by None.
• category the category, again as defined by the ChangeSource.

For each attribute, the filter can look for a single, specific value:

     my_filter = ChangeFilter(project = 'myproject')

or accept any of a set of values:

     my_filter = ChangeFilter(project = ['myproject', 'jimsproject'])

It can apply a regular expression, use the attribute name with a suffix of _re:

     my_filter = ChangeFilter(category_re = '.*deve.*')
     # or, to use regular expression flags:
     import re
     my_filter = ChangeFilter(category_re = re.compile('.*deve.*', re.I))

For anything more complicated, define a Python function to recognize the strings you want:

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

The special argument filter_fn can be used to specify a function that is given the entire Change object, and returns a boolean.

A Change passes the filter only if all arguments are satisfied. If no filter object is given to a scheduler, then all changes will be built (subject to any other restrictions the scheduler enforces).