Configuring Batch Changes

Batch Changes is generally configured through the same site configuration and code host configuration as the rest of Sourcegraph. However, Batch Changes features may require specific configuration, and those are documented here.

Rollout windows

By default, Sourcegraph attempts to reconcile (create, update, or close) changesets as quickly as the rate limits on the code host allow. This can result in CI systems being overwhelmed if hundreds or thousands of changesets are being handled as part of a single batch change.

Configuring rollout windows allows changesets to be created and updated at a slower or faster rate based on the time of day and/or the day of the week. These windows are applied to changesets across all code hosts.

Rollout windows are configured through the batchChanges.rolloutWindows site configuration option. If specified, this option contains an array of rollout window objects that are used to schedule changesets. The format of these objects is given below.

Behavior

When rollout windows are enabled, changesets will initially enter a Scheduled state when their batch change is applied. Hovering or tapping on the changeset’s state icon will provide an estimate of when the changeset will be reconciled.

To restore the default behavior, you can either delete the batchChanges.rolloutWindows option, or set it to null.

Or, to put it another way:

batchChanges.rolloutWindows configuration Behavior
Omitted, or set to null Changesets will be reconciled as fast as the code host allows; essentially the same as setting a single {"rate": "unlimited"} window.
Set to an array (even if empty) Changesets will be reconciled using the rate limit in the current window using the leaky bucket behavior described below. If no window covers the current period, then no changesets will be reconciled until a window with a non-zero rate opens.
Any other value The configuration is invalid, and an error will appear.

Leaky bucket rate limiting

Rate limiting uses the leaky bucket algorithm to smooth bursts in reconciliations.

Practically speaking, this means that the given rate can be thought of more as an average than as a simple resource allocation. If there are always changesets in the queue, a rate of 10/hour means that a changeset will be reconciled approximately every six minutes, rather than ten changesets being simultaneously reconciled at the start of each hour.

Rollout window object

A rollout window is a JSON object that looks as follows:

{
  "rate": "10/hour",
  "days": ["saturday", "sunday"],
  "start": "06:00",
  "end": "20:00"
}

All fields are optional except for rate, and are described below in more detail. All times and days are handled in UTC.

In the event multiple windows overlap, the last defined window will be used.

rate

rate describes the rate at which changesets will be reconciled. This may be expressed in one of the following ways:

  • The string unlimited, in which case no limit will be applied for this window, or
  • A string in the format N/UNIT, where N is a number and UNIT is one of second, minute, or hour; for example, 10/hour would allow 10 changesets to be reconciled per hour, or
  • The number 0, which will prevent any changesets from being reconciled when this window is active.

days

days is an array of strings that defines the days of the week that the window applies to. English day names are accepted in a case insensitive manner:

  • ["saturday", "sunday"] constrains the window to Saturday and Sunday.
  • ["tuesday"] constrains the window to only Tuesday.

If omitted or an empty array, all days of the week will be matched.

start and end

start and end define the start and end of the window on each day that is matched by days, or every day of the week if days is omitted. Values are defined as HH:MM in UTC.

Both start and end must be provided or omitted: providing only one is invalid.

Examples

To rate limit changeset publication to 3 per minute between and UTC on weekdays, and allow unlimited changesets outside of those hours:

[
  {
    "rate": "unlimited"
  },
  {
    "rate": "3/minute",
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "start": "08:00",
    "end": "16:00"
  }
]

To only allow changesets to be reconciled at 1 changeset per minute on (UTC) weekends:

[
  {
    "rate": "1/minute",
    "days": ["saturday", "sunday"]
  }
]