PullApprove is a product of Dropseed

Conditions

Conditions are how you decide when a group should be asked to look at a PR. Often times, people will set this up based on specific filetypes or languages. The same data and syntax also powers the pullapprove_conditions and notification filters.

Things to know

  • Every condition in the list must be true to activate the group
  • If you need to "or" a condition, do it in a single list item with the word "or"
  • Conditions must be strings (almost always need to be surrounded by quotes to be proper YAML)

Under the hood, conditions are evaluated as Python. There is a specific set of functions that you can use and variables you have access to. This allows you to write flexible, powerful "if" statements while still being readable. Note that in Python, some operators are written as more readable words, such as "in", "not in", "and", and, "or".

Examples

Comparing objects

conditions:
- "'bug' in labels"
- "'sig-*' in labels"
- "regex('.*/app') in labels"
- "'*.py' in files or '*.js' in files"
- "'*travis*' in statuses.succeeded"
- "base.ref == 'master'"
- "base.ref != base.repo.default_branch"
- "not mergeable"
- "created_at < date('3 days ago')"

Comparing strings

For variables that are simply strings, you'll need to use specific functions to compare with regular expressions or fnmatch syntax.
conditions:
- "'WIP' in title"  # checks for 'WIP' anywhere in the string
- "contains_fnmatch(title, 'WIP*')"
- "contains_regex(title, 'WIP: .*')"
- "'feature' in head.ref"
- "contains_fnmatch(head.ref, 'feature*')"

Files and Paths

Often times reviewers are decided by the changes made in a PR. You can use include and exclude to build more complex rules for who needs to review what changes.
conditions:
# review any changes in src unless they only involved markdown
- "files.include('src/*').exclude('*.md')"
# review changes to any non-python tests
- "files.include('*test*').exclude('*.py')"

Context reference

The following variables are directly available when writing conditions and templates. For variables that are custom objects, see their properties further down the page.

Don't see what you need? Let us know.

Property Type Note
all function

Return True if bool(x) is True for all values x in the iterable.

If the iterable is empty, return True.

any function

Return True if bool(x) is True for any x in the iterable.

If the iterable is empty, return False.

length function

Return the number of items in a container.

len function

Return the number of items in a container.

count function

Return the number of items in a container.

regex function

regex('WIP: .*')

contains_fnmatch function

contains_fnmatch(title, 'WIP*')

contains_any_fnmatches function

contains_any_fnmatches(files, ['api/*', 'tests/*'])

contains_regex function

contains_regex(title, 'WIP.*')

date function

Parses a date from a string using dateparser.

date('3 days ago')

date('8/10/1995')

text_list function

Returns a readable, comma-separated list of items for printing in templates.

text_list(['a', 'b', 'c', 'd']) == 'a, b, c or d'

text_list(['a', 'b', 'c'], 'and') == 'a, b and c'

text_list(['a', 'b'], 'and') == 'a and b'

text_list(['a']) == 'a'

text_list([]) == ''

node_id str
merge_commit_sha str
statuses Statuses
closed_at datetime
merged_by User
created_at datetime
maintainer_can_modify bool
patch_url str
number int
locked bool
review_comments_url str
review_comments int
commits_url str
commits int
merged bool
changed_files int
milestone Milestone
state str
rebaseable bool
deletions int
author_association str
files Files
body str
url str
merged_at datetime
diff_url str
assignee User
author User
updated_at datetime
title str
issue_url str
comments int
mergeable bool
labels Labels
head Branch
assignees Users
statuses_url str
comments_url str
additions int
requested_reviewers Users
requested_teams Teams
review_comment_url str
base Branch
html_url str
user User
mergeable_state str
id int
groups Groups

Statuses

Statuses are pulled from the most recent commit on the pull request. See the GitHub documentation for more information.

Property Type Note
contexts list of str
errored Statuses
exclude method

Filter down the list of objects using not contains behavior. Chainable with include.

files.excludes("*.md")

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

failed Statuses
include method

Filter down the list of objects using contains behavior. Chainable with exclude.

files.include("src/*")

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

pending Statuses
succeeded Statuses
successful Statuses

Status

Property Type Note
avatar_url str
context str
created_at datetime
creator dict
description str
id int
node_id str
state str
target_url str
updated_at datetime
url str

User

Property Type Note
avatar_url str
events_url str
followers_url str
following_url str
gists_url str
gravatar_id str
html_url str
id int
login str
mention str
node_id str
organizations_url str
received_events_url str
repos_url str
site_admin bool
starred_url str
subscriptions_url str
type str
url str
username str

Milestone

Property Type Note
closed_at datetime
closed_issues int
created_at datetime
creator User
description str
due_on datetime
html_url str
id int
labels_url str
node_id str
number int
open_issues int
state str
title str
updated_at datetime
url str

Files

See the GitHub documentation for more information.

Property Type Note
added Files
exclude method

Filter down the list of objects using not contains behavior. Chainable with include.

files.excludes("*.md")

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

filenames list of str
include method

Filter down the list of objects using contains behavior. Chainable with exclude.

files.include("src/*")

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

modified Files
removed Files

File

Property Type Note
additions int
blob_url str
changes int
contents_url str
deletions int
filename str
patch str
raw_url str
sha str
status str

Labels

Property Type Note
exclude method

Filter down the list of objects using not contains behavior. Chainable with include.

files.excludes("*.md")

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

include method

Filter down the list of objects using contains behavior. Chainable with exclude.

files.include("src/*")

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

names list of str

Label

Property Type Note
color str
default bool
id int
name str
node_id str
url str

Branch

Property Type Note
label str
ref str
repo Repo
sha str
user User

Repo

Property Type Note
archive_url str
archived bool
assignees_url str
blobs_url str
branches_url str
clone_url str
collaborators_url str
comments_url str
commits_url str
compare_url str
contents_url str
contributors_url str
created_at datetime
default_branch str
deployments_url str
description str
downloads_url str
events_url str
fork bool
forks int
forks_count int
forks_url str
full_name str
git_commits_url str
git_refs_url str
git_tags_url str
git_url str
has_downloads bool
has_issues bool
has_pages bool
has_projects bool
has_wiki bool
homepage str
hooks_url str
html_url str
id int
issue_comment_url str
issue_events_url str
issues_url str
keys_url str
labels_url str
language str
languages_url str
license str
merges_url str
milestones_url str
mirror_url str
name str
node_id str
notifications_url str
open_issues int
open_issues_count int
owner User
private bool
pulls_url str
pushed_at datetime
releases_url str
size int
ssh_url str
stargazers_count int
stargazers_url str
statuses_url str
subscribers_url str
subscription_url str
svn_url str
tags_url str
teams_url str
trees_url str
updated_at datetime
url str
watchers int
watchers_count int

Users

Property Type Note
exclude method

Filter down the list of objects using not contains behavior. Chainable with include.

files.excludes("*.md")

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

include method

Filter down the list of objects using contains behavior. Chainable with exclude.

files.include("src/*")

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

mentions list of str
usernames list of str

Teams

Property Type Note
exclude method

Filter down the list of objects using not contains behavior. Chainable with include.

files.excludes("*.md")

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

ids list of int
include method

Filter down the list of objects using contains behavior. Chainable with exclude.

files.include("src/*")

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

names list of str

Team

Property Type Note
description str
id int
members_url str
name str
node_id str
permission str
privacy str
repositories_url str
slug str
url str

Groups

Groups is a list of Group objects with a few handy shortcuts.

Property Type Note
active Groups
approved Groups
exclude method

Filter down the list of objects using not contains behavior. Chainable with include.

files.excludes("*.md")

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

inactive Groups
include method

Filter down the list of objects using contains behavior. Chainable with exclude.

files.include("src/*")

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

names list of str
passing Groups
pending Groups
rejected Groups

Group

A PullApprove review group

Property Type Note
author_value int
conditions list
is_active bool
is_passing bool
name str
request int
request_order str
required int
score int
state str
teams list
users list of str
users_approved list
users_available list
users_pending list
users_rejected list
users_requested list
users_unavailable list
users_unrequested list