Nullgap.dev Docs

Pull request review

Review filters

Choose which pull requests are reviewed automatically, by label, author, branch or keyword.

Review filters decide which pull requests in a covered repository are reviewed automatically. With no filters, every pull request that is not a draft is reviewed.

Filters are one list for the whole organisation. They apply to reviews started by a pull request being opened or updated. They do not apply to a review someone asks for with @nullgap review, in the console or through the API.

#What a filter is

A filter has three parts.

PartValuesIn the console
modeexclude or includeSkip or Only review
kindlabel, author, branch or keywordLabel, Author, Target branch, Title keyword
valueText, up to 200 charactersThe text box

How each kind matches a pull request:

KindMatches whenCase-sensitiveWildcards
labelThe pull request has a label with exactly this name. Left out on Bitbucket Cloud, whose pull requests have no labels.NoNo
authorThe author's login on the code host is exactly this.NoNo
branchThe target branch or the source branch matches the pattern.No* stands for any run of characters. Everything else is literal.
keywordThe text appears anywhere in the pull request's title or description.NoNo

Two details differ from what the console labels suggest: a branch filter looks at the source branch as well as the target branch, and a keyword filter looks at the description as well as the title.

#How filters combine

  1. Exclude filters are checked first, and any one that matches wins. The pull request is skipped, whatever the include filters say.
  2. Then include filters are checked, kind by kind. For each kind that has at least one include filter, the pull request must match at least one of them. If a kind has no include filters, it does not restrict anything.

Put another way: include filters of the same kind are alternatives (label A or label B), include filters of different kinds must all be satisfied (one of the labels and one of the branches), and a single matching exclude overrides everything.

A filtered pull request is recorded under PR reviews as skipped with the reason, for example Excluded by author filter "dependabot[bot]" or Does not match any branch include filter. Nothing is posted on the pull request, and no review seat is used for its author.

Filters are evaluated each time an event arrives. Adding a label to an open pull request does not start a review by itself; the next push is evaluated with the new label.

#Examples

#Skip dependency bots

[
  { "kind": "author", "mode": "exclude", "value": "dependabot[bot]" },
  { "kind": "author", "mode": "exclude", "value": "renovate[bot]" }
]

#Review only pull requests into main and release branches

[
  { "kind": "branch", "mode": "include", "value": "main" },
  { "kind": "branch", "mode": "include", "value": "release/*" }
]

Because a branch filter also matches the source branch, a pull request from release/1.4 into some other branch is reviewed by this as well.

#Review only what is labelled, but never what is marked to skip

[
  { "kind": "label", "mode": "include", "value": "security-review" },
  { "kind": "label", "mode": "exclude", "value": "skip-security" }
]

A pull request with both labels is skipped, because excludes win.

#Combine kinds

[
  { "kind": "branch", "mode": "include", "value": "main" },
  { "kind": "label", "mode": "include", "value": "backend" },
  { "kind": "label", "mode": "include", "value": "api" },
  { "kind": "keyword", "mode": "exclude", "value": "[skip nullgap]" }
]

Reviewed: pull requests that involve main, carry the label backend or api, and do not have [skip nullgap] in the title or description.

#Set filters in the console

Open Settings, the PR reviews tab, and find Filters under Review defaults. Press Add filter, choose Skip or Only review, the field and the value, then press Save filters. Every filter needs a value.

#Set filters with the API

Filters are part of the organisation settings. Read them (any key):

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/settings"

Write them (a key with the admin scope). The list you send replaces the whole list, so send every filter you want to keep. An empty list removes all filters.

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": [{"kind": "author", "mode": "exclude", "value": "dependabot[bot]"}, {"kind": "branch", "mode": "include", "value": "main"}]}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/settings"

Limits: up to 100 filters, each value 1 to 200 characters. An unknown kind or mode, or an empty value, is refused with 400.

#Things to know per code host

  • Author. The value is compared with the author as the code host names them. On GitHub and GitLab that is the user name. On Bitbucket Cloud it is the account id, and on Azure DevOps the sign-in name, so write author filters in that form there. The author shown on a review under PR reviews is the exact text to use.
  • Labels on Bitbucket Cloud. Bitbucket pull requests carry no labels for Nullgap to read. An exclude filter on a label never matches there, and an include filter on a label matches nothing, which skips every Bitbucket pull request. Do not use label include filters if you review Bitbucket repositories.
  • Drafts are skipped before filters are looked at. On GitLab and Bitbucket Cloud a title starting with Draft: or WIP: also counts as a draft. See why a review is skipped.

#Filters and manual reviews

A person asking for a review overrides the filters. If a filter excludes a bot's pull requests and someone comments @nullgap review on one, it is reviewed, and the author then takes a review seat like anyone else.

Nullgap documentation