4.10.2 Merging Build Requests

When more than one build request is available for a builder, Buildbot can "merge" the requests into a single build. This is desirable when build requests arrive more quickly than the available slaves can satisfy them, but has the drawback that separate results for each build are not available.

This behavior can be controlled globally, using the c['mergeRequests'] parameter, and on a per-builder basis, using the mergeRequests argument to the builder configuration. If mergeRequests is given, it completely overrides the global configuration.

For either configuration parameter, a value of True (the default) causes buildbot to merge BuildRequests that have "compatible" source stamps. Source stamps are compatible if:

• their branch, project, and repository attributes match exactly;
• neither source stamp has a patch (e.g., from a try scheduler); and
• either both source stamps are associated with changes, or neither ar associated with changes but they have matching revisions.

This algorithm is implemented by the SourceStamp method canBeMergedWith.

A configuration value of False indicates that requests should never be merged.

If the configuration value is a callable, that callable will be invoked with three positional arguments: a Builder object and two BuildRequest objects. It should return true if the requests can be merged, and False otherwise. For example:

     def mergeRequests(builder, req1, req2):
         "any requests with the same branch can be merged"
         return req1.branch == req2.branch
     c['mergeRequests'] = mergeRequests

In many cases, the details of the SourceStamps and BuildRequests are important. In this example, only BuildRequests with the same "reason" are merged; thus developers forcing builds for different reasons will see distinct builds. Note the use of the canBeMergedWith method to access the source stamp compatibility algorithm.

     def mergeRequests(builder, req1, req2):
         if req1.source.canBeMergedWith(req2.source) and  req1.reason == req2.reason:
            return True
         return False
     c['mergeRequests'] = mergeRequests

If it's necessary to perform some blocking operation to determine whether two requests can be merged, then the mergeRequests callable may return its result via Deferred. Note, however, that the number of invocations of the callable is proportional to the square of the request queue length, so a long-running callable may cause undesirable delays when the queue length grows.