Built-ins
One of the key advantages of using Reviewpad is that you can access a set of built-in functions and actions that allow flexible specifications and actions.
Functions
Reviewpad functions allow querying data from a pull request
, issue
, or organization
to act on it.
The functions are organized into 4 categories:
- Pull Request / Issue - Functions to query pull request / issue data.
- Organization - Functions to query organization data.
- User - Functions to query user's data.
- Utilities - Functions to help act on the queried data.
- Engine - Functions used to work with
reviewpad.yml
file.
Pull Request / Issue
Set of functions to get pull request / issue details.
approvalsCount
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:
Type | Description |
---|---|
int | The total number of approvals the pull request has received. |
Examples:
$approvalsCount()
A reviewpad.yml
example:
workflows:
- name: auto-merge
if:
- $approvalsCount() > 2
then:
- $merge()
assignees
Description:
Retrieves the list of GitHub user logins that are assigned to the pull request / issue.
Parameters:
none
Return value:
Type | Description |
---|---|
[]string | The list of GitHub user logins that are assigned to the pull request / issue. |
Examples:
$assignees()
A reviewpad.yml
example:
workflows:
- name: by-default-assign-to-author
# Run workflow regardless of previous workflow result
always-run: true
if:
- $assignees() == []
then:
- $assignAssignees([$author()])
author
Description:
Retrieves the pull request / issue author GitHub login.
Parameters:
none
Return value:
Type | Description |
---|---|
string | The GitHub login of the pull request / issue author. |
Examples:
$author()
A reviewpad.yml
example:
rules:
- name: is-author-by-tech-lead
spec: $author() == "john"
workflows:
- name: share-knowledge
if:
- rule: is-author-by-tech-lead
then:
- $assignTeamReviewer(["juniors"])
base
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:
Type | Description |
---|---|
string | The name of the branch the pull request should be pulled into. |
Examples:
$base()
A reviewpad.yml
example:
workflows:
- name: staging-changes
if:
- $base() == "stage"
then:
- $info("Please make sure you've tested your changes in staging environment.")
changed
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:
Parameter | Type | Description |
---|---|---|
pre_file_pattern | string | The antecedent file pattern expression. |
post_file_pattern | string | The consequent file pattern expression. |
Return value:
Type | Description |
---|---|
boolean | true 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:
rules:
- name: missing-tests
spec: $changed("src/@1.java", "test/@1.java") == false
workflows:
- name: validate-changes
if:
- rule: missing-tests
then:
- $fail("Please include tests for your change.")
checkRunConclusion
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
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:
Parameter | Type | Description |
---|---|---|
check_run_name | string | The name of the check run. |
Return value:
Type | Description |
---|---|
string | The conclusion of the check run, can be action_required , cancelled , failure , neutral , success , skipped , stale , or timed_out . |
Examples:
$checkRunConclusion("build")
A reviewpad.yml
example:
workflows:
- name: auto-merge-docs-changes
if:
- $hasFileExtensions([".md"]) && $checkRunConclusion("build") == "success"
then:
- $merge()
commentCount
Description:
Retrieves the total number of comments made into the pull request / issue.
Parameters:
none
Return value:
Type | Description |
---|---|
int | The total number of comments in the pull request / issue. |
Examples:
$commentCount()
A reviewpad.yml
example:
workflows:
- name: high-activity
if:
- $commentCount() > 15
then:
- $info("Please consider splitting the pull request into smaller pull requests.")
comments
Description:
Retrieves the list of comment body of the pull request / issue.
Parameters:
none
Return value:
Type | Description |
---|---|
[]string | The list of comment body of the pull request / issue. |
Examples:
$comments()
A reviewpad.yml
example:
workflows:
- name: waiting-for-feedback
if:
- $comments() == []
then:
- $addLabel("waiting-for-feedback")
commitCount
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:
Type | Description |
---|---|
int | The total number of commits in the pull request. |
Examples:
$commitCount()
A reviewpad.yml
example:
workflows:
- name: high-activity
if:
- $commitCount() > 10
then:
- $info("Please consider splitting the pull request into smaller pull requests.")
commits
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:
Type | Description |
---|---|
[]string | The list of commit messages of the pull request. |
Examples:
$commits()
A reviewpad.yml
example:
rules:
- name: is-bug
# Verify if any commit message starts with the word "fix:"
# The expression is wrapped in quotes to avoid YAML parsing errors
spec: '$any($commits(), ($c: String => $startsWith($c, "fix:") ))'
workflows:
- name: labe-change-type
if:
- rule: is-bug
then:
- $addLabel("bug")
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:
Type | Description |
---|---|
string | JSON serialized string of the current context (pull request /issue ) |
Examples:
$context()
A reviewpad.yml
example:
workflows:
- name: debug
if:
- rule: $isElementOf("debug", $labels())
then:
- $info($context())
createdAt
Description:
Retrieves the time the pull request / issue was created at.
Parameters:
none
Return value:
Type | Description |
---|---|
int64 | The number of seconds elapsed since January 1, 1970 UTC. |
Examples:
$createdAt()
A reviewpad.yml
example:
workflows:
- name: long-live
if:
# Verify if the pull request was created more than 10 days ago
- $createdAt() < 10 days ago
then:
- $info("This pull request is old. Please consider closing it.")
description
Description:
Retrieves the description of the pull request / issue.
Parameters:
none
Return value:
Type | Description |
---|---|
string | The description of the pull request / issue. |
Examples:
$description()
A reviewpad.yml
example:
workflows:
- name: check-conventions
if:
- $description() == ""
then:
- $fail("Pull request description is empty")
eventType
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
Description:
Retrieves the type of the pull request event.
Parameters:
none
Return value:
Type | Description |
---|---|
string | The pull_request event activity type. |
Examples:
$eventType()
A reviewpad.yml
example:
workflows:
- name: assign-reviewer-when-pr-ready-for-review
if:
- $eventType() == "ready_for_review"
then:
- $assignRandomReviewer()
fileCount
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:
Type | Description |
---|---|
int | The total number of files changed in the patch. |
Examples:
$fileCount()
A reviewpad.yml
example:
workflows:
- name: too-big
if:
- $fileCount() > 10
then:
- $info("Please consider splitting the pull request into smaller pull requests.")
filesPath
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:
Type | Description |
---|---|
[]string | A list of all file paths changed files in the patch. |
Examples:
$filesPath()
A reviewpad.yml
example:
workflows:
- name: binary-files-not-allowed
if:
- '$any($filesPath(), ($filePath: String => $isBinary($filePath)))'
then:
- $fail("Binary files are not allowed.")
hasAnnotation
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
Description:
Verifies if the patch contains a symbol with the provided annotation, returning true
or false
as appropriate.
Please note that for this to work a symbol must be annotated with the @reviewpad-an <annotation>
annotation.
For more information annotations, please see this page.
Parameters:
Parameter | Type | Description |
---|---|---|
annotation | string | The annotation to look for in the patch. |
Return value:
Type | Description |
---|---|
boolean | true if the patch changes a symbol with the provided annotation, false otherwise. |
Examples:
$hasAnnotation("critical")
A reviewpad.yml
example:
workflows:
- name: security-changes
if:
- $hasAnnotation("security")
then:
- $assignReviewer($team("security"), 1)
hasAnyCheckRunCompleted
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
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
if:
- $hasAnyCheckRunCompleted()
then:
- $comment("Hello")
In this example, if you have 5 checks Reviewpad comment "Hello" 5 times.
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:
Parameter | Type | Description |
---|---|---|
check_runs_to_ignore (optional) | []string | List of check run names to be disregarded. By default, is [] |
check_conclusions (optional) | []string | List of the final conclusions of the check. By default, is [] |
Return value:
Type | Description |
---|---|
boolean | true 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:
workflows:
- name: check-run-failure
if:
- $hasAnyCheckRunCompleted([], ["failure"])
then:
- $review("REQUEST_CHANGES", "Some of the pull request checks are failing. Please fix them.")
hasBinaryFile
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:
Type | Description |
---|---|
boolean | true if the pull request contains a binary file, false otherwise. |
Examples:
$hasBinaryFile()
A reviewpad.yml
example:
workflows:
- name: disallow-binary-file
if:
- $hasBinaryFile()
then:
- $close()
- $error("Please don't add any binary file into the repository")
hasCodePattern
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:
Parameter | Type | Description |
---|---|---|
query_pattern | string | The query pattern to look for in the patch. |
Return value:
Type | Description |
---|---|
boolean | true if the patch matches the query pattern, false otherwise. |
Examples:
$hasCodePattern("placeBet\(.*\)")
A reviewpad.yml
example:
workflows:
- name: critical-code
if:
- $hasCodePattern("placeBet\(.*\)")
then:
- $assignReviewer($team("core"), 1)
- $addLabel("critical")
hasCodeWithoutSemanticChanges 🧪
This is an experimental built-in. Be careful before using it in production.
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:
Parameter | Type | Description |
---|---|---|
file_patterns_to_ignore (optional) | []string | The list of file pattern globs to ignore in the patch. |
Return value:
Type | Description |
---|---|
boolean | true if the pull request changes are not semantic code changes |
Examples:
$hasCodeWithoutSemanticChanges()
$$hasCodeWithoutSemanticChanges(["**/*_test.go"])
A reviewpad.yml
example:
workflows:
- name: LGTM
if:
- $hasCodeWithoutSemanticChanges()
then:
- $approve("LGTM")
hasFileExtensions
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:
Parameter | Type | Description |
---|---|---|
extensions | []string | The list of all file extensions. |
Return value:
Type | Description |
---|---|
boolean | true if all file extensions in the patch are included in the list, false otherwise. |
Examples:
$hasFileExtensions([".test.ts"])
A reviewpad.yml
example:
workflows:
- name: configuration-changes
if:
- $hasFileExtensions([".yaml"])
then:
- $assignTeamReviewer(["devops"])
hasFileName
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:
Parameter | Type | Description |
---|---|---|
filename | string | The filename to look for in the patch - case sensitive. |
Return value:
Type | Description |
---|---|
boolean | true 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:
$hasFileName("placeBet.js")
A reviewpad.yml
example:
workflows:
- name: configuration-changes
if:
- $hasFileName("Dockerfile")
then:
- $assignTeamReviewer(["devops"])
- $addLabel("devops")
hasFilePattern
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:
Parameter | Type | Description |
---|---|---|
file_pattern | string | The file pattern glob to look for in the patch. |
Return value:
Type | Description |
---|---|
boolean | true if any of the files in the patch matches the provided file pattern, false otherwise. |
Examples:
$hasFilePattern("src/transactions/**")
A reviewpad.yml
example:
workflows:
- name: core-changes
if:
- $hasFilePattern("src/transactions/**")
then:
- $assignTeamReviewer(["core"])
hasGitConflicts
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:
Type | Description |
---|---|
boolean | true if the pull request has Git conflicts, false otherwise. |
Examples:
$hasGitConflicts()
A reviewpad.yml
example:
workflows:
- name: check-compliance
if:
- $hasGitConflicts()
then:
- $fail("Pull request has git conflicts")
hasLinearHistory
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:
Type | Description |
---|---|
boolean | true if the pull request has a linear history, false otherwise. |
Examples:
$hasLinearHistory()
A reviewpad.yml
example:
workflows:
- name: check-compliance
if:
- $hasLinearHistory() == false
then:
- $fail("The pull request does not have a linear history.")
hasLinkedIssues
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:
Type | Description |
---|---|
boolean | true if the pull request has linked issues, false otherwise. |
Examples:
$hasLinkedIssues()
A reviewpad.yml
example:
rules:
- name: is-compliant
spec: $hasLinkedIssues() && $hasLinearHistory()
workflows:
- name: assign-reviewers
if:
- rule: is-compliant
then:
- $assignRandomReviewer()
hasRequiredApprovals
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:
Parameter | Type | Description |
---|---|---|
total_required_approvals | int | The number of required approving reviews. |
required_approvals_from | []string | The list of users where the required approving reviews must come from. |
Return value:
Type | Description |
---|---|
boolean | true if the number of required approvals comes from the list of users, false otherwise. |
Examples:
$hasRequiredApprovals(2, ["john", "jane", "peter"])
A reviewpad.yml
example:
workflows:
- name: merge
if:
- $hasRequiredApprovals(2, $team("core"))
then:
- $merge()
hasUnaddressedThreads
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:
Type | Description |
---|---|
boolean | true if the pull request has any review thread that is not resolved or outdated , false otherwise. |
Examples:
$hasUnaddressedThreads()
A reviewpad.yml
example:
workflows:
- name: attention-set
if:
- $hasUnaddressedThreads()
then:
- $addLabel("requires-author-attention")
haveAllChecksRunCompleted
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
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
if:
- $haveAllChecksRunCompleted([], "success")
then:
- $comment("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 $comment("Hello")
for each check. This will result in 5 comments.
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:
Parameter | Type | Description |
---|---|---|
check_runs_to_ignore (optional) | []string | List of check run names to be disregarded. |
conclusion (optional) | string | The final conclusion of the check. Empty by default. All conclusion values are valid. |
check_conclusions_to_ignore (optional) | []string | List of check conclusions to be disregarded. Any checks with a conclusion in that list will be ignored. |
Return value:
Type | Description |
---|---|
boolean | true if all check runs have been completed, false otherwise. |
Examples:
All check runs have been completed (regardless of the conclusion).
$haveAllChecksRunCompleted()
All check runs have been completed except for the integration-tests
check.
$haveAllChecksRunCompleted(["integration-tests"])
All check runs have been completed with a success
conclusion.
$haveAllChecksRunCompleted([], "success")
All check runs have been completed with success
ignoring the checks with skipped
conclusion.
$haveAllChecksRunCompleted([], "success", ["skipped"])
A reviewpad.yml
example:
workflows:
- name: auto-merge
if:
- $haveAllChecksRunCompleted([], "success", ["skipped"])
then:
- $merge()
head
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:
Type | Description |
---|---|
string | The name of the branch where the pull request changes are implemented. |
Examples:
$head()
A reviewpad.yml
example:
workflows:
- name: label-change-type
if:
- rule: $startsWith($head(), "feat/")
extra-actions:
- $addLabel("feature")
- rule: $startsWith($head(), "fix/")
extra-actions:
- $addLabel("fix")
isBinary
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:
Parameter | Type | Description |
---|---|---|
filepath | string | The filepath to the file to verify if it is binary. |
Return value:
Type | Description |
---|---|
boolean | true if the file is a binary, false otherwise. |
Examples:
$isBinary("folder/filename")
$isBinary("filename")
A reviewpad.yml
example:
workflows:
- name: blacklist-binary-files
if:
- rule: '$any(["file", "folder/file"], ($file: String => $isBinary($file)))'
then:
- $fail("Blacklisted binary files aren't allowed in pull request")
isDraft
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:
Type | Description |
---|---|
boolean | true if the pull request is a draft, false otherwise. |
Examples:
$isDraft()
A reviewpad.yml
example:
rules:
- name: is-ready-to-review
# The expression is wrapped in quotes to avoid YAML parsing errors
spec: '!$isDraft() && $hasLinkedIssues() && $hasLinearHistory()'
workflows:
- name: distribute-review
if:
- rule: is-ready-to-review
then:
- $assignRandomReviewer()
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:
Parameter | Type | Description |
---|---|---|
project_title | string | The title of the project - case sensitive. |
Return value:
Type | Description |
---|---|
boolean | true if the pull request / issue is linked to the project, false otherwise. |
Examples:
$isLinkedToProject("project title")
A reviewpad.yml
example:
workflows:
- name: add-to-project
if:
- '!$isLinkedToProject("project-title")'
then:
- $addToProject("project-title", "column")
isUpdatedWithBaseBranch
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:
Type | Description |
---|---|
boolean | true if the pull request is updated with the base branch, false otherwise. |
Examples:
$isUpdatedWithBaseBranch()
A reviewpad.yml
example:
workflows:
- name: rebase
if:
- '!$isUpdatedWithBaseBranch()'
then:
- $rebase()
isMerged
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:
Type | Description |
---|---|
boolean | true if the pull request is merged, false otherwise. |
Examples:
$isMerged()
A reviewpad.yml
example:
workflows:
- name: notify-unaddressed-threads-merge
if:
- rule: $hasUnaddressedThreads() && $isMerged()
then:
- $comment("Pull request merged with unaddressed threads!")
isWaitingForReview
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:
Type | Description |
---|---|
boolean | true if the pull request is waiting for review, false otherwise. |
Examples:
$isWaitingForReview()
A reviewpad.yml
example:
workflows:
- name: attention-set
if:
- rule: $isWaitingForReview()
extra-actions:
- $addLabel("waiting-for-review")
- rule: $hasUnaddressedThreads()
extra-actions:
- $addLabel("requires-author-attention")
join
Description:
Concatenates an array of strings, using the specified separator between each member.
Parameters:
Parameter | Type | Description |
---|---|---|
elements | []string | The array to join. |
separator | string | The separator to put between the elements. |
Return value:
Type | Description |
---|---|
string | The 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
if:
- $hasAnnotation("security")
then:
- '$warn($sprintf("This pull request contains security changes. Please, request a 1:1 with security team: %s", [$join($team("security", ", "))]))'
labels
Description:
Retrieves the list of labels of the pull request / issue.
Parameters:
none
Return value:
Type | Description |
---|---|
[]string | The list of labels of the pull request / issue. |
Examples:
$labels()
A reviewpad.yml
example:
workflows:
- name: assign-reviewers
if:
- rule: $isElementOf("bug", $labels())
then:
- $assignTeamReviewer(["testers"])
lastEventAt
Description:
Retrieves the timestamp of the last event in the timeline.
Parameters:
none
Return value:
Type | Description |
---|---|
int64 | The number of seconds elapsed since January 1, 1970 UTC. |
Examples:
$lastEventAt()
A reviewpad.yml
example:
rules:
- name: stale-pull-request
spec: $lastEventAt() < 30 days ago
workflows:
- name: stale
if:
- rule: stale-pull-request
then:
- $addLabel("stale")
- $comment("This pull request has been automatically marked as stale")
milestone
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:
Type | Description |
---|---|
string | The milestone title associated with the pull request. |
Examples:
$milestone()
A reviewpad.yml
example:
workflows:
- name: label-milestone
if:
- rule: $milestone() == "Hacktoberfest"
extra-actions:
- $addLabel("hacktoberfest")
- rule: $startsWith($milestone(), "v")
extra-actions:
- $addLabel("release")
requestedReviewers
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
Description:
Retrieves the list of GitHub user logins or team slugs that were requested to review the pull request.
Parameters:
none
Return value:
Type | Description |
---|---|
[]string | The list of GitHub user logins or team slugs that were requested to review the pull request. |
Examples:
$requestedReviewers()
A reviewpad.yml
example:
workflows:
- name: assign-reviewer
if:
- $requestedReviewers() == []
then:
- $info("Please assign a reviewer.")
reviewers
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
Be aware that this built-in DOES NOT retrieve the list of ALL reviewers on a pull request but the list of the reviewers that have REVIEWED the pull request.
If you wish to retrieve the list of all reviewers on a pull request, you can create a group
and use both reviewers
and requestedReviewers
built-ins.
Here's an example:
groups:
- name: all-reviewers
spec: $append($reviewers(), $requestedReviewers())
Description:
Retrieves the list of GitHub user logins that have reviewed the pull request.
Parameters:
none
Return value:
Type | Description |
---|---|
[]string | The list of GitHub user logins that have reviewed the pull request. |
Examples:
$reviewers()
A reviewpad.yml
example:
rules:
- name: missing-senior-reviewer
# The expression is wrapped in quotes to avoid YAML parsing errors
spec: '$any($reviewers(), ($r: String => $isElementOf($r, $team("seniors")))) == false'
workflows:
- name: check-compliance
if:
- rule: missing-senior-reviewer
extra-actions:
- $info("A pull request must have at least one senior reviewer")
reviewerStatus
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:
Parameter | Type | Description |
---|---|---|
reviewer_login | string | The GitHub login of the reviewer. |
Return value:
Type | Description |
---|---|
string | The status of a reviewer. It can be one of four 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:
$reviewerStatus("marcelosousa")
A reviewpad.yml
example:
rules:
- name: has-approval
# The expression is wrapped in quotes to avoid YAML parsing errors
spec: '$any($reviewers(), ($r: String => $reviewerStatus($r) == "APPROVED"))'
workflows:
- name: merge
if:
- rule: has-approval
then:
- $merge()
size
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:
Parameter | Type | Description |
---|---|---|
excluded_patterns (optional) | []string | The file patterns to exclude from count. |
Return value:
Type | Description |
---|---|
int | The sum of all changed lines in the patch. |
Examples:
$size(["*.lock"])
A reviewpad.yml
example:
workflows:
- name: check-compliance
if:
# Verify size ignoring lock files
- $size(["*.lock"]) > 100
then:
- $error("Change is too big")
state
Description:
Retrieves the state of a pull request / issue.
This state can be either open
or closed
.
Parameters:
none
Return value:
Type | Description |
---|---|
string | The state of the pull request / issue. The state can be open or closed . |
Examples:
$state()
A reviewpad.yml
example:
workflows:
- name: thank-contributors
if:
- $state() == "closed"
then:
- $info("Thanks for your contribution!")
title
Description:
Retrieves the title of the pull request / issue.
Parameters:
none
Return value:
Type | Description |
---|---|
string | The title of the pull request / issue. |
Examples:
$title()
A reviewpad.yml
example:
workflows:
- name: check-compliance
if:
- $title() == ""
then:
- $fail("A pull request must have a title")
workflowStatus 🗑️
This built-in is no longer recommended. Avoid using it, and update existing code if possible.
Be aware that this built-in may cease to work at any time.
Please consider using checkRunConclusion
built-in instead.
Description:
Retrieves the status of a workflow run.
Parameters:
Parameter | Type | Description |
---|---|---|
workflow_name | string | The name of the workflow run. |
Return value:
Type | Description |
---|---|
string | The conclusion of the check run, can be action_required , cancelled , failure , neutral , success , skipped , stale , or timed_out . |
Examples:
$workflowStatus("reviewpad")
A reviewpad.yml
example:
workflows:
- name: merge
if:
- rule: $workflowStatus("build") == "success"
then:
- $merge()
Organization
Set of functions to get organization details.
organization
Description:
Lists all the members of the organization that own the pull request / issue.
If the authenticated user is an owner of the organization, this will return both concealed and public members, otherwise it will only return public members.
Parameters:
none
Return value:
Type | Description |
---|---|
[]string | The list of all the members of the organization to where the pull request / issue is running against. |
Examples:
$organization()
A reviewpad.yml
example:
rules:
- name: external-contributor
spec: $isElementOf($author(), $organization()) == false
workflows:
- name: external-contributions
if:
- rule: external-contributor
then:
- $assignTeamReviewer(["core"])
- $addLabel("external-contributor")
- $commentOnce("Thank you for your contribution!")
team
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:
Parameter | Type | Description |
---|---|---|
team_slug | string | The slug of the team name on GitHub. |
Return value:
Type | Description |
---|---|
[]string | The list of all team and child teams members GitHub login. |
Examples:
$team("devops")
A reviewpad.yml
example:
workflows:
- name: assign-devops-reviewer
if:
- $isElementOf($author(), $team("devops"))
then:
- $assignTeamReviewer(["devops"])
User
Set of functions to get user details.
issueCountBy
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:
Parameter | Type | Description |
---|---|---|
user_login | string | The GitHub user login. |
state (optional) | string | The 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:
Type | Description |
---|---|
int | The total number of issues created by the given GitHub user login with the state. |
Examples:
$issueCountBy($author())
A reviewpad.yml
example:
workflows:
- name: congratulate
if:
- rule: $issueCountBy($author(), "all") == 1
extra-actions:
- $commentOnce("Congratulations on your first issue!")
- rule: $issueCountBy($author(), "all") == 10
extra-actions:
- $commentOnce("Way to go! You have created 10 issues!")
pullRequestCountBy
Description:
Retrieves the total number of pull requests created by the given GitHub user login and state.
Parameters:
Parameter | Type | Description |
---|---|---|
user_login | string | The GitHub user login. |
state (optional) | string | The 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:
Type | Description |
---|---|
int | The total number of pull requests created by the given GitHub user login with provided the state. |
Examples:
$pullRequestCountBy($author(), "all")
A reviewpad.yml
example:
workflows:
- name: check-workload
if:
- $pullRequestCountBy($author(), "open") > 2
then:
- $commentOnce("You have too many open pull requests.")
totalCodeReviews
Description:
Retrieves the total number of code reviews made by the given GitHub user login.
Parameters:
Parameter | Type | Description |
---|---|---|
user_login | string | The GitHub user login. |
Return value:
Type | Description |
---|---|
int | The total number of code reviews made by the GitHub user login. |
Examples:
$totalCodeReviews($author())
A reviewpad.yml
example:
rules:
- name: is-junior-author
spec: $totalCodeReviews($author()) < 5
workflows:
- name: assign-reviewers
if:
- rule: is-junior-author
then:
- $assignReviewer($team("seniors"), 1, "reviewpad")
totalCreatedPullRequests 🗑️
This built-in is no longer recommended. Avoid using it, and update existing code if possible.
Be aware that this built-in may cease to work at any time.
Please consider using pullRequestCountBy
built-in instead.
Description:
Retrieves the total number of pull requests created by the given GitHub user login.
Parameters:
Parameter | Type | Description |
---|---|---|
user_login | string | The GitHub user login. |
Return value:
Type | Description |
---|---|
int | The total number of pull requests created by the GitHub user login. |
Examples:
$totalCreatedPullRequests($author())
A reviewpad.yml
example:
workflows:
- name: workload
if:
- $pullRequestCountBy($author(), "open") > 2
then:
- $commentOnce("You have too many open pull requests.")
Utilities
Set of functions to help handle the queried data.
all
Description:
Determines if all elements of the slice satisfy the given predicate.
Parameters:
Parameter | Type | Description |
---|---|---|
slice | []string | The slice of strings. |
predicate | (string => boolean) | The predicate over string. |
Return value:~
Type | Description |
---|---|
boolean | true if the predicate is true for all elements of the slice, false otherwise. |
Examples:
'$all(["a", "b"], ($el: String => $el == "a"))' # false
A reviewpad.yml
example:
workflows:
- name: merge
if:
# Verify if all reviewers approved the pull request.
# The expression is wrapped in quotes to avoid YAML parsing errors.
- '$all($reviewers(), ($r: String => $reviewerStatus($r) == "APPROVED"))'
then:
- $merge()
any
Description:
Determines if any element of the slice satisfies the given predicate.
Parameters:
Parameter | Type | Description |
---|---|---|
slice | []string | The slice of strings. |
predicate | (string => boolean) | The predicate over string. |
Return value:
Type | Description |
---|---|
boolean | true 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:
workflows:
- name: merge
if:
# Verify if any reviewer approved the pull request.
# The expression is wrapped in quotes to avoid YAML parsing errors.
- '$any($reviewers(), ($r: String => $reviewerStatus($r) == "APPROVED"))'
then:
- $merge()
append
Description:
Appends elements to the end of a slice and retrieves the updated slice.
Parameters:
Parameter | Type | Description |
---|---|---|
slice | []string | The slice that will have elements appended to it. |
elements | []string | The elements to be added to the end of the slice. |
Return value:
Type | Description |
---|---|
[]string | A new slice by appending the slices passed to it. |
Examples:
$append(["a", "b"], ["c"]) # ["a", "b", "c"]
A reviewpad.yml
example:
groups:
- name: all-devs
kind: developers
spec: $append($team("frontend"), $team("backend"))
workflows:
- name: reviewer-assignment
if:
- $description() != ""
then:
- $assignReviewer($group("all-devs"), 1)
contains
Description:
Determines whether a text includes a certain sentence, returning true
or false
as appropriate.
Parameters:
Parameter | Type | Description |
---|---|---|
text | string | The text to search in. |
search_sentence | string | The sentence to search for. |
Return value:
Type | Description |
---|---|
boolean | true 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:
workflows:
- name: labe-change-type
if:
- $contains($title(), "fix")
then:
- $addLabel("bug")
filter
Description:
Filters the elements in the slice based on whether they satisfy a given predicate.
Parameters:
Parameter | Type | Description |
---|---|---|
slice | []string | The slice of strings. |
predicate | (string => boolean) | The predicate over string. |
Return value:
Type | Description |
---|---|
[]string | The 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:
workflows:
- name: merge
if:
# 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.
- '$length($filter($reviewers(), ($r: String => $isElementOf($r, $team("maintainers"))))) == 0'
then:
- $info("No maintainer has reviewed the pull request yet")
isElementOf
Description:
Determines whether a list includes a certain value among its entries, returning true
or false
as appropriate.
Parameters:
Parameter | Type | Description |
---|---|---|
search_element | string | The value to search for. |
list | []string | The list to search in. |
Return value:
Type | Description |
---|---|
boolean | true 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:
workflows:
- name: requires-review
if:
- $isElementOf($author(), $team("juniors"))
then:
- $assignTeamReviewer(["seniors"])
length
Description:
Retrieves the length of an array.
Parameters:
Parameter | Type | Description |
---|---|---|
array | []string | The array of elements. |
Return value:
Type | Description |
---|---|
int | The length of the array. |
Examples:
$length(["a", "b"]) # 2
A reviewpad.yml
example:
workflows:
- name: check-compliance
if:
- rule: $length($reviewers()) < 2
extra-actions:
- $info("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:
Parameter | Type | Description |
---|---|---|
pattern | string | The regular expression pattern |
text | string | The text to match |
Return value:
Type | Description |
---|---|
boolean | true if text matches the pattern , false otherwise. |
Examples:
$matchString("a(bc)+$", "abcbc") # true
$matchString("\d+", "text") # false
A reviewpad.yml
example:
workflows:
- name: branch-convention
if:
- rule: '!$matchString("(feature|fix|docs)/.+", $head())'
then:
- $error("The branch name must start with 'feature/', 'fix/' or 'docs/'")
selectFromJSON
Description:
Allows the selection of arbitrary value(s) from a JSON
type using a JSONPath expression.
If no value is found for the given expression, an empty string is returned.
Parameters:
Parameter | Type | Description |
---|---|---|
json | JSON | The JSON value to select from |
expression | string | The JSONPath expression to evaluate |
Return value:
Type | Description |
---|---|
string | The 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:
workflows:
- name: label-rebaseable
if:
- rule: $selectFromJSON($toJSON($context), "$.rebaseable") == "true"
then:
- $addLabel("rebaseable")
sprintf
Description:
Returns a formatted string.
Parameters:
Parameter | Type | Description |
---|---|---|
format_string | string | The string to be formatted. |
arguments_list | []string | The list of arguments to replace the format specifiers. |
Return value:
Type | Description |
---|---|
string | The formatted string. |
Examples:
$sprintf("Hello, %s!", ["world"]) # "Hello, world!"
A reviewpad.yml
example:
workflows:
- name: congratulate
if:
- $pullRequestCountBy($author(), "all") == 1
then:
- $commentOnce($sprintf("Thank you @%s for this first contribution!", [$author()]))
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:
Parameter | Type | Description |
---|---|---|
expression | string | The JSONPath expression to evaluate |
Return value:
Type | Description |
---|---|
string | The 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:
workflows:
- name: label-rebaseable
if:
- rule: $selectFromContext("$.rebaseable") == "true"
then:
- $addLabel("rebaseable")
startsWith
Description:
Determines whether a text starts with a certain sentence, returning true
or false
as appropriate.
Parameters:
Parameter | Type | Description |
---|---|---|
text | string | The text to search in. |
prefix | string | The prefix. |
Return value:
Type | Description |
---|---|
boolean | true 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:
workflows:
- name: label-change-type
if:
- rule: $startsWith($head(), "feature/")
extra-actions:
- $addLabel("feature")
- rule: $startsWith($head(), "fix/")
extra-actions:
- $addLabel("fix")
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:
Parameter | Type | Description |
---|---|---|
string | string | The string value to be converted to a boolean. |
Return value:
Type | Description |
---|---|
bool | The converted boolean |
Examples:
$toBool("true")
$toBool("false")
$toBool($selectFromContext("$.locked"))
A reviewpad.yml
example:
workflows:
- name: label-locked
if:
- rule: $toBool($selectFromContext("$.locked"))
then:
- $addLabel("locked")
toJSON
Description:
Converts a JSON serialized string to a JSON object.
Parameters:
Parameter | Type | Description |
---|---|---|
json_string | string | JSON serialized string |
Return value:
Type | Description |
---|---|
JSON | The JSON object corresponding to the serialized string. |
Examples:
$toJSON($context())
$toJSON("[1, 2, 3]")
A reviewpad.yml
example:
workflows:
- name: label-mergeable
if:
- rule: $selectFromJSON($toJSON($context()), "$.mergeable") == "true"
then:
- $addLabel("mergeable")
toNumber
Description:
Converts a string into a number.
Parameters:
Parameter | Type | Description |
---|---|---|
string | string | The string value to convert to a number. |
Return value:
Type | Description |
---|---|
int | The converted number |
Examples:
$toNumber("1")
$toNumber("-1")
$toNumber($selectFromContext("$.comments"))
A reviewpad.yml
example:
workflows:
- name: warn-large-pull-requests
if:
- rule: $toNumber($selectFromContext("$.additions")) > 100
then:
- $warn("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 the value can not be converted.
Parameters:
Parameter | Type | Description |
---|---|---|
json_string | string | JSON serialized array of string |
Return value:
Type | Description |
---|---|
[]string | The array of string values. |
Examples:
$toStringArray($selectFromContext("$.labels[*].name"))
A reviewpad.yml
example:
groups:
- name: deprecated-labels
description: List of labels that should not be used
spec: '["foo", "bar"]'
workflows:
- name: warn-outdated-labels
if:
- rule: '$any($toStringArray($selectFromContext("$.labels[*].name")), ($label: String => $isElementOf($label, $group("deprecated-labels"))))'
then:
- $warn($sprintf("Please do not use the deprecated labels %s", [$join($group("deprecated-labels"), ", ")]))
Engine
Set of functions used to handle reviewpad.yml
file.
This functions should be used to access and handle data declared into reviewpad.yml
, e.g. $group
to get a defined group.
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:
Parameter | Type | Description |
---|---|---|
group_name | string | The group name to list all the members from. |
Return value:
Type | Description |
---|---|
[]string | All the members from the group. |
Examples:
$group("techLeads")
A reviewpad.yml
example:
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: $pullRequestCountBy($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
if:
- $size($group("ignore_paths")) < 10
then:
- $addLabel("small")
- name: review-juniors-changes
if:
- $isElementOf($author(), $group("juniors"))
then:
- $assignReviewer($group("tech-leads"), 1)
rule
Description:
Evaluates a rule. This rule needs to be defined in the same reviewpad.yml
file.
Parameters:
Parameter | Type | Description |
---|---|---|
rule_name | string | The rule name. |
Return value:
Type | Description |
---|---|
boolean | The evaluation of the rule. |
Examples:
'$rule("is-small")'
A reviewpad.yml
example:
rules:
- name: size-compliance
spec: $size() < 100
- name: description-compliance
spec: $description() != ""
- name: is-compliant
spec: $rule("size-compliance") && $rule("description-compliance")
workflows:
- name: check-compliance
if:
- rule: is-compliant
then:
- $assignRandomReviewer()
Actions
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:
labels:
small:
name: Small Change
description: Few files
medium:
description: Some files
workflows:
- name: add-label
if:
- rule: $size() < 10
extra-actions:
- $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:
Parameter | Type | Description |
---|---|---|
name | string | The name of the label to add. |
Examples:
$addLabel("bug")
A reviewpad.yml
example:
workflows:
- name: label-small-pull-request
if:
- $size() < 10
then:
- $addLabel("small")
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:
Parameter | Type | Description |
---|---|---|
project_title | string | The title of the project - case sensitive. |
status | string | The status of the pull request / issue (must exist as a status). |
Examples:
$addToProject("reviewpad", "in progress")
A reviewpad.yml
example:
workflows:
- name: add-to-project
if:
- $hasLinkedIssues() == false
then:
- $addToProject("jupiter", "in progress")
approve
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
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:
Parameter | Type | Description |
---|---|---|
message (optional) | string | The message to write as a comment. |
Examples:
$approve()
A reviewpad.yml
example:
workflows:
- name: trivial-changes
if:
- $hasFileExtensions([".md"])
then:
- $approve("LGTM")
assignAssignees
Description:
Assigns a defined amount of assignees to a pull request / issue.
Users already assigned to a pull request / issue are not replaced.
Parameters:
Parameter | Type | Description |
---|---|---|
assignees | []string | The list of GitHub logins to assign the pull request / issue to. |
total (optional) | int | The total number of assignees to assign to, between 1 and 10. By default, it assigns to all assignees. |
Examples:
$assignAssignees(["john", "marie", "peter"])
$assignAssignees($team("engineering"), 2)
A reviewpad.yml
example:
workflows:
- name: assign-core-team
always-run: true
if:
- $author() == "renovate[bot]"
then:
- $assignAssignees($team("core"), 1)
assignCodeAuthorReviewers
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.
When there are no reviewers to assign to, an error is returned.
Parameters:
Parameter | Type | Description |
---|---|---|
total_required_reviewers (optional) | int | The total number of required reviewers. By default, it is one. |
excluded_reviewers (optional) | []string | List of usernames to exclude from review requests. |
max_reviews (optional) | int | The maximum number of open pull requests that a single user can be responsible for reviewing. |
Examples:
$assignCodeAuthorReviewers(2, ["john", "marie"], 3)
A reviewpad.yml
example:
workflows:
- name: assign-reviewer
if:
- '!$isWaitingForReview() && !$isDraft()'
then:
- $assignCodeAuthorReviewers(2, ["john", "marie"], 3)
assignRandomReviewer
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:
$assignRandomReviewer()
A reviewpad.yml
example:
workflows:
- name: assign-reviewer
if:
- $description() != ""
then:
- $assignRandomReviewer()
assignReviewer
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 theround-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:
Parameter | Type | Description |
---|---|---|
reviewers | []string | The list of GitHub logins to select from. |
total (optional) | int | The total number of reviewers to assign to. By default, it assigns to all reviewers. |
policy (optional) | string | The policy followed for reviewer assignment. By default, the policy is reviewpad . |
Examples:
$assignReviewer(["john", "marie", "peter"], 2, "random")
A reviewpad.yml
example:
workflows:
- name: reviewers-assignment
if:
- rule: $isElementOf($author(), $team("devops"))
extra-actions:
- $assignReviewer($team("devops"))
- rule: $isElementOf($author(), $team("juniors"))
extra-actions:
- $assignReviewer($team("seniors"), 1, "reviewpad")
assignTeamReviewer
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:
Parameter | Type | Description |
---|---|---|
team_reviewers | []string | The list of GitHub team slugs that will be requested to review. |
Examples:
$assignTeamReviewer(["core", "support"])
A reviewpad.yml
example:
workflows:
- name: reviewers-assignment
if:
- $hasCodePattern("critical\(.*\)")
then:
- $assignTeamReviewer(["core"])
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:
Parameter | Type | Description |
---|---|---|
comment (optional) | string | The body of the comment. |
reason (optional) (issues only) | string | The 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:
workflows:
- name: stale
if:
- rule: $lastEventAt() < 30 days ago
then:
- $addLabel("stale")
- $close("This pull request has been automatically closed due to inactivity")
- name: project_deprecated
on:
- "issue"
if:
- rule: $isElementOf("jupiter", $labels())
then:
- $close("The project `jupiter` is deprecated", "not_planned")
comment
Please be aware that this built-in may cause unexpected behavior.
The comment built-in is executed on each Reviewpad execution as long as the condition is met.
In the configuration below, the comment will be posted on each Reviewpad execution as long as the pull request has at least one approval.
For instance, if after getting approval there are 5 activities on the pull request (e.g. committing, pushing, labelling), the comment will be posted 5 times.
workflows:
- name: comment
if:
- rule: $approvalsCount() > 0
then:
- $comment("This pull request has been approved.")
You might consider using the commentOnce
built-in instead.
Description:
Posts a comment on the pull request / issue.
Parameters:
Parameter | Type | Description |
---|---|---|
comment | string | The body of the comment. |
Examples:
$comment("This pull request has git conflicts. Please resolve them.")
A reviewpad.yml
example:
workflows:
- name: update-to-date
if:
- $hasLinearHistory() == false
then:
- $comment("The pull request does not have a linear history.")
- $fail("non-linear history")
commentOnce
Description:
Posts a comment to the pull request / issue once.
If the comment is already present, then the action does nothing.
Parameters:
Parameter | Type | Description |
---|---|---|
comment | string | The body of the comment. |
Examples:
$commentOnce("This is your first contribution! Thank you!")
A reviewpad.yml
example:
workflows:
- name: congratulate
if:
- rule: $pullRequestCountBy($author(), "all") == 1
extra-actions:
- $commentOnce("Thank you for your first contribution!")
commitLint
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
Description:
Checks if the commits in the pull request follow the conventional commits specification.
Parameters:
none
Examples:
$commitLint()
A reviewpad.yml
example:
workflows:
- name: check-conventional-commits
if:
- $base() == "main"
then:
- $commitLint()
deleteHeadBranch
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
This built-in does not work on pull request from forks.
Deleting a branch will cause all pull requests that have the deleted branch as head or base to be closed.
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:
rules:
- name: ready-to-merge
spec: $hasFileExtensions([".md"])
workflows:
- name: check-compliance
if:
- rule: ready-to-merge
then:
- $merge()
- $deleteHeadBranch()
disableActions
Description:
Disables the list of actions passed as an argument.
Parameters:
Parameter | Type | Description |
---|---|---|
actions | []string | The list of actions to be disabled. |
Examples:
$disableActions(["assignReviewer"])
A reviewpad.yml
example:
workflows:
- name: protect-actions
if:
- $isDraft()
then:
- $disableActions(["assignReviewer", "assignTeamReviewer", "assignRandomReviewer"])
- $disableActions(["merge"])
error
Description:
Add a message to the errors section of the report.
Parameters:
Parameter | Type | Description |
---|---|---|
comment | string | The comment to be added in the errors. |
Examples:
$error("Please do not touch these files.")
A reviewpad.yml
example:
workflows:
- name: check-compliance
if:
- $size() > 100
then:
- $error("This pull request is too large")
fail
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:
Parameter | Type | Description |
---|---|---|
fail_message | string | The fail message. |
Examples:
$fail("Missing specs")
A reviewpad.yml
example:
rules:
- name: missing-tests
spec: $changed("src/@1.java", "test/@1.java") == false
workflows:
- name: check-compliance
if:
- rule: missing-tests
then:
- $fail("Please include tests for your change")
info
Description:
Adds a message to the info section of the report.
Parameters:
Parameter | Type | Description |
---|---|---|
comment | string | The comment to be added in the informations. |
Examples:
$info("Please do not forget to add the tests.")
A reviewpad.yml
example:
workflows:
- name: when-transactions
if:
- $hasFilePattern("**/transactions")
then:
- $info("You have changed transactions. Please schedule a meeting.")
- $addLabel("critical")
merge
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:
Parameter | Type | Description |
---|---|---|
method (optional) | string | The merge method (merge, rebase or squash). By default, it will perform a standard git merge. |
Examples:
$merge()
A reviewpad.yml
example:
rules:
- name: only-changes-documentation
spec: $hasFileExtensions([".md"])
workflows:
- name: merge
if:
- rule: only-changes-documentation
then:
- $merge()
rebase
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
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:
workflows:
- name: rebase-pull-request
if:
- $toBool($selectFromContext("$.rebaseable"))
then:
- $rebase()
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:
Parameter | Type | Description |
---|---|---|
project_title | string | The title of the project - case sensitive. |
Examples:
$removeFromProject("reviewpad")
A reviewpad.yml
example:
workflows:
- name: remove-from-project
if:
- '!$isMerged() && $state() == "closed"'
then:
- $removeFromProject("reviewpad")
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:
Parameter | Type | Description |
---|---|---|
name | string | The name of the label to remove. |
Examples:
$removeLabel("bug")
A reviewpad.yml
example:
workflows:
- name: conflicts
if:
- rule: $hasGitConflicts() == false
extra-actions:
- $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:
Parameter | Type | Description |
---|---|---|
labels | []string | The list of the labels to be removed. |
Examples:
$removeLabels(["bug", "p1"])
A reviewpad.yml
example:
workflows:
- name: label-size
if:
- rule: $size() < 10
extra-actions:
- $addLabel("small")
- $removeLabels(["medium", "large"])
review
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:
Parameter | Type | Description |
---|---|---|
review_type | string | The kind of review, can be APPROVE , REQUEST_CHANGES , COMMENT . |
message | string | The message to write as a comment. |
Examples:
$review("APPROVE", "")
A reviewpad.yml
example:
rules:
- name: missing-tests
spec: $changed("src/@1.java", "test/@1.java") == false
workflows:
- name: validate-changes
if:
- rule: missing-tests
then:
- $review("REQUEST_CHANGES", "Please include the tests for your change")
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:
Parameter | Type | Description |
---|---|---|
project_title | string | The title of the project - case sensitive. |
field | string | The custom field which can be text, number, or single select (must exist). |
value | string | The value of the field. |
Examples:
$setProjectField("reviewpad", "priority", "P1")
$setProjectField("reviewpad", "size", "50")
A reviewpad.yml
example:
workflows:
- name: set-project-field
if:
- $hasLinkedIssues() == false
then:
- $addToProject("jupiter", "in progress")
- $setProjectField("jupiter", "notes", "missing issue")
titleLint
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
Description:
Checks if the pull request title follows the conventional commits specification.
Parameters:
none
Examples:
$titleLint()
A reviewpad.yml
example:
workflows:
- name: check-conventional-commits
if:
- $base() == "main"
then:
- $titleLint()
triggerWorkflow
This built-in is unavailable for issues. Reviewpad will ignore it when running on issues.
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:
Parameter | Type | Description |
---|---|---|
file_name | string | The workflow file name. |
Examples:
$triggerWorkflow("main.yml")
A reviewpad.yml
example:
workflows:
- name: run-critical-ci
if:
- $hasAnnotation("critical")
then:
- $triggerWorkflow("ci-critical-tests.yml")
warn
Description:
Adds a message to the warnings section of the report.
Parameters:
Parameter | Type | Description |
---|---|---|
comment | string | The comment to be added in the warnings. |
Examples:
$warn("Please do not forget to add the tests.")
A reviewpad.yml
example:
workflows:
- name: validate-changes
if:
- $hasFilePattern("*.lock")
then:
- $warn("Please remove the lock file from the commit.")