Skip to main content
Version: v4

Built-ins

Below is the comprehensive list of all available built-ins:

addAssignees


Description:

Assigns a defined amount of assignees to a pull request / issue.

Users already assigned to a pull request / issue are not replaced.

Parameters:

ParameterTypeDescription
assignees[]stringThe list of GitHub logins to assign the pull request / issue to.
total (optional)intThe total number of assignees to assign to, between 1 and 10. By default, it assigns to all assignees.

Examples:

$addAssignees(["john", "marie", "peter"])
$addAssignees($getTeamMembers("engineering"), 2)

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-core-team
run:
if: $getAuthor() == "renovate[bot]"
then: $addAssignees($getTeamMembers("core"), 1)

addComment


Description:

Posts a comment to the pull request / issue once.

If the comment is already present, then the action does nothing.

Parameters:

ParameterTypeDescription
commentstringThe body of the comment.

Examples:

$addComment("This is your first contribution! Thank you!")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: congratulate
run:
if: $countUserPullRequests($getAuthor(), "all") == 1
then: $addComment("Thank you for your first contribution!")

addLabel


Description:

Adds a label to the pull request / issue.

If the label is not applied to the pull request / issue then nothing happens.

It will check if there is a label with this key in the labels section of reviewpad.yml.

If such label exists, it will use the name property of the label; if the property is not present, then it uses the key as the name.

If such label does not exist in labels, it will use the provided input string and create a label with that name.

Here's an example:

reviewpad.yml
labels:
small:
name: Small Change
description: Few files
medium:
description: Some files

workflows:
- name: add-label
run:
if: $getSize() < 10
then:
- $addLabel("small") # creates the label "Small Change" with description "Few files"
- $addLabel("medium") # creates the label "medium" with description "Some files"
- $addLabel("large") # creates the label "large" without description

Parameters:

ParameterTypeDescription
namestringThe name of the label to add.

Examples:

$addLabel("bug")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-small-pull-request
run:
if: $getSize() < 10
then: $addLabel("small")

addReviewers


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Assigns a defined amount of reviewers to the pull request from the provided list of reviewers.

Reviewers can be assigned following one of the described policies:

  • random: the reviewers are chosen in a random manner;
  • round-robin: the reviewers are chosen following the round-robin algorithm;
  • reviewpad: the reviewers are chosen based on the total number of pull requests assigned to them. The smaller the number of pull requests assigned to a reviewer, the greater the probability of being picked.

When there are not enough reviewers to assign to, a warning is returned.

If a reviewer from the defined list has performed a review, their review will be re-requested.

Parameters:

ParameterTypeDescription
reviewers[]stringThe list of GitHub logins to select from.
total (optional)intThe total number of reviewers to assign to. By default, it assigns to all reviewers.
policy (optional)stringThe policy followed for reviewer assignment. By default, the policy is reviewpad.

Examples:

$addReviewers(["john", "marie", "peter"], 2, "random")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: reviewers-assignment
run:
- if: $isElementOf($getAuthor(), $getTeamMembers("devops"))
then: $addReviewers($getTeamMembers("devops"))
- if: $isElementOf($getAuthor(), $getTeamMembers("juniors"))
then: $addReviewers($getTeamMembers("seniors"), 1, "reviewpad")

addReviewersBasedOnCodeAuthor


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Assigns the most relevant and available reviewers to the pull request.

The relevancy is based on the code ownership information available on the impacted source files. The more lines of code are owned by a reviewer on the impacted source files, the more relevant this reviewer is for the pull request.

The availability is based on the number of open pull requests per reviewer. Above a configurable threshold (max_reviews), the reviewer is considered unavailable.

The assigned reviewers will always be different than the pull request's author.

If no relevant reviewers are available for the pull request, the reviewers are randomly selected from the list of GitHub repository collaborators.

If the pull request already has a reviewer, no action will be taken.

Parameters:

ParameterTypeDescription
total_required_reviewers (optional)intThe total number of required reviewers. By default, it is one.
excluded_reviewers (optional)[]stringList of usernames to exclude from review requests.
max_reviews (optional)intThe maximum number of open pull requests that a single user can be responsible for reviewing.

Examples:

$addReviewersBasedOnCodeAuthor(2, ["john", "marie"], 3)

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-reviewer
run:
if: "!$hasAnyPendingReviews() && !$isDraft()"
then: $addReviewersBasedOnCodeAuthor(2, ["john", "marie"], 3)

addReviewerRandomly


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Assigns a random user of the GitHub organization as the reviewer. This action will always pick a user different than the author of the pull request.

However, if the pull request already has a reviewer, nothing happens. This is to prevent adding a reviewer each time the pull request is updated.

When there's no reviewers to assign to, an error is returned.

Parameters:

none

Examples:

$addReviewerRandomly()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-reviewer
run:
if: $getDescription() != ""
then: $addReviewerRandomly()

addTeamsForReview


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Assigns a list of teams to review the pull request.

Parameters:

ParameterTypeDescription
team_reviewers[]stringThe list of GitHub team slugs that will be requested to review.

Examples:

$addTeamsForReview(["core", "support"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: reviewers-assignment
run:
if: $containsCodePattern("critical\(.*\)")
then: $addTeamsForReview(["core"])

addToProject


Description:

Adds a pull request / issue to a project with a particular status.

If the project doesn't exist, an error is returned.

If the status doesn't exist, an error is returned.

Parameters:

ParameterTypeDescription
project_titlestringThe title of the project - case sensitive.
statusstringThe status of the pull request / issue (must exist as a status).

Examples:

$addToProject("reviewpad", "in progress")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: add-to-project
run:
if: $hasLinkedIssues() == false
then: $addToProject("jupiter", "in progress")

all


Description:

Determines if all elements of the slice satisfy the given predicate.

Parameters:

ParameterTypeDescription
slice[]stringThe slice of strings.
predicate(string => boolean)The predicate over string.

Return value:~

TypeDescription
booleantrue if the predicate is true for all elements of the slice, falseotherwise.

Examples:

'$all(["a", "b"], ($el: String => $el == "a"))' # false

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: merge
run:
# Verify if all reviewers approved the pull request.
if: $hasAnyReviewers() && $hasOnlyApprovedReviews()
then: $merge()

any


Description:

Determines if any element of the slice satisfies the given predicate.

Parameters:

ParameterTypeDescription
slice[]stringThe slice of strings.
predicate(string => boolean)The predicate over string.

Return value:

TypeDescription
booleantrue if the predicate is true for any element of the slice, false otherwise.

Examples:

'$any(["a", "b"], ($el: String => $el == "a"))' # true

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: merge
run:
# Verify if any reviewer approved the pull request.
if: $hasAnyReviewers() && $hasOnlyApprovedReviews()
then: $merge()

append


Description:

Appends elements to the end of a slice and retrieves the updated slice.

Parameters:

ParameterTypeDescription
slice[]stringThe slice that will have elements appended to it.
elements[]stringThe elements to be added to the end of the slice.

Return value:

TypeDescription
[]stringA new slice by appending the slices passed to it.

Examples:

$append(["a", "b"], ["c"]) # ["a", "b", "c"]

A reviewpad.yml example:

reviewpad.yml
groups:
- name: all-devs
kind: developers
spec: $append($getTeamMembers("frontend"), $getTeamMembers("backend"))

workflows:
- name: reviewer-assignment
run:
if: $getDescription() != ""
then: $addReviewers($group("all-devs"), 1)

approve


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

note

This built-in is a shortcut to the review built-in. It is the same as $review("APPROVE", <MESSAGE>).

Description:

Submits a pull request review marked as approved.

Parameters:

ParameterTypeDescription
message (optional)stringThe message to write as a comment.

Examples:

$approve()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: trivial-changes
run:
if: $containsOnlyFileExtensions([".md"])
then: $approve("LGTM")

changed


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

The changed built-in receives two regexes with named capturing groups denoted by the @X pattern.

These regexes are matched against the set of files in the patch.

The built-in checks if the value set of the first regex is contained in the second one.

Parameters:

ParameterTypeDescription
pre_file_patternstringThe antecedent file pattern expression.
post_file_patternstringThe consequent file pattern expression.

Return value:

TypeDescription
booleantrue if the value set of the first regex is contained in the second one, false otherwise.

Examples:

$changed("@1.go", "@1.md")

This spec will return true if for each file in the patch with the extension .go there is also a file in the patch with the same name with the extension .md.

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: validate-changes
run:
if: $changed("src/@1.java", "test/@1.java") == false
then: $fail("Please include tests for your change.")

close


Description:

Closes an pull request / issue with a given comment - without merging it.

By default, if no comment is provided, it will close the pull request / issue without a comment.

For issues, it can also be given a closure reason.

By default, if no closure reason is provided, the issue will be closed as completed.

When a closure reason is provided and we don't want to close the issue with a comment then we need to pass the comment parameter as "".

Parameters:

ParameterTypeDescription
comment (optional)stringThe body of the comment.
reason (optional) (issues only)stringThe reason for closing. The options are completed or not_planned.

Please note that the reason parameter is only available for issues.

Examples:

$close()                                            # close without comment or reason
$close("Closed due inactivity") # close with comment and no reason
$close("", "not_planned") # close with no comment but reason
$close("This project is deprecated", "not_planned") # close with a comment and reason

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: stale
run:
if: $getLastEventTime() < 30 days ago
then:
- $addLabel("stale")
- $close("This pull request has been automatically closed due to inactivity")

- name: project_deprecated
on:
- "issue"
run:
if: $isElementOf("jupiter", $getLabels())
then: $close("The project `jupiter` is deprecated", "not_planned")

contains


Description:

Determines whether a text includes a certain sentence, returning true or false as appropriate.

Parameters:

ParameterTypeDescription
textstringThe text to search in.
search_sentencestringThe sentence to search for.

Return value:

TypeDescription
booleantrue if searchSentence is found within the text, false otherwise.

Examples:

$contains("Testing string contains", "string contains")     #true
$contains("Testing string contains", "test") #false

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: labe-change-type
run:
if: $contains($getTitle(), "fix")
then: $addLabel("bug")

containsBinaryFiles


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Checks if a pull request has a binary file in the patch.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request contains a binary file, false otherwise.

Examples:

$containsBinaryFiles()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: disallow-binary-file
run:
if: $containsBinaryFiles()
then:
- $close()
- $reportBlocker("Please don't add any binary file into the repository")

containsCodeAnnotation


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies if the patch includes a symbol with the specified annotation, returning true or false accordingly. To annotate a symbol, precede the symbol definition with a comment that begins with // reviewpad-an:.

In the example below, the main function is annotated with critical annotation. If this main function is updated as part of a Pull Request, the expression $containsCodeAnnotation("critical") will return true.

// reviewpad-an: critical
func main() {
fmt.Println("Hello, World!")
}

Parameters:

ParameterTypeDescription
annotationstringThe annotation to look for in the patch.

Return value:

TypeDescription
booleantrue if the patch changes a symbol with the provided annotation, false otherwise.

Examples:

$containsCodeAnnotation("critical")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: security-changes
run:
if: $containsCodeAnnotation("security")
then: $addReviewers($getTeamMembers("security"), 1)

containsCodePattern


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies if the patch matches the provided code pattern, returning true or false as appropriate.

The code pattern needs to be a compilable regular expression.

Parameters:

ParameterTypeDescription
query_patternstringThe query pattern to look for in the patch.

Return value:

TypeDescription
booleantrue if the patch matches the query pattern, false otherwise.

Examples:

$containsCodePattern("placeBet\(.*\)")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: critical-code
run:
if: $containsCodePattern("placeBet\(.*\)")
then:
- $addReviewers($getTeamMembers("core"), 1)
- $addLabel("critical")

containsFileName


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Determines whether the provided filename is among the files in the patch, returning true or false as appropriate.

Parameters:

ParameterTypeDescription
filenamestringThe filename to look for in the patch - case sensitive.

Return value:

TypeDescription
booleantrue if the patch has a file with the provided filename, false otherwise. The provided filename and the filename on the patch need to be exactly the same in order to get a positive result.

Examples:

$containsFileName("placeBet.js")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: configuration-changes
run:
if: $containsFileName("Dockerfile")
then:
- $addTeamsForReview(["devops"])
- $addLabel("devops")

containsFilePattern


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Determines whether the provided file pattern matches any of the files in the patch, returning true or false as appropriate.

The file pattern needs to be a glob.

Parameters:

ParameterTypeDescription
file_patternstringThe file pattern glob to look for in the patch.

Return value:

TypeDescription
booleantrue if any of the files in the patch matches the provided file pattern, false otherwise.

Examples:

$containsFilePattern("src/transactions/**")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: core-changes
run:
if: $containsFilePattern("src/transactions/**")
then: $addTeamsForReview(["core"])

containsOnlyCodeWithoutSemanticChanges


🧪 EXPERIMENTAL

This is an experimental built-in. Be careful before using it in production.

caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Checks if a pull request contains only code changes that do not touch the semantics of the software.

Parameters:

ParameterTypeDescription
file_patterns_to_ignore (optional)[]stringThe list of file pattern globs to ignore in the patch.

Return value:

TypeDescription
booleantrue if the pull request changes are not semantic code changes

Examples:

$containsOnlyCodeWithoutSemanticChanges()
$containsOnlyCodeWithoutSemanticChanges(["**/*_test.go"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: LGTM
run:
if: $containsOnlyCodeWithoutSemanticChanges()
then: $approve("LGTM")

containsOnlyFileExtensions


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Determines whether all the extensions of the changed files in the patch are included on the provided list of file extensions, returning true or false as appropriate.

Each extension provided on the list needs to be a glob.

Parameters:

ParameterTypeDescription
extensions[]stringThe list of all file extensions.

Return value:

TypeDescription
booleantrue if all file extensions in the patch are included in the list, false otherwise.

Examples:

$containsOnlyFileExtensions([".test.ts"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: configuration-changes
run:
if: $containsOnlyFileExtensions([".yaml"])
then: $addTeamsForReview(["devops"])

context


Description:

Returns a JSON serialized string of the current context.

The context is the pull request or issue where the built-in is running on.

Parameters:

none

Return value:

TypeDescription
stringJSON serialized string of the current context (pull request /issue )

Examples:

$context()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: debug
run:
if: $isElementOf("debug", $getLabels())
then: $reportInfo($context())

countApprovals


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the total number of approvals for a pull request.

Parameters:

none

Return value:

TypeDescription
intThe total number of approvals the pull request has received.

Examples:

$countApprovals()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: auto-merge
run:
if: $countApprovals() > 2
then: $merge()

countComments


Description:

Retrieves the total number of comments made into the pull request / issue.

Parameters:

none

Return value:

TypeDescription
intThe total number of comments in the pull request / issue.

Examples:

$countComments()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: high-activity
run:
if: $countComments() > 15
then: $reportInfo("Please consider splitting the pull request into smaller pull requests.")

countCommits


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the total number of commits made into the pull request.

Parameters:

none

Return value:

TypeDescription
intThe total number of commits in the pull request.

Examples:

$countCommits()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: high-activity
run:
if: $countCommits() > 10
then: $reportInfo("Please consider splitting the pull request into smaller pull requests.")

countFiles


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the total number of files changed in the patch.

Parameters:

none

Return value:

TypeDescription
intThe total number of files changed in the patch.

Examples:

$countFiles()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: too-big
run:
if: $countFiles() > 10
then: $reportInfo("Please consider splitting the pull request into smaller pull requests.")

countUserReviews


Description:

Retrieves the total number of code reviews made by the given GitHub user login.

Parameters:

ParameterTypeDescription
user_loginstringThe GitHub user login.

Return value:

TypeDescription
intThe total number of code reviews made by the GitHub user login.

Examples:

$countUserReviews($getAuthor())

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-reviewers
run:
if: $countUserReviews($getAuthor()) < 5
then: $addReviewers($getTeamMembers("seniors"), 1, "reviewpad")

countUserIssues


Description:

Retrieves the total number of issues created by the given GitHub user login and issue state.

Note that altough GitHub considers a pull request to be an issue, we exclude pull requests in this request.

Parameters:

ParameterTypeDescription
user_loginstringThe GitHub user login.
state (optional)stringThe issue state (open, closed or all).

Passing the empty string "" to user_login returns the number of issues with a given state in the repository.

Passing the empty string "" or nothing to state defaults to all.

Return value:

TypeDescription
intThe total number of issues created by the given GitHub user login with the state.

Examples:

$countUserIssues($getAuthor())

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: congratulate
run:
- if: $countUserIssues($getAuthor(), "all") == 1
then: $addComment("Congratulations on your first issue!")
- if: $countUserIssues($getAuthor(), "all") == 10
then: $addComment("Way to go! You have created 10 issues!")

countUserPullRequests


Description:

Retrieves the total number of pull requests created by the given GitHub user login and state.

Parameters:

ParameterTypeDescription
user_loginstringThe GitHub user login.
state (optional)stringThe pull request state (open, closed or all).

Passing the empty string "" to user_login returns the number of pull requests with a given state in the repository.

Passing the empty string "" or nothing to state defaults to all.

Return value:

TypeDescription
intThe total number of pull requests created by the given GitHub user login with provided the state.

Examples:

$countUserPullRequests($getAuthor(), "all")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-workload
run:
if: $countUserPullRequests($getAuthor(), "open") > 2
then: $addComment("You have too many open pull requests.")

deleteHeadBranch


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

caution

This built-in does not work on pull request from forks.

caution

Deleting a branch will cause all pull requests that have the deleted branch as head or base to be closed.

INFO

This built-in is only executed if the pull request is either closed or merged.

Description:

Deletes the head branch of the pull request.

Parameters:

none

Examples:

$deleteHeadBranch()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $containsOnlyFileExtensions([".md"])
then:
- $merge()
- $deleteHeadBranch()

dictionaryValueFromKey


Description:

Returns the value of the specified key in the given dictionary.

Parameters:

ParameterTypeDescription
dictionarystringThe dictionary name.
keystringThe key name.

Return value:

TypeDescription
[]stringThe value of the specified key in the given dictionary.

Examples:

$dictionaryValueFromKey("seniors", "devops") # returns ["blair", "casey", "max"]

A reviewpad.yml example:

reviewpad.yml
dictionaries:
- name: seniors
description: Senior developers by team
spec:
devops: '["blair", "casey", "max"]'
qa: '["devon", "taylor"]'

workflows:
- name: name
run:
- if: $isElementOf("infra", $getLabels())
then: $addReviewers($dictionaryValueFromKey("seniors", "devops"))
- if: $isElementOf("debug", $getLabels())
then: $addReviewers($dictionaryValueFromKey("seniors", "qa"))

disableActions


Description:

Disables the list of actions passed as an argument.

Parameters:

ParameterTypeDescription
actions[]stringThe list of actions to be disabled.

Examples:

$disableActions(["assignReviewer"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: protect-actions
run:
if: $isDraft()
then:
- $disableActions(["assignReviewer", "assignTeamReviewer", "assignRandomReviewer"])
- $disableActions(["merge"])

extractMarkdownHeadingContent


Description:

Extracts content from a Markdown heading with the title and the heading level.

Parameters:

ParameterTypeDescription
inputstringInput Markdown string
titlestringTitle of the heading
levelintHeading level

Return value:

TypeDescription
string"" if heading with level does not exist in input, the contents otherwise.

Examples:

$extractMarkdownHeadingContent($getDescription(), "How", 2) # It will extract the body of ## How in the description

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: add-label-based-on-description-heading
run: $addLabel($extractMarkdownHeadingContent($getDescription(), "Merge strategy", 2))

fail


caution

This built-in forces Reviewpad to fail.

You will see a ❌ in the reviewpad status check.

Description:

Fails Reviewpad execution with a custom message.

The custom message is added to both the Reviewpad status check and the Reviewpad report.

Parameters:

ParameterTypeDescription
fail_messagestringThe fail message.

Examples:

$fail("Missing specs")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $changed("src/@1.java", "test/@1.java") == false
then: $fail("Please include tests for your change")

failCheckStatus


Description:

Fails the Reviewpad check run status with a custom message without failing Reviewpad.

This built-in is especially useful to disable the merge action when some conditions are not met. Disabling the Merge action on GitHub can be done with help of a branch protection rule. This branch protection rule must require the Reviewpad check run status to succeed before merging.

The custom message is added to the Reviewpad status check summary.

Parameters:

ParameterTypeDescription
fail_messagestringThe fail message.

Examples:

$failCheckStatus("One approval from the security team is missing.")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $changed("src/@1.java", "test/@1.java") == false
then: $failCheckStatus("Please include tests for your change")

filter


Description:

Filters the elements in the slice based on whether they satisfy a given predicate.

Parameters:

ParameterTypeDescription
slice[]stringThe slice of strings.
predicate(string => boolean)The predicate over string.

Return value:

TypeDescription
[]stringThe elements of the slice that satisfy the given predicate.

Examples:

'$filter(["aa", "ab", "bb", "cc"], ($e: String => $startsWith($e, "a")))' # ["aa", "ab"]

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: merge
run:
# Filter the list of reviewers to only those who are in the maintainers team
# and check that there is at least one reviewer in the list.
# The expression is wrapped in quotes to avoid YAML parsing errors.
if: '$length($filter($getReviewers(), ($r: String => $isElementOf($r, $getTeamMembers("maintainers"))))) == 0'
then: $reportInfo("No maintainer has reviewed the pull request yet")

getAssignees


Description:

Retrieves the list of GitHub user logins that are assigned to the pull request / issue.

Parameters:

none

Return value:

TypeDescription
[]stringThe list of GitHub user logins that are assigned to the pull request / issue.

Examples:

$getAssignees()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: by-default-assign-to-author
run:
if: $getAssignees() == []
then: $addAssignees([$getAuthor()])

getAuthor


Description:

Retrieves the pull request / issue author GitHub login.

Parameters:

none

Return value:

TypeDescription
stringThe GitHub login of the pull request / issue author.

Examples:

$getAuthor()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: share-knowledge
run:
if: $getAuthor() == "john"
then: $addTeamsForReview(["juniors"])

getBaseBranch


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the name of the branch the pull request should be pulled into.

Parameters:

none

Return value:

TypeDescription
stringThe name of the branch the pull request should be pulled into.

Examples:

$getBaseBranch()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: staging-changes
run:
if: $getBaseBranch() == "stage"
then: $reportInfo("Please make sure you've tested your changes in staging environment.")

getCheckRunConclusion


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

caution

Reviewpad looks for the check run conclusion based on the name of the check run.

This means that if you have multiple check runs with the same name, Reviewpad will only check for the first check run with that name.

It is recommended to use unique names for your check runs.

Description:

Retrieves the conclusion of the given check run.

Parameters:

ParameterTypeDescription
check_run_namestringThe name of the check run.

Return value:

TypeDescription
stringThe conclusion of the check run, can be action_required, cancelled, failure, neutral, success, skipped, stale, or timed_out.

Examples:

$getCheckRunConclusion("build")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: auto-merge-docs-changes
run:
if: $containsOnlyFileExtensions([".md"]) && $getCheckRunConclusion("build") == "success"
then: $merge()

getComments


Description:

Retrieves the list of comment body of the pull request / issue.

Parameters:

none

Return value:

TypeDescription
[]stringThe list of comment body of the pull request / issue.

Examples:

$getComments()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: waiting-for-feedback
run:
if: $getComments() == []
then: $addLabel("waiting-for-feedback")

getCommits


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the list of commit messages of the pull request.

Parameters:

none

Return value:

TypeDescription
[]stringThe list of commit messages of the pull request.

Examples:

$getCommits()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-change-type
run:
# Verify if any commit message starts with the word "fix:"
# The expression is wrapped in quotes to avoid YAML parsing errors
if: '$any($getCommits(), ($c: String => $startsWith($c, "fix:")))'
then: $addLabel("bug")

getCreatedAt


Description:

Retrieves the time the pull request / issue was created at.

Parameters:

none

Return value:

TypeDescription
int64The number of seconds elapsed since January 1, 1970 UTC.

Examples:

$getCreatedAt()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: long-live
run:
# Verify if the pull request was created more than 10 days ago
if: $getCreatedAt() < 10 days ago
then: $reportInfo("This pull request is old. Please consider closing it.")

getDescription


Description:

Retrieves the description of the pull request / issue.

Parameters:

none

Return value:

TypeDescription
stringThe description of the pull request / issue.

Examples:

$getDescription()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-conventions
run:
if: $getDescription() == ""
then: $fail("Pull request description is empty")

getEventType


Description:

Retrieves the event type of:

  • Pull request - when Reviewpad is triggered by a pull request event.
  • Issue - when Reviewpad is triggered by an issue event.

Parameters:

none

Return value:

TypeDescription
stringThe pull_request/issue event activity type.

Examples:

$getEventType()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-reviewer-when-pr-ready-for-review
run:
if: $getEventType() == "ready_for_review"
then: $addReviewerRandomly()
- name: add-to-project-when-issue-opened
on:
- issue
run:
if: $getEventType() == "opened"
then: $addToProject("project-title", "column")

getFilePaths


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the list of all file paths changed in the pull request.

Parameters:

none

Return value:

TypeDescription
[]stringA list of all file paths changed files in the patch.

Examples:

$getFilePaths()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: binary-files-not-allowed
run:
if: "$any($getFilePaths(), ($filePath: String => $isBinaryFile($filePath)))"
then: $fail("Binary files are not allowed.")

getHeadBranch


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the name of the branch where the pull request changes are implemented.

Parameters:

none

Return value:

TypeDescription
stringThe name of the branch where the pull request changes are implemented.

Examples:

$getHeadBranch()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-change-type
run:
- if: $startsWith($getHeadBranch(), "feat/")
then: $addLabel("feature")
- if: $startsWith($getHeadBranch(), "fix/")
then: $addLabel("fix")

getLabels


Description:

Retrieves the list of labels of the pull request / issue.

Parameters:

none

Return value:

TypeDescription
[]stringThe list of labels of the pull request / issue.

Examples:

$getLabels()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-reviewers
run:
if: $isElementOf("bug", $getLabels())
then: $addTeamsForReview(["testers"])

getLastEventTime


Description:

Retrieves the timestamp of the last event in the timeline.

Parameters:

none

Return value:

TypeDescription
int64The number of seconds elapsed since January 1, 1970 UTC.

Examples:

$getLastEventTime()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: stale
run:
if: $getLastEventTime() < 30 days ago
then:
- $addLabel("stale")
- $addComment("This pull request has been automatically marked as stale")

getMilestone


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the milestone title associated with the pull request.

Parameters:

none

Return value:

TypeDescription
stringThe milestone title associated with the pull request.

Examples:

$getMilestone()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-milestone
run:
- if: $getMilestone() == "Hacktoberfest"
then: $addLabel("hacktoberfest")
- if: $startsWith($getMilestone(), "v")
then: $addLabel("release")

getOrganizationMembers


Description:

Retrieves all the members of the organization to which the pull request or issue is linked

Parameters:

none

Return value:

TypeDescription
[]stringThe list of all the members within the organization.

Examples:

$getOrganizationMembers()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: external-contributions
run:
if: $isElementOf($getAuthor(), $getOrganizationMembers()) == false
then:
- $addTeamsForReview(["core"])
- $addLabel("external-contributor")
- $addComment("Thank you for your contribution!")

getOrganizationTeams


Description:

Retrieves all the teams of the organization to which the pull request or issue is linked

Parameters:

none

Return value:

TypeDescription
[]stringThe list of all teams within the organization.

Examples:

$getOrganizationTeams()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign for review to a team member based on label
on:
- pull_request
run:
- forEach:
value: $orgaTeam
in: $getOrganizationTeams()
do:
- if: $hasLabel($orgaTeam)
then: $addReviewers($getTeamMembers($orgaTeam), 1)

getReviewers


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Fetches the list of reviewers assigned to this pull request. By default, it return all the reviewers regardless of the review statuses. To refine the list based on review status, utilize the optional review-status parameter.

Parameters:

ParameterTypeDescription
review-status (optional)Allows filtering of reviewers based on their review status: “COMMENTED”, “CHANGES_REQUESTED”, “APPROVED”, or “PENDING”.

Return value:

TypeDescription
[]stringThe list of GitHub user IDs.

Examples:

$getReviewers()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: attention set when no review from the security team
run:
if: '$any($getReviewers(), ($r: String => $isElementOf($r, $getTeamMembers("security")))) == false'
then: $reportInfo("Are you sure this PR doesn't deserve any review from the security team?")

getReviewerStatus


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the status of a reviewer in the pull request.

Parameters:

ParameterTypeDescription
reviewer_loginstringThe GitHub login of the reviewer.

Return value:

TypeDescription
stringThe status of a reviewer. It can be one of the four following string values:
- "", if there was no review from the reviewer.
- "COMMENTED", if all the reviews from the reviewer were comments.
- "CHANGES_REQUESTED", if the last review, that was not a comment, requested changes.
- "APPROVED", if the last review that was not a comment requested changes.

Examples:

$getReviewerStatus("marcelosousa")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: merge
run:
if: '$any($getReviewers(), ($r: String => $getReviewerStatus($r) == "APPROVED"))'
then: $merge()

getSize


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Retrieves the total amount of changed lines in the patch excluding files that match the given patterns.

By default, if no parameter is provided, it will perform a count on all changed files.

Any added or removed line is considered a change. For instance, the following patch will have a size of 2 (one line removed and one line added).

function helloWorld() {
- return "Hello"
+ return "Hello World"
}

Parameters:

ParameterTypeDescription
excluded_patterns (optional)[]stringThe file patterns to exclude from count.

Return value:

TypeDescription
intThe sum of all changed lines in the patch.

Examples:

$getSize(["*.lock"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
# Verify size ignoring lock files
if: $getSize(["*.lock"]) > 100
then: $reportBlocker("Change is too big")

getState


Description:

Retrieves the state of a pull request / issue. This state can be either open or closed.

Parameters:

none

Return value:

TypeDescription
stringThe state of the pull request / issue. The state can be open or closed.

Examples:

$getState()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: thank-contributors
run:
if: $getState() == "closed"
then: $reportInfo("Thanks for your contribution!")

getTeamMembers


Description:

Retrieves the members of a team and child teams.

To list members in a team, the team must be visible to the authenticated user.

Parameters:

ParameterTypeDescription
team_slugstringThe slug of the team name on GitHub.

Return value:

TypeDescription
[]stringThe list of all team and child teams members GitHub login.

Examples:

$getTeamMembers("devops")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-devops-reviewer
run:
if: $isElementOf($getAuthor(), $getTeamMembers("devops"))
then: $addTeamsForReview(["devops"])

getTitle


Description:

Retrieves the title of the pull request / issue.

Parameters:

none

Return value:

TypeDescription
stringThe title of the pull request / issue.

Examples:

$getTitle()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $getTitle() == ""
then: $fail("A pull request must have a title")

getUserTeams


Description:

Fetches the list of teams to which a user belongs to

Parameters:

ParameterTypeDescription
userstringThe user for whom the team are to be retrieved

Return value:

TypeDescription
[]stringThe list of all teams to which the user belongs to.

Examples:

$getUserTeams("Paul")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: review assignment policy in case the author belongs to team 'onboarding'
on:
- pull_request
run:
- if: $isElementOf("onboarding", $getUserTeams($getAuthor()))
then: $addReviewers(["paul", "freddy"], 1)

group


Description:

Lists all the members that belong to the provided group. This group needs to be defined in the same reviewpad.yml file.

group is a way to refer to a defined set of users in a short way.

Parameters:

ParameterTypeDescription
group_namestringThe group name to list all the members from.

Return value:

TypeDescription
[]stringAll the members from the group.

Examples:

$group("techLeads")

A reviewpad.yml example:

reviewpad.yml
groups:
- name: tech-leads
# The expression is wrapped in quotes to avoid YAML parsing errors
spec: '["john", "maria", "arthur"]'
- name: juniors
type: filter
param: developer
where: $countUserPullRequests($developer, "all") < 10
- name: ignore_paths
# The expression is wrapped in quotes to avoid YAML parsing errors
spec: '["engine/**", "*.yaml"]'

workflows:
- name: label-with-size
run:
if: $getSize($group("ignore_paths")) < 10
then: $addLabel("small")
- name: review-juniors-changes
run:
if: $isElementOf($getAuthor(), $group("juniors"))
then: $addReviewers($group("tech-leads"), 1)

hasAnyCheckRunCompleted


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Known issue

Please note that Reviewpad will run for every check run that is completed.

This can be an issue if you use built-ins that are not idempotent (e.g. the comment built-in). In this case, Reviewpad will run the built-in multiple times.

Here's an example of a reviewpad.yml configuration:

workflows:
- name: has-any-check-run-completed
run:
if: $hasAnyCheckRunCompleted()
then: $addComment("Hello")

In this example, if you have 5 checks Reviewpad comment "Hello" 5 times.

info

By default, the reviewpad check run is ignored.

Description:

Checks, whether any check runs for a pull request, have been completed with the provided conclusions.

If the check_runs_to_ignore parameter is provided, any check runs that have a name included in the parameter will be ignored.

If the check_conclusions parameter is provided, only check runs that have been completed with one of the provided conclusions will be considered.

The check_conclusions parameter accepts the following values: action_required, cancelled, failure, neutral, success, skipped, stale, and timed_out.

Parameters:

ParameterTypeDescription
check_runs_to_ignore (optional)[]stringList of check run names to be disregarded. By default, is []
check_conclusions (optional)[]stringList of the final conclusions of the check. By default, is []

Return value:

TypeDescription
booleantrue if there is at least one check completed with one of the provided conclusions, false otherwise.

Examples:

Any check run has been completed with any conclusion.

$hasAnyCheckRunCompleted()

Any check run has failed.

$hasAnyCheckRunCompleted([], ["failure"])

Any check run has been skipped or failed.

$hasAnyCheckRunCompleted([], ["skipped", "failure"])

Any check run has been completed with skipped except for the integration-tests check run.

$hasAnyCheckRunCompleted(["integration-tests"], ["skipped"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-run-failure
run:
if: $hasAnyCheckRunCompleted([], ["failure"])
then: $review("REQUEST_CHANGES", "Some of the pull request checks are failing. Please fix them.")

hasAnyPendingReviews


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies whether a pull request is waiting for review, returning true or false as appropriate.

A pull request is set as waiting for review when there are requested reviewers or when there's at least one reviewer whose last review is outdated.

An outdated review is a review submitted before the last pull request update and whose state is not approved.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request is waiting for review, false otherwise.

Examples:

$hasAnyPendingReviews()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: attention-set
run:
- if: $hasAnyPendingReviews()
then: $addLabel("waiting-for-review")
- if: $hasAnyUnaddressedThreads()
then: $addLabel("requires-author-attention")

hasAnyReviewers


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies whether a pull request has at least one reviewer assigned to it. It returns true regardless of the review statuses.

Parameters:

none

Return value:

TypeDescription
booleantrue if at least one reviewer.

Examples:

$hasAnyReviewers()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: missing-reviewer label when no reviewer but the PR is ready for review
run:
- if: "!$hasAnyReviewers() && !$isDraft() && $getLastEventTime() < 2 days ago"
then: $addLabel("missing-reviewer")

hasAnyUnaddressedThreads


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies whether the pull request has review threads that are unaddressed, returning true or false as appropriate.

A review thread is unaddressed when it is not resolved or outdated.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request has any review thread that is not resolved or outdated, false otherwise.

Examples:

$hasAnyUnaddressedThreads()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: attention-set
run:
if: $hasAnyUnaddressedThreads()
then: $addLabel("requires-author-attention")

hasGitConflicts


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Determines if the pull request has Git conflicts, returning true or false as appropriate.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request has Git conflicts, false otherwise.

Examples:

$hasGitConflicts()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $hasGitConflicts()
then: $fail("Pull request has git conflicts")

hasLabel


Description:

Checks whether a pull request or an issue is tagged with a specific label.

Parameters:

ParameterTypeDescription
labelstringThe target label to check for

Return value:

TypeDescription
booleantrue if the pull request or issue has the target label, false otherwise.

Examples:

$hasLabel("foo")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign for review to Paul in case of a bug
on:
- pull_request
run:
if: $hasLabel("bug")
then: $addReviewers(["paul"])

hasLinearHistory


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Checks if a pull request has a linear history.

A linear history is simply a Git history in which all commits come after one another, i.e., you will not find any merges of branches with independent commit histories.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request has a linear history, false otherwise.

Examples:

$hasLinearHistory()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $hasLinearHistory() == false
then: $fail("The pull request does not have a linear history.")

hasLinkedIssues


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Checks if a pull request has associated issues that might be closed by it.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request has linked issues, false otherwise.

Examples:

$hasLinkedIssues()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: assign-reviewers
run:
if: $hasLinkedIssues() && $hasLinearHistory()
then: $addReviewerRandomly()

hasOnlyApprovedReviews


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies if all the reviewers assigned to a pull request have approved it.

Parameters:

none

Return value:

TypeDescription
booleantrue if there is no “COMMENTED”, “CHANGES_REQUESTED" or “PENDING” review.

Examples:

$hasOnlyApprovedReviews()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: disable the merge when missing approval
run:
- if: "!$hasOnlyApprovedReviews()"
then: $failCheckStatus("Waiting for all reviewers to approve the change")

hasOnlyCompletedCheckRuns


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Known issue

Please note that Reviewpad will run for every check run that is completed.

This can be an issue if the checks finish around the same time and you use built-ins that are not idempotent (e.g. the comment built-in). In this case, Reviewpad will run the built-in multiple times.

Here's an example of a reviewpad.yml configuration:

workflows:
- name: all-checks-completed
run:
if: $hasOnlyCompletedCheckRuns([], "success")
then: $addComment("Hello")

In this example, if you have 5 checks Reviewpad comment "Hello" 5 times.

If checks finish all with success around the same time then, when Reviewpad runs for each check, the condition of all checks being completed with success will be true and Reviewpad will run $addComment("Hello") for each check. This will result in 5 comments.

info

By default, the reviewpad check run is ignored.

Description:

Checks if all check runs for a pull request have been completed.

If the check_runs_to_ignore parameter is provided the checks with a name included in the parameter will be ignored.

If the conclusion parameter is provided, all check runs must be complete with the provided conclusion.

The conclusion parameter can be one of action_required, cancelled, failure, neutral, success, skipped, stale or timed_out.

If the check_conclusions_to_ignore parameter is set, any checks with a conclusion that appears in the check_conclusions_to_ignore list will be ignored.

Parameters:

ParameterTypeDescription
check_runs_to_ignore (optional)[]stringList of check run names to be disregarded.
conclusion (optional)stringThe final conclusion of the check. Empty by default. All conclusion values are valid.
check_conclusions_to_ignore (optional)[]stringList of check conclusions to be disregarded. Any checks with a conclusion in that list will be ignored.

Return value:

TypeDescription
booleantrue if all check runs have been completed, false otherwise.

Examples:

All check runs have been completed (regardless of the conclusion).

$hasOnlyCompletedCheckRuns()

All check runs have been completed except for the integration-tests check.

$hasOnlyCompletedCheckRuns(["integration-tests"])

All check runs have been completed with a success conclusion.

$hasOnlyCompletedCheckRuns([], "success")

All check runs have been completed with success ignoring the checks with skipped conclusion.

$hasOnlyCompletedCheckRuns([], "success", ["skipped"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: auto-merge
run:
if: $hasOnlyCompletedCheckRuns([], "success", ["skipped"])
then: $merge()

hasRequiredApprovals


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Checks if a pull request has the required number of approvals from a defined set of users.

Parameters:

ParameterTypeDescription
total_required_approvalsintThe number of required approving reviews.
required_approvals_from[]stringThe list of users where the required approving reviews must come from.

Return value:

TypeDescription
booleantrue if the number of required approvals comes from the list of users, false otherwise.

Examples:

$hasRequiredApprovals(2, ["john", "jane", "peter"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: merge
run:
if: $hasRequiredApprovals(2, $getTeamMembers("core"))
then: $merge()

isBinaryFile


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies whether the file in the provided path is a binary file.

Parameters:

ParameterTypeDescription
filepathstringThe filepath to the file to verify if it is binary.

Return value:

TypeDescription
booleantrue if the file is a binary, false otherwise.

Examples:

$isBinaryFile("folder/filename")
$isBinaryFile("filename")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: blacklist-binary-files
run:
if: '$any(["file", "folder/file"], ($file: String => $isBinaryFile($file)))'
then: $fail("Blacklisted binary files aren't allowed in pull request")

isDraft


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies whether the pull request is a draft, returning true or false as appropriate.

To know more about GitHub Draft pull request.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request is a draft, false otherwise.

Examples:

$isDraft()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: distribute-review
run:
if: "!$isDraft() && $hasLinkedIssues() && $hasLinearHistory()"
then: $addReviewerRandomly()

isElementOf


Description:

Determines whether a list includes a certain value among its entries, returning true or false as appropriate.

Parameters:

ParameterTypeDescription
search_elementstringThe value to search for.
list[]stringThe list to search in.

Return value:

TypeDescription
booleantrue if search_element is found within the list, false otherwise.

Examples:

$isElementOf("john", ["maria", "john"])  # true
$isElementOf(3, [1, 2]) # false

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: requires-review
run:
if: $isElementOf($getAuthor(), $getTeamMembers("juniors"))
then: $addTeamsForReview(["seniors"])

isMerged


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Verifies whether a pull request is merged, returning true or false as appropriate.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request is merged, false otherwise.

Examples:

$isMerged()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: notify-unaddressed-threads-merge
run:
if: $hasAnyUnaddressedThreads() && $isMerged()
then: $addComment("Pull request merged with unaddressed threads!")

isLinkedToProject


Description:

Checks if the pull request / issue is linked to a GitHub project with a given title.

If the project doesn't exist, an error is returned.

Parameters:

ParameterTypeDescription
project_titlestringThe title of the project - case sensitive.

Return value:

TypeDescription
booleantrue if the pull request / issue is linked to the project, false otherwise.

Examples:

$isLinkedToProject("project title")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: add-to-project
run:
if: '!$isLinkedToProject("project-title")'
then: $addToProject("project-title", "column")

isUpdatedWithBaseBranch


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Checks if the pull request is updated with the base branch, i.e., if the first commit of the head branch is the last commit from the base branch.

Parameters:

none

Return value:

TypeDescription
booleantrue if the pull request is updated with the base branch, false otherwise.

Examples:

$isUpdatedWithBaseBranch()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: rebase
run:
if: '!$isUpdatedWithBaseBranch()'
then: $rebase()

join


Description:

Concatenates an array of strings, using the specified separator between each member.

Parameters:

ParameterTypeDescription
elements[]stringThe array to join.
separatorstringThe separator to put between the elements.

Return value:

TypeDescription
stringThe concatenated string of elements with the separator between them.

Examples:

$join(["alice", "bob"], " ")    # "alice bob"
$join(["alice", "bob"], ", ") # "alice, bob"

A reviewpad.yml example:

workflows:
- name: changes-on-security
description: Warn when changes include security annotation
run:
if: $containsCodeAnnotation("security")
then: '$reportWarning($sprintf("This pull request contains security changes. Please, request a 1:1 with security team: %s", [$join($getTeamMembers("security", ", "))]))'

length


Description:

Retrieves the length of an array.

Parameters:

ParameterTypeDescription
array[]stringThe array of elements.

Return value:

TypeDescription
intThe length of the array.

Examples:

$length(["a", "b"]) # 2

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $length($getReviewers()) < 2
then: $reportInfo("A pull request needs at least 2 reviews")

matchString


Description:

Verifies if a provided regular expression pattern is matched by a given text.

See supported regular expression syntax

Parameters:

ParameterTypeDescription
patternstringThe regular expression pattern
textstringThe text to match

Return value:

TypeDescription
booleantrue if text matches the pattern, false otherwise.

Examples:

$matchString("a(bc)+$", "abcbc") # true
$matchString("\d+", "text") # false

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: branch-convention
run:
if: '!$matchString("(feature|fix|docs)/.+", $getHeadBranch())'
then: $reportBlocker("The branch name must start with 'feature/', 'fix/' or 'docs/'")

merge


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Merges a pull request with a specific merge method.

By default, this action is only enabled for open pull requests that are not draft.

Also, by default, if no parameter is provided, it will perform a standard git merge.

Parameters:

ParameterTypeDescription
method (optional)stringThe merge method (merge, rebase or squash). By default, it will perform a standard git merge.

Examples:

$merge()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: merge
if: $containsOnlyFileExtensions([".md"])
then: $merge()

rebase


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

caution

This built-in is only supported on non-forked and user-owned forks repositories. This is due to GitHub restrictions on committing to a pull request branch from a fork. For more information, see this Github documentation.

Description:

Rebases the pull request.

Parameters:

none

Examples:

$rebase()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: rebase-pull-request
run:
if: $toBool($selectFromContext("$.rebaseable"))
then: $rebase()

removeLabel


Description:

Removes a label applied to a pull request / issue.

It will check if there is a label with this key in the labels section of reviewpad.yml.

If such label exists, it will use name property of the label; if the property is not present, then it uses the key as the name.

If the label does not exist in the repository, no action will be taken.

Parameters:

ParameterTypeDescription
namestringThe name of the label to remove.

Examples:

$removeLabel("bug")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: conflicts
run:
if: $hasGitConflicts() == false
then: $removeLabel("git-conflicts")

removeLabels


Description:

Removes the provided labels from the pull request / issue.

For each given label, it will check if there is a label with this key in the labels section of reviewpad.yml.

If such label exists, it will use the name property of the label; Otherwsise, it uses the key as the label name.

If the label does not exist in the repository, no action will be taken.

Parameters:

ParameterTypeDescription
labels[]stringThe list of the labels to be removed.

Examples:

$removeLabels(["bug", "p1"])

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-size
run:
if: $getSize() < 10
then:
- $addLabel("small")
- $removeLabels(["medium", "large"])

removeFromProject


Description:

Removes a pull request / issue from a project with a particular title.

If the project doesn't exist, an error is returned.

Parameters:

ParameterTypeDescription
project_titlestringThe title of the project - case sensitive.

Examples:

$removeFromProject("reviewpad")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: remove-from-project
run:
if: '!$isMerged() && $getState() == "closed"'
then: $removeFromProject("reviewpad")

reportBlocker


Description:

Add a message to the errors section of the report.

Parameters:

ParameterTypeDescription
commentstringThe comment to be added in the errors.

Examples:

$reportBlocker("Please do not touch these files.")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: check-compliance
run:
if: $getSize() > 100
then: $reportBlocker("This pull request is too large")

reportInfo


Description:

Adds a message to the info section of the report.

Parameters:

ParameterTypeDescription
commentstringThe comment to be added in the informations.

Examples:

$reportInfo("Please do not forget to add the tests.")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: when-transactions
run:
if: $containsFilePattern("**/transactions")
then:
- $reportInfo("You have changed transactions. Please schedule a meeting.")
- $addLabel("critical")

reportWarning


Description:

Adds a message to the warnings section of the report.

Parameters:

ParameterTypeDescription
commentstringThe comment to be added in the warnings.

Examples:

$reportWarning("Please do not forget to add the tests.")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: validate-changes
run:
if: $containsFilePattern("*.lock")
then: $reportWarning("Please remove the lock file from the commit.")

review


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

Description:

Submits a pull request review.

The action fails when the review type is REQUEST_CHANGES or COMMENT and no message is provided.

The review will only be performed if the following conditions are met:

  • the pull request is open;
  • the pull request is not in draft;
  • the pull request has changes since the last submitted review.

Parameters:

ParameterTypeDescription
review_typestringThe kind of review, can be APPROVE, REQUEST_CHANGES, COMMENT.
messagestringThe message to write as a comment.

Examples:

$review("APPROVE", "")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: validate-changes
run:
if: $changed("src/@1.java", "test/@1.java") == false
then: $review("REQUEST_CHANGES", "Please include the tests for your change")

rule


Description:

Evaluates a rule. This rule needs to be defined in the same reviewpad.yml file.

Parameters:

ParameterTypeDescription
rule_namestringThe rule name.

Return value:

TypeDescription
booleanThe evaluation of the rule.

Examples:

'$rule("is-small")'

A reviewpad.yml example:

reviewpad.yml
rules:
- name: size-compliance
spec: $getSize() < 100
- name: description-compliance
spec: $getDescription() != ""
- name: is-compliant
spec: $rule("size-compliance") && $rule("description-compliance")

workflows:
- name: check-compliance
run:
if: is-compliant
then: $addReviewerRandomly()

selectFromContext


Description:

Allows the selection of arbitrary value(s) from the current context using a JSONPath expression.

If no value is found for the given expression, an empty string is returned.

The context is the pull request or issue where the built-in is running on.

Parameters:

ParameterTypeDescription
expressionstringThe JSONPath expression to evaluate

Return value:

TypeDescription
stringThe JSON serialized string of the value found at the given expression, or empty string if no value is found

Examples:

$selectFromContext("$.title") # select the title property
$selectFromContext("$.labels[*].name") # select all label names

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-rebaseable
run:
if: $selectFromContext("$.rebaseable") == "true"
then: $addLabel("rebaseable")

selectFromJSON


Description:

Allows the selection of arbitrary value(s) from a JSON type using a JSONPath expression.

info

If no value is found for the given expression, an empty string is returned.

Parameters:

ParameterTypeDescription
jsonJSONThe JSON value to select from
expressionstringThe JSONPath expression to evaluate

Return value:

TypeDescription
stringThe JSON serialized string of the value found at the given expression, or empty string if no value is found

Examples:

$selectFromJSON($toJSON("[1, 2, 3]"), "$[0]") # select element at index 0

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-rebaseable
run:
if: $selectFromJSON($toJSON($context), "$.rebaseable") == "true"
then: $addLabel("rebaseable")

setProjectField


Description:

Sets the value of a GitHub project's custom field for the pull request / issue in the current context.

Currently, we only support setting the value of a custom field in a project.

We don't support creating a custom field or a project.

The current field value is overwritten.

We support the following types of custom fields: text fields, number fields, and single select fields.

An error is returned if:

  • The project doesn't exist.
  • The field doesn't exist.
  • The field is not one of the types above.
  • The value is not a number for a number field.

Parameters:

ParameterTypeDescription
project_titlestringThe title of the project - case sensitive.
fieldstringThe custom field which can be text, number, or single select (must exist).
valuestringThe value of the field.

Examples:

$setProjectField("reviewpad", "priority", "P1")
$setProjectField("reviewpad", "size", "50")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: set-project-field
run:
if: $hasLinkedIssues() == false
then:
- $addToProject("jupiter", "in progress")
- $setProjectField("jupiter", "notes", "missing issue")

sprintf


Description:

Returns a formatted string.

Parameters:

ParameterTypeDescription
format_stringstringThe string to be formatted.
arguments_list[]stringThe list of arguments to replace the format specifiers.

Return value:

TypeDescription
stringThe formatted string.

Examples:

$sprintf("Hello, %s!", ["world"])  # "Hello, world!"

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: congratulate
run:
if: $countUserPullRequests($getAuthor(), "all") == 1
then: $addComment($sprintf("Thank you @%s for this first contribution!", [$getAuthor()]))

startsWith


Description:

Evaluates if a given text begins with a specific sentence, returning true or false accordingly Note that this evaluation is case-sensitive.

Parameters:

ParameterTypeDescription
textstringThe text to search in.
prefixstringThe prefix.

Return value:

TypeDescription
booleantrue if prefix is a prefix of text, false otherwise.

Examples:

$startsWith("Testing string contains", "Test")                 #true
$startsWith("Testing string contains", "string contains") #false

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-change-type
run:
- if: $startsWith($getHeadBranch(), "feature/")
then: $addLabel("feature")
- if: $startsWith($getHeadBranch(), "fix/")
then: $addLabel("fix")

subMatchesString


Description:

Extracts the first match on a string based on a given regular expression pattern.

Parameters:

ParameterTypeDescription
patternstringThe regular expression pattern to match against the input value
inputstringThe string value to test against the given pattern

Return value:

TypeDescription
string"" if the input string does not have the pattern

Examples:

Matching a string against a simple pattern.

$subMatchesString("name:\\s*(\\w+)", "name: Peter")

Using this function in a reviewpad.yml example:

reviewpad.yml
workflows:
- name: add-label-based-on-branch-convention
run:
if: $matchString("(feat|chore)/\\w+", $getHeadBranch())
then: $addLabel($subMatchesString((feat|chore)/\\w+), $getHeadBranch()))

{/ Workaround to keep the anchor "summarize-" /}

summarize

summarize 🧪


🧪 EXPERIMENTAL

This is a command that is currently in beta phase.

We send information to OpenAI about the pull request, including parts of the git patch and git diff. We do not send any information that is not retrieved from the pull request. For more questions, contact us on discord.

Description:

Automatically summarizes the pull request changes with GPT-4.

Parameters:

none

Examples:

$summarize()

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: summarize-on-pull-request-creation
run:
if: $getEventType() == "opened"
then: $summarize()

triggerWorkflow


caution

This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.

caution

For this built-in to work, the workflow file that you wish to trigger must have the workflow_dispatch trigger.

Description:

Creates a workflow dispatch event to manually trigger a GitHub Action workflow run.

Parameters:

ParameterTypeDescription
file_namestringThe workflow file name.

Examples:

$triggerWorkflow("main.yml")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: run-critical-ci
run:
if: $containsCodeAnnotation("critical")
then: $triggerWorkflow("ci-critical-tests.yml")

toBool


Description:

Converts a string into a boolean. This built-in is a wrapper around strconv.ParseBool. It accepts 1, t, T, TRUE, true, True, 0, f, F, FALSE, false, False. Any other value returns an error.

Parameters:

ParameterTypeDescription
stringstringThe string value to be converted to a boolean.

Return value:

TypeDescription
boolThe converted boolean

Examples:

$toBool("true")
$toBool("false")
$toBool($selectFromContext("$.locked"))

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-locked
run:
if: $toBool($selectFromContext("$.locked"))
then: $addLabel("locked")

toJSON


Description:

Converts a JSON serialized string to a JSON object.

Parameters:

ParameterTypeDescription
json_stringstringJSON serialized string

Return value:

TypeDescription
JSONThe JSON object corresponding to the serialized string.

Examples:

$toJSON($context())
$toJSON("[1, 2, 3]")

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: label-mergeable
run:
if: $selectFromJSON($toJSON($context()), "$.mergeable") == "true"
then: $addLabel("mergeable")

toNumber


Description:

Converts a string into a number.

Parameters:

ParameterTypeDescription
stringstringThe string value to convert to a number.

Return value:

TypeDescription
intThe converted number

Examples:

$toNumber("1")
$toNumber("-1")
$toNumber($selectFromContext("$.comments"))

A reviewpad.yml example:

reviewpad.yml
workflows:
- name: warn-large-pull-requests
run:
if: $toNumber($selectFromContext("$.additions")) > 100
then: $reportWarning("please break down large pull requests into smaller and easy to review parts.")

toStringArray


Description:

Converts a given JSON string into an array of strings. It returns an error if the value can not be converted.

Parameters:

ParameterTypeDescription
json_stringstringJSON serialized array of string

Return value:

TypeDescription
[]stringThe array of string values.

Examples:

$toStringArray($selectFromContext("$.labels[*].name"))

A reviewpad.yml example:

reviewpad.yml
groups:
- name: deprecated-labels
description: List of labels that should not be used
spec: '["foo", "bar"]'

workflows:
- name: warn-outdated-labels
run:
if: '$any($toStringArray($selectFromContext("$.labels[*].name")), ($label: String => $isElementOf($label, $group("deprecated-labels"))))'
then: $reportWarning($sprintf("Please do not use the deprecated labels %s", [$join($group("deprecated-labels"), ", ")]))