Expressions

The core building block across PullApprove are "expressions". Expressions allow you to write custom, low-code rules for your code review workflows.

Expressions are evaluated in a secure, isolated Python environment, using a set of provided functions and variables. You can use human-readable operators like in, not in, and, and, or (in addition to ==, !=, >, etc.).

In addition to a set of "utility" functions and objects, the expressions environment includes a lightweight abstraction of data available via the GitHub API. This allows you to write custom rules that are easy to read and understand, without having to worry about the implementation details of the GitHub API.

For example, this expression matches PRs where README.md was modified:

"README.md" in pull.files

All of the available functions and objects are available in the UI as you type. Some of the variables change depending what the expression is being applied to.

Examples

GitHub

Author

pull.author == "example-username"

pull.author == "dependabot[bot]"

Labels

"dependencies" in pull.labels

Branches

pull.base.ref == "master"

Repos

pull.repo == "example/example"

Statuses and checks

"continuous-integration/jenkins" in pull.statuses.succeeded

"test" in pull.check_runs.succeeded

Title and description

"WIP" in pull.title

"- [ ]" not in pull.body

Files

"docs/README.md" in pull.files

fnmatch_filter(pull.files, "*.json")

Review teams

teams.all_approved

teams["Code review"].approved

PR size

pull.changed_files > 10

(pull.additions + pull.deletions) > 500

Bitbucket (beta)

Author

pull.author == "example-username"

pull.author == "dependabot[bot]"

Branches

pull.base.ref == "master"

Repos

pull.repo == "example/example"

Title and description

"WIP" in pull.title

"- [ ]" not in pull.description

Files

"docs/README.md" in pull.diffstat

fnmatch_filter(pull.diffstat, "*.json")

Review teams

teams.all_approved

teams["Code review"].approved

Templates

In notifications you can use expressions to customize the content of the message.

These templates are rendered using Jinja, and have similar variables and functions available as expressions.

To output a variable, you use the Jinja {{ variable }} syntax. See the Jinja documentation for more details.

FAQs

What about Python's list comprehension syntax?

Unfortunately, the Python list comprehension syntax is not supported in expressions. Instead you can use items.filter() and items.map() methods, among others.