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 to query data from a pull request or organization in order to act on it.

The functions are organized into 4 categories:

• Pull Request - Functions to query pull request 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

---

Set of functions to get pull request details.

assignees

---

Description:

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

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
[]string	The list of GitHub user logins that are assigned to the pull request.

Examples:

$assignees()

A reviewpad.yml example:

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 author GitHub login.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
string	The GitHub login of the pull request author.

Examples:

$author()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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:
      - $error("Please include tests for your change")
      - $fail("missing tests")

commentCount

---

Description:

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

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$commentCount()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
[]string	The list of comment body of the pull request.

Examples:

$comments()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$commitCount()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$commits()

A reviewpad.yml example:

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

createdAt

---

Description:

Retrieves the time the pull request was created at.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
int64	The number of seconds elapsed since January 1, 1970 UTC.

Examples:

$createdAt()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
string	The description of the pull request.

Examples:

$description()

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

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

fileCount

---

Description:

Retrieves the total number of files changed in the patch.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$fileCount()

A reviewpad.yml example:

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.")

hasAnnotation

---

Description:

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

Available for:

Type	Available
issue	❌
pull_request	✅

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:

api-version: reviewpad.com/v3.x

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

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$hasGitConflicts()

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

workflows:
  - name: check-compliance
    if:
      - $hasGitConflicts()
    then:
      - $error("Pull request has git conflicts")
      - $fail("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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$hasLinearHistory()

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

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

hasLinkedIssues

---

Description:

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

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$hasLinkedIssues()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

api-version: reviewpad.com/v3.x

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

head

---

Description:

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

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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

isDraft

---

Description:

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

To know more about GitHub Draft pull request.

Available for:

Type	Available
issue	❌
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:

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

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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$isWaitingForReview()

A reviewpad.yml example:

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

labels

---

Description:

Retrieves the list of labels of the pull request.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
[]string	The list of labels of the pull request.

Examples:

$labels()

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

rules:
  - name: is-bug
    spec: $isElementOf("bug", $labels())

workflows:
  - name: assign-reviewers
    if:
      - rule: is-bug
    then:
      - $assignTeamReviewer(["testers"])

lastEventAt

---

Description:

Retrieves the timestamp of the last event in the timeline.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
int64	The number of seconds elapsed since January 1, 1970 UTC.

Examples:

$lastEventAt()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Return value:

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

Examples:

$milestone()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
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:

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.

Available for:

Type	Available
issue	❌
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:

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.

Available for:

Type	Available
issue	❌
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:

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

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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")
      - $fail("patch with more than 100 lines")

title

---

Description:

Retrieves the title of the pull request.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
string	The title of the pull request.

Examples:

$title()

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

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

workflowStatus

---

Description:

Retrieves the status of a workflow run.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

none

Return value:

Type	Description
[]string	The list of all the members of the organization to where the pull request is running against.

Examples:

$organization()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

Available for:

Type	Available
issue	✅
pull_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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
user_login	string	The GitHub user login.
state	string	The issue 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.

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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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

---

Description:

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

INFO

This built-in will be deprecated in the upcoming 4.x series as it.

Replace its usage by $pullRequestCountBy(CURRENT_ARGUMENT, "all").

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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, falseotherwise.

Examples:

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

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
search_element	literal	The value to search for.
list	[]literal	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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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

sprintf

---

Description:

Returns a formatted string.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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

startsWith

---

Description:

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

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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.

If the label is not applied to the pull request 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:

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

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
name	string	The name of the label to add.

Examples:

$addLabel("bug")

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

workflows:
  - name: label-small-pull-request
    if:
      - $size() < 10
    then:
      - $addLabel("small")

addToProject

---

Description:

Adds a pull request 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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
project_name	string	The name of the project you want to attach the pull request to.
status	string	The status of the pull request (must be present as a status).

Examples:

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

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

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

assignAssignees

---

Description:

Assigns up to 10 assignees to a pull request.

Users already assigned to a pull request are not replaced.

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

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

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

Examples:

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

A reviewpad.yml example:

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

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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Examples:

$assignRandomReviewer()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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.

Available for:

Type	Available
issue	❌
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:

api-version: reviewpad.com/v3.x

workflows:
  - name: reviewers-assignment
    if:
      - $hasCodePattern("critical\(.*\)")
    then:
      - $assignTeamReviewer(["core"])

close

---

Description:

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

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

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
comment (optional)	string	The body of the comment.

Examples:

$close()

A reviewpad.yml example:

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

comment

---

Description:

Posts a comment to the pull request.

Note that this comment will always be added whenever this action is executed.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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 once.

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

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
comment	string	The body of the comment.

Examples:

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

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Examples:

$commitLint()

A reviewpad.yml example:

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.

WARNING

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.

INFO

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

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Examples:

$deleteHeadBranch()

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
actions	[]string	The list of actions to be disabled.

Examples:

$disableActions(["assignReviewer"])

A reviewpad.yml example:

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.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

api-version: reviewpad.com/v3.x

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

fail

---

Description:

Fails the action with a given fail message which will appear in the logs of the GitHub action.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
fail_message	string	The fail message.

Examples:

$fail("missing specs")

A reviewpad.yml example:

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:
      - $error("Please include tests for your change")
      - $fail("missing tests")

info

---

Description:

Adds a message to the info section of the report.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

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, if no parameter is provided, it will perform a standard git merge.

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

Parameter	Type	Description
method	string	The merge method (merge, rebase or squash).

Examples:

$merge()

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

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

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

removeLabel

---

Description:

Removes a label applied to a pull request.

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.

INFO

This built-in will be deprecated in the upcoming 4.x series.

Replace its usage by $removeLabels.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

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

Examples:

$removeLabel("bug")

A reviewpad.yml example:

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 issue or pull request.

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.

Available for:

Type	Available
issue	✅
pull_request	✅

Parameters:

Parameter	Type	Description
labels	[]string	The list of the labels to be removed.

Examples:

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

A reviewpad.yml example:

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 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 last review is not APPROVED;
• the pull request has changes since the last submitted review.

Available for:

Type	Available
issue	❌
pull_request	✅

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:

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

titleLint

---

Description:

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

Available for:

Type	Available
issue	❌
pull_request	✅

Parameters:

none

Examples:

$titleLint()

A reviewpad.yml example:

api-version: reviewpad.com/v3.x

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

warn

---

Description:

Adds a message to the warnings section of the report.

Available for:

Type	Available
issue	✅
pull_request	✅

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:

api-version: reviewpad.com/v3.x

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