Version: v3

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

Description:

Retrieves the total number of approvals for a pull request.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`int`	The total number of approvals the pull request has received.

Examples:

$approvalsCount()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

Description:

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

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: staging-changes
    if:
      - $base() == "stage"
    then:
      - $info("Please make sure you've tested your changes in staging environment.")

changed

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

Description:

Retrieves the conclusion of the given check run.

caution

This built-in is not available for issues.

caution

Reviewpad checks for 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.

Parameters:

Parameter	Type	Description
`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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: waiting-for-feedback
    if:
      - $comments() == []
    then:
      - $addLabel("waiting-for-feedback")

commitCount

Description:

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

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`int`	The total number of commits in the pull request.

Examples:

$commitCount()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: high-activity
    if:
      - $commitCount() > 10
    then:
      - $info("Please consider splitting the pull request into smaller pull requests.")

commits

Description:

Retrieves the list of commit messages of the pull request.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`[]string`	The list of commit messages of the pull request.

Examples:

$commits()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: check-conventions
    if:
      - $description() == ""
    then:
      - $fail("Pull request description is empty")

eventType

Description:

Retrieves the type of the pull request event.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`string`	The `pull_request` event activity type.

Examples:

$eventType()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: assign-reviewer-when-pr-ready-for-review
    if:
      - $eventType() == "ready_for_review"
    then:
      - $assignRandomReviewer()

fileCount

Description:

Retrieves the total number of files changed in the patch.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`int`	The total number of files changed in the patch.

Examples:

$fileCount()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: too-big
    if:
      - $fileCount() > 10
    then:
      - $info("Please consider splitting the pull request into smaller pull requests.")

filesPath

Description:

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

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`[]string`	A list of all file paths changed files in the patch.

Examples:

$filesPath()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: binary-files-not-allowed
    if:
      - '$any($filesPath(), ($filePath: String => $isBinary($filePath)))'
    then:
      - $fail("Binary files are not allowed.")

hasAnnotation

Description:

Verifies if the patch contains a symbol with the provided annotation, returning true or false as appropriate.

INFO

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: security-changes
    if:
      - $hasAnnotation("security")
    then:
      - $assignReviewer($team("security"), 1)

hasBinaryFile

Description:

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

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`boolean`	`true` if the pull request contains a binary file, `false` otherwise.

Examples:

$hasBinaryFile()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: disallow-binary-file
    if:
      - $hasBinaryFile()
    then:
      - $close()
      - $error("Please don't add any binary file into the repository")

hasCodePattern

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: critical-code
    if:
      - $hasCodePattern("placeBet\(.*\)")
    then:
      - $assignReviewer($team("core"), 1)
      - $addLabel("critical")

hasFileExtensions

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: configuration-changes
    if:
      - $hasFileExtensions([".yaml"])
    then:
      - $assignTeamReviewer(["devops"])

hasFileName

Description:

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

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: configuration-changes
    if:
      - $hasFileName("Dockerfile")
    then:
      - $assignTeamReviewer(["devops"])
      - $addLabel("devops")

hasFilePattern

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: core-changes
    if:
      - $hasFilePattern("src/transactions/**")
    then:
      - $assignTeamReviewer(["core"])

hasGitConflicts

Description:

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

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`boolean`	`true` if the pull request has Git conflicts, `false` otherwise.

Examples:

$hasGitConflicts()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

hasLinearHistory

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.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`boolean`	`true` if the pull request has a linear history, `false` otherwise.

Examples:

$hasLinearHistory()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

hasLinkedIssues

Description:

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

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`boolean`	`true` if the pull request has linked issues, `false` otherwise.

Examples:

$hasLinkedIssues()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

rules:
  - name: is-compliant
    spec: $hasLinkedIssues() && $hasLinearHistory()

workflows:
  - name: assign-reviewers
    if:
      - rule: is-compliant
    then:
      - $assignRandomReviewer()

hasRequiredApprovals

Description:

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

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: merge
    if:
      - $hasRequiredApprovals(2, $team("core"))
    then:
      - $merge()

hasUnaddressedThreads

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: attention-set
    if:
      - $hasUnaddressedThreads()
    then:
      - $addLabel("requires-author-attention")

haveAllChecksRunCompleted

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.

caution

This built-in is not available for 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:

api-version: reviewpad.com/v3.x

workflows:
  - name: all-checks-completed
    if:
    - $haveAllChecksRunCompleted([], "success", ["skipped"])
    then:
    - $comment("Hello")

In this example, if you have 5 check runs Reviewpad will run 5 times. If all checks finish with success around the same time, when Reviewpad runs for each check run, all checks have already been completed with success and Reviewpad will run the $comment built-in. This will result in 5 comments.

Parameters:

Parameter	Type	Description
`check_runs_to_ignore` (optional)	`[]string`	List of checks to be disregarded.
`conclusion` (optional)	`string`	The final conclusion of the check
`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 completed, `false` otherwise.

Examples:

All check runs have completed with `success`.

$haveAllChecksRunCompleted()

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

$haveAllChecksRunCompleted(["integration-tests"])

All check runs have been completed with `success`.

$haveAllChecksRunCompleted([], "success")

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

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

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: auto-merge
    if:
      - $haveAllChecksRunCompleted([], "success", ["skipped"])
    then:
      - $merge()

head

Description:

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

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: label-change-type
    if:
      - rule: $startsWith($head(), "feat/")
        extra-actions:
          - $addLabel("feature")
      - rule: $startsWith($head(), "fix/")
        extra-actions:
          - $addLabel("fix")

isBinary

Description:

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

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

Description:

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

To know more about GitHub Draft pull request.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`boolean`	`true` if the pull request is a draft, `false` otherwise.

Examples:

$isDraft()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

isUpdatedWithBaseBranch

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: rebase
    if:
      - '!$isUpdatedWithBaseBranch()'
    then:
      - $rebase()

isMerged

Description:

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

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`boolean`	`true` if the pull request is merged, `false` otherwise.

Examples:

$isMerged()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: notify-unaddressed-threads-merge
    if:
      - rule: $hasUnaddressedThreads() && $isMerged()
    then:
      - $comment("Pull request merged with unaddressed threads!")

isWaitingForReview

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.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`boolean`	`true` if the pull request is waiting for review, `false` otherwise.

Examples:

$isWaitingForReview()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

Description:

Retrieves the milestone title associated to the pull request.

caution

This built-in is not available for issues.

Parameters:

none

Return value:

Type	Description
`string`	The milestone title associated to the pull request.

Examples:

$milestone()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: label-milestone
    if:
      - rule: $milestone() == "Hacktoberfest"
        extra-actions:
          - $addLabel("hacktoberfest")
      - rule: $startsWith($milestone(), "v")
        extra-actions:
          - $addLabel("release")

requestedReviewers

Description:

Retrieves the list of GitHub user logins or team slugs that were requested to review the pull request.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: assign-reviewer
    if:
      - $requestedReviewers() == []
    then:
      - $info("Please assign a reviewer.")

reviewers

Description:

Retrieves the list of GitHub user logins that have reviewed the pull request.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

Description:

Retrieves the status of a reviewer in the pull request.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

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"
}

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

workflowStatus

Description:

Retrieves the status of a workflow run.

Parameters:

Parameter	Type	Description
`workflow_name`	string	The name of the workflow.

Return value:

Type	Description
`string`	The status of the workflow run.

Examples:

$workflowStatus("reviewpad")

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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.

By default, a GitHub action does not have permission to access organization members.

Because of that, in order for the team built-in to work we need to provide a GitHub token to the Reviewpad action.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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 (deprecated)

DEPRECATED

This built-in is deprecated and will be removed in the next major version.

Please use the 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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: labe-change-type
    if:
      - $contains($title(), "fix")
    then:
      - $addLabel("bug")

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: check-compliance
    if:
      - rule: $length($reviewers()) < 2
        extra-actions:
          - $info("A pull request must have at least two reviewers")
      - rule: $length($reviewers()) > 5
        extra-actions:
          - $info("A pull request should not more than 5 reviewers")

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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.

info

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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.

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

caution

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

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

approve

Description:

Submits a pull request review marked as approved.

note

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

caution

This built-in is not available for issues.

Parameters:

Parameter	Type	Description
`message` (optional)	string	The message to write as a comment.

Examples:

$approve()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: trivial-changes
    if:
      - $hasFileExtensions([".md"])
    then:
      - $approve("LGTM")

assignAssignees

Description:

Assigns up to 10 assignees to a pull request / issue.

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

Only users with push access can assign users to a pull request / issue. Otherwise, assignees are silently ignored.

Parameters:

Parameter	Type	Description
`assignees`	[]string	The list of GitHub logins to assign the pull request / issue to.

Examples:

$assignAssignees(["john", "marie", "peter"])

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: always-assign-to-author
    # Run workflow regardless of previous workflow result
    always-run: true
    if:
      - $description() != ""
    then:
      - $assignAssignees([$author()])

assignCodeAuthorReviewers

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: assign-reviewer
    if:
      - '!$isWaitingForReview() && !isDraft()'
    then:
      - $assignCodeAuthorReviewers(2, ["john", "marie"], 3)

assignRandomReviewer

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.

caution

This built-in is not available for issues.

Parameters:

none

Examples:

$assignRandomReviewer()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: assign-reviewer
    if:
      - $description() != ""
    then:
      - $assignRandomReviewer()

assignReviewer

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

Description:

Assigns a list of teams to review the pull request.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

Description:

Posts a comment on the pull request / issue.

caution

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, labeling), 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.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: congratulate
    if:
      - rule: $pullRequestCountBy($author(), "all") == 1
        extra-actions:
          - $commentOnce("Thank you for your first contribution!")

commitLint

Description:

Checks if the commits in the pull request follow the conventional commits specification.

caution

This built-in is not available for issues.

Parameters:

none

Examples:

$commitLint()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: check-conventional-commits
    if:
      - $base() == "main"
    then:
      - $commitLint()

deleteHeadBranch

Description:

Deletes the head branch of the pull request.

caution

This built-in is not available for 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.

Parameters:

none

Examples:

$deleteHeadBranch()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: check-compliance
    if:
      - $size() > 100
    then:
      - $error("This pull request is too large")

fail

Description:

Fails Reviewpad execution with a custom message.

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

caution

This built-in forces Reviewpad to fail.

You will see a ❌ in the reviewpad status check.

Parameters:

Parameter	Type	Description
`fail_message`	string	The fail message.

Examples:

$fail("Missing specs")

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: when-transactions
    if:
      - $hasFilePattern("**/transactions")
    then:
      - $info("You have changed transactions. Please schedule a meeting.")
      - $addLabel("critical")

merge

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

rules:
  - name: only-changes-documentation
    spec: $hasFileExtensions([".md"])

workflows:
  - name: merge
    if:
      - rule: only-changes-documentation
    then:
      - $merge()

rebase

Description:

Rebases the pull request.

caution

This built-in is not available for issues.

caution

Currently, this built-in has some limitations and known issues:

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

Overall, the following table shows the current support for the different scenarios:

	Github App	Github Action
Non forked	✓	✓
User owned fork	✓
Organization owned fork

Parameters:

none

Examples:

$rebase()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: rebase-pull-request
    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:

Parameter	Type	Description
`name`	string	The name of the label to remove.

Examples:

$removeLabel("bug")

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: label-size
    if:
      - rule: $size() < 10
        extra-actions:
          - $addLabel("small")
          - $removeLabels(["medium", "large"])

review

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.

caution

This built-in is not available for issues.

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

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

titleLint

Description:

Checks if the pull request title follows the conventional commits specification.

caution

This built-in is not available for issues.

Parameters:

none

Examples:

$titleLint()

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: check-conventional-commits
    if:
      - $base() == "main"
    then:
      - $titleLint()

triggerWorkflow

Description:

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

caution

Please note that for this built-in to work, the workflow file that you which to trigger must have the workflow_dispatch trigger.

caution

This built-in is not available for issues.

Parameters:

Parameter	Type	Description
`file_name`	string	The workflow file name.

Examples:

$triggerWorkflow("main.yml")

A reviewpad.yml example:

reviewpad.yml
api-version: reviewpad.com/v3.x

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:

reviewpad.yml
api-version: reviewpad.com/v3.x

workflows:
  - name: validate-changes
    if:
      - $hasFilePattern("*.lock")
    then:
      - $warn("Please remove the lock file from the commit.")

Functions​

Pull Request / Issue​

approvalsCount​

assignees​

author​

base​

changed​

checkRunConclusion​

commentCount​

comments​

commitCount​

commits​

context​

createdAt​

description​

eventType​

fileCount​

filesPath​

hasAnnotation​

hasBinaryFile​

hasCodePattern​

hasFileExtensions​

hasFileName​

hasFilePattern​

hasGitConflicts​

hasLinearHistory​

hasLinkedIssues​

hasRequiredApprovals​

hasUnaddressedThreads​

haveAllChecksRunCompleted​

All check runs have completed with success.​

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

All check runs have been completed with success.​

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

head​

isBinary​

isDraft​

isLinkedToProject​

isUpdatedWithBaseBranch​

isMerged​

isWaitingForReview​

join​

labels​

lastEventAt​

milestone​

requestedReviewers​

reviewers​

reviewerStatus​

size​

state​

title​

workflowStatus​

Organization​

organization​

team​

User​

issueCountBy​

pullRequestCountBy​

totalCodeReviews​

totalCreatedPullRequests (deprecated)​

Utilities​

all​

any​

append​

contains​

isElementOf​

length​

matchString​

selectFromJSON​

sprintf​

selectFromContext​

startsWith​

toBool​

toJSON​

toNumber​

toStringArray​

Engine​

group​

rule​

Actions​

Functions

Pull Request / Issue

approvalsCount

assignees

author

base

changed

checkRunConclusion

commentCount

comments

commitCount

commits

context

createdAt

description

eventType

fileCount

filesPath

hasAnnotation

hasBinaryFile

hasCodePattern

hasFileExtensions

hasFileName

hasFilePattern

hasGitConflicts

hasLinearHistory

hasLinkedIssues

hasRequiredApprovals

hasUnaddressedThreads

haveAllChecksRunCompleted

All check runs have completed with `success`.

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

All check runs have been completed with `success`.

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

head

isBinary

isDraft

isLinkedToProject

isUpdatedWithBaseBranch

isMerged

isWaitingForReview

join

labels

lastEventAt

milestone

requestedReviewers

reviewers

reviewerStatus

size

state

title

workflowStatus

Organization

organization

team

User

issueCountBy

pullRequestCountBy

totalCodeReviews

totalCreatedPullRequests (deprecated)

Utilities

all

any

append

contains

isElementOf

length

matchString

selectFromJSON

sprintf

selectFromContext

startsWith

toBool

toJSON

toNumber

toStringArray

Engine

group

rule

Actions