Log in to v3

On this page

Single vs multi-lineExamplesFilesBranchesLabelsOther PullApprove groupsChecks and statusesTitleBody/descriptionSizeAuthorMergeabilityGit diff and files changedDates

Expressions

PullApprove expressions allow you to write powerful, custom rules to design your workflow.

Expressions are evaluated in a Python environment, using the provided functions and variables. You can use human-readable operators like "in", "not in", "and", and, "or".

The same syntax powers the group conditions, overrides, and notification filters.

Single vs multi-line

Most basic expressions can be written in a single line. In YAML, you'll typically want to surround these with single-quotes since you'll have double-quotes inside (or vice versa):

version: 3
groups:
  api:
    conditions:
    - '"API" in title'

When you're comparing lots of values, it may be easier to write the expression over multiple lines using the > syntax:

version: 3
overrides:
- if: >
    not contains_any_fnmatches(files, [
      "packages/*",
      "apps/*",
      "docs/*",
      ])
  status: success

Examples

You can apply the same basic operations to most of the data we make available. Here are some common examples of how to use the available functions and variables.

Files

Basic string comparisons will use fnmatch under the hood.

"*.js" in files or "frontend/*" in files

You can also use the contains_any_fnmatch function to check more paths at once without writing lots of "or" lines.

contains_any_fnmatches(files, [
    "packages/*",
    "apps/*",
    "docs/*",
    ])

Or globs using contains_any_globs:

contains_any_globs(files, [
    "packages/animations/**",
    "packages/platform-browser/animations/**",
    "aio/content/guide/animations.md",
    "aio/content/examples/animations/**",
    "aio/content/images/guide/animations/**",
    "aio/content/guide/complex-animation-sequences.md",
    "aio/content/guide/reusable-animations.md",
    "aio/content/guide/route-animations.md",
    "aio/content/guide/transition-and-triggers.md",
    ])

Or a glob() instance:

glob("packages/**/*.js") in files

You can also chain the include and exclude methods to further filter down a list of files:

files.include("src/*").exclude("*.md")

Branches

Use branch variables to enable review depending on PR branch names or where it's being merged into:

# Reference a hardcoded branch name
base.ref == "master"

# Or another variable
base.ref != base.repo.default_branch

# Or use the standard comparision operators
"feature/" in head.ref

Labels

# Standard strings
"bug" in labels

# String patterns (fnmatch)
"sig-*" in labels

# Regular expressions
regex('.*/app') in labels

Other PullApprove groups

Use the state of preceding groups (above the current group in your config).

# Use list operators
len(groups.approved) > 3

# Or basic logic by name
"admins" in groups.passing

Checks and statuses

The "checks" on a PR come in two forms: the Checks API, and the commit Statuses API.

The GitHub interface often combines these, making it hard to tell the difference. The best way to tell the difference is to look for the Checks tab on a PR page. For anything on that page (like GitHub Actions/Workflows), use the check_runs object. If you have a status that is not on that page, it will be found in statuses.

GitHub pull request "Checks" tab

Checks

"build" not in check_runs.failed

Statuses

"*travis*" in statuses.succeeded

Title

# Use basic string comparisions
"WIP" in title

# Or fnmatch
"WIP*" in title

# Or regular expressions
regex("WIP: .*") in title

Body/description

"needs review" in body

Size

changed_files > 30

Author

author in ["internA", "internB"]

GitHub also has an author_association variable which can be used (check possible values here):

author_association == "FIRST_TIME_CONTRIBUTOR"

Mergeability

not mergeable

Git diff and files changed

contains_fnmatch(files.lines_added, '*dangerouslySetInnerHTML*')

Dates

created_at < date('3 days ago')