Version: 3.5.0

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 for 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:

Returns the list of GitHub user login that are assigned to the pull request.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

[]string

The list of GitHub user login that are assigned to the pull request.

Examples:

$assignees()

A reviewpad.yml example:

rules:
  - name: assignedToTechLead
    kind: patch
    description: Verifies if pull request was assigned only to a specific tech lead
    spec: $assignees() == ["john"]

author

Description:

Retrieves the pull request author GitHub login.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

string

The GitHub login of the pull request author.

Examples:

$author()

A reviewpad.yml example:

rules:
  - name: isAuthoredByTechLead
    kind: patch
    description: Verifies if authored by tech lead
    spec: $author() == "john"

base

Description:

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

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

none

Return value:

string

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

Examples:

$base()

A reviewpad.yml example:

rules:
  - name: shouldNotifyTechLead
    kind: patch
    description: Verifies if pull request is going to be pulled into "features" branch
    spec: $base() == "features"

changed

Description:

This 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:

variable	type	description
`preFilePattern`	string	antecedent file pattern expression
`postFilePattern`	string	consequent file pattern expression

Return value:

boolean

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

Examples:

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

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

A reviewpad.yml example:

rules:
  - name: does-not-modify-tests
    kind: patch
    description: Does not modify test files
    spec: '!$changed("src/@1.java", "test/@1.java")'

commentCount

Description:

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

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

int

The total number of comments in the pull request.

Examples:

$commentCount()

A reviewpad.yml example:

rules:
  - name: hasNoComments
    kind: patch
    description: Verifies if it has no comments
    spec: $commentCount() == 0

comments

Description:

Returns the list of comment body of the pull request.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

[]string

The list of comment body of the pull request.

Examples:

$comments()

A reviewpad.yml example:

rules:
  - name: has-comments
    kind: patch
    description: Verifies if the issue/pull request has comments
    spec: $comments() != []

commitCount

Description:

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

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

int

The total number of commits in the pull request.

Examples:

$commitCount()

A reviewpad.yml example:

rules:
  - name: hasTooManyCommits
    kind: patch
    description: Verifies if it has than 3 commits
    spec: $commitCount() > 3

commits

Description:

Returns the list of commit messages of the pull request.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

[]string

The list of commit messages of the pull request.

Examples:

$commits()

A reviewpad.yml example:

rules:
  - name: has-initial-commit-in-commit-body
    kind: patch
    description: Verifies if any of the commit messages of the pull request is "inital commit"
    spec: $isElementOf("initial commit", $commits())

createdAt

Description:

Returns the time the pull request was created at.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

int64

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

Examples:

$createdAt()

A reviewpad.yml example:

rules:
  - name: wasCreatedOnApril
    kind: patch
    description: "Verifies if the pull request was created on the April 14th of 2011 at 16:00:49"
    spec: $createdAt() == "2011-04-14T16:00:49Z

description

Description:

Returns the description of the pull request.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

string

The description of the pull request.

Examples:

$description()

A reviewpad.yml example:

rules:
  - name: hasDescription
    kind: patch
    description: Verifies if the pull request description is "Testing description"
    spec: $description() == "Testing description"

fileCount

Description:

Returns the total number of files changed in the patch.

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

none

Return value:

int

The total number of files changed in the patch.

Examples:

$fileCount()

A reviewpad.yml example:

rules:
  - name: changesTooManyFiles
    kind: patch
    description: Verifies if it has than 3 files
    spec: $fileCount() > 3

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:

variable	type	description
`annotation`	string	annotation to look for in the patch

Return value:

boolean

Returns true if the patch changes a symbol with the provided annotation, false otherwise.

Examples:

$hasAnnotation("critical")

A reviewpad.yml example:

rules:
  - name: changesCritical
    kind: patch
    description: Verifies if changes critical code
    spec: $hasAnnotation("critical")

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:

variable	type	description
`queryPattern`	string	query pattern to look for on patch

Return value:

boolean

Returns true if the patch matches the code query, false otherwise.

Examples:

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

A reviewpad.yml example:

rules:
  - name: usesPlaceBet
    kind: patch
    description: Verifies if uses placeBet
    spec: $hasCodePattern("placeBet\(.*\)")

hasFileExtensions

Description:

Determines whether all the extensions of the changed files on 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:

variable	type	description
`extensions`	[]string	list of all file extensions

Return value:

boolean

Returns true if all file extensions in the patch are included in the list, false otherwise.

Examples:

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

A reviewpad.yml example:

rules:
  - name: changesAreOnlyTests
    kind: patch
    description: Verifies if changes are only on test files
    spec: $hasFileExtensions([".test.ts"])

hasFileName

Description:

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

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

variable	type	description
`filename`	string	filename to look for in the patch. case sensitive.

Return value:

boolean

Returns 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:

rules:
  - name: changesPlaceBet
    kind: patch
    description: Verifies if changes place bet file
    spec: $hasFileName("placeBet.js")

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:

variable	type	description
`filePattern`	string	file pattern glob to look for on patch

Return value:

boolean

Returns true if any of the files on patch matches the provided file pattern, false otherwise.

Examples:

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

A reviewpad.yml example:

rules:
  - name: changesTransactions
    kind: patch
    description: Verifies if changes transactions
    spec: $hasFilePattern("src/transactions/**")

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:

boolean

Returns true if it has a linear history. false otherwise.

Examples:

$hasLinearHistory()

A reviewpad.yml example:

rules:
  - name: hasLinearHistory
    kind: patch
    description: Verifies if the pull request has a linear history
    spec: $hasLinearHistory()

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:

boolean

Returns true if it has linked issues. false otherwise.

Examples:

$hasLinkedIssues()

A reviewpad.yml example:

rules:
  - name: hasLinkedIssues
    kind: patch
    description: Verifies if the pull request has linked issues
    spec: $hasLinkedIssues()

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:

boolean

A boolean which is true if the pull request has any review thread that is not resolved or outdated, false otherwise.

Examples:

$hasUnaddressedThreads()

A reviewpad.yml example:

rules:
  - name: requires-author-attention
    kind: patch
    description: Requires author to take action
    spec: $hasUnaddressedReviewThreads()

head

Description:

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

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

none

Return value:

string

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

Examples:

$head()

A reviewpad.yml example:

rules:
  - name: changesImplementedInDevelopmentBranch
    kind: patch
    description: Verifies if pull request changes are implemented in the "development" branch
    spec: $head() == "development"

isDraft

Description:

Verifies whether the pull request is 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:

boolean

A boolean which is true if the pull request is Draft, false otherwise.

Examples:

$isDraft()

A reviewpad.yml example:

rules:
  - name: isDraft
    kind: patch
    description: Verifies if is Draft
    spec: $isDraft()

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 of 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:

boolean

A boolean which is true if the pull request is waiting for review, false otherwise.

Examples:

$isWaitingForReview()

A reviewpad.yml example:

rules:
  - name: isWaitingForReview
    kind: patch
    description: Verifies if pull request is waiting for review
    spec: $isWaitingForReview()

labels

Description:

Returns the list of labels of the pull request.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

[]string

The list of labels of the pull request.

Examples:

$labels()

A reviewpad.yml example:

rules:
  - name: onlyHasTestLabelAssigned
    kind: patch
    description: Verifies if the pull request only has "test" label assigned
    spec: $labels() == ["test"]

lastEventAt

Description:

Returns the timestamp of the last event in the timeline.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

int64

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

Examples:

$lastEventAt()

A reviewpad.yml example:

rules:
  - name: check-if-inactive-for-a-month
    kind: patch
    description: Checks if the issue/pull request is inactive for a month
    spec: $lastEventAt() < 30 days ago

milestone

Description:

Returns the milestone title associated to the pull request.

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

none

Return value:

string

The milestone title associated to the pull request.

Examples:

$milestone()

A reviewpad.yml example:

rules:
  - name: isPartOfBugFixesMilestone
    kind: patch
    description: Verifies if the pull request is associated with the bug fixes milestone
    spec: $milestone() == "Bug fixes"

reviewers

Description:

Returns the list of GitHub user login or team slug that were requested to review the pull request.

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

none

Return value:

[]string

The list of GitHub user login or team slug that were requested to review the pull request.

Examples:

$reviewers()

A reviewpad.yml example:

rules:
  - name: hasReviewers
    kind: patch
    description: Verifies if the pull request has reviewers
    spec: $reviewers() != []

reviewerStatus

Description:

Returns the status of a reviewer in the pull request.

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

variable	type	description
`reviewerLogin`	string	the GitHub login of the reviewer

Return value:

string

The status of a reviewer. It can be one of four string values:

"", if there was no review from the reviewer;
"COMMENTED", if all the reviews from the reviewer were comments;
"CHANGES_REQUESTED", if the last review that was not a comment requested changes;
"APPROVED", if the last review that was not a comment requested changes;

Examples:

$reviewerStatus("marcelosousa")

A reviewpad.yml example:

rules:
  - name: approved-by-marcelosousa
    kind: patch
    description: Checks if the pull request was approved by marcelosousa
    spec: '$reviewerStatus("marcelosousa") == "APPROVED"'

size

Description:

Returns 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:

variable	type	description
`excludedPatterns` (optional)	[]string	file patterns to exclude from count

Return value:

int

The sum of all changed lines in the patch.

Examples:

$size()

A reviewpad.yml example:

rules:
  - name: isBigChange
    kind: patch
    description: Verifies if change is big
    spec: $size() > 100

title

Description:

Returns the title of the pull request.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

none

Return value:

string

The title of the pull request.

Examples:

$title()

A reviewpad.yml example:

rules:
  - name: hasTitle
    kind: patch
    description: Verifies if the pull request title is "Test custom built-ins"
    spec: $title() == "Test custom built-ins"

workflowStatus

Description:

Returns the status of a workflow run.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`workflowName`	string	The name of the workflow.

Return value:

string

The status of the workflow run.

Examples:

$workflowStatus("reviewpad")

A reviewpad.yml example:

rules:
  - name: reviewpad-successful
    kind: patch
    description: Verifies if reviewpad run was successful
    spec: '$workflowStatus("reviewpad") == "success"'

Organization

Set of functions to get organization details.

organization

Description:

Lists all the members of the organization that owns 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:

[]string

The list of all members of the organization to where the pull request running against.

Examples:

$organization()

A reviewpad.yml example:

rules:
  - name: isAuthorFromOrganization
    kind: patch
    description: Verifies if author belongs to organization
    spec: $isElementOf($author(), $organization())

team

Requires GitHub token

Please note that this function requires the Reviewpad Action to be installed with a GitHub token

Description:

Returns the members of a team and child teams.

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

⚠️ Requires GitHub token ⚠️

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

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

Please follow this link to know more

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`teamSlug`	string	The slug of the team name on GitHub.

Return value:

[]string

Returns the list of all team and child teams members GitHub login.

Examples:

$team("devops")

A reviewpad.yml example:

rules:
  - name: isAuthorByDevops
    description: Verifies if author belongs to devops team
    kind: patch
    spec: $isElementOf($author(), $team("devops"))

User

Set of functions to get user details.

issueCountBy

Description:

Returns 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:

variable	type	description
`userLogin`	string	the GitHub user login
`state` (optional)	string	the issue state (open, closed or all)

Passing the empty string "" to userLogin 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:

int

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

Examples:

$issueCountBy($author())

A reviewpad.yml example:

rules:
  - name: author-has-more-than-10-issues-open
    spec: $issueCountBy($author(), "open") > 10

pullRequestCountBy

Description:

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

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`userLogin`	string	the GitHub user login
`state` (optional)	string	the issue state (open, closed or all)

Passing the empty string "" to userLogin 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:

int

The total number of created pull requests created by the given GitHub user login with the state.

Examples:

$pullRequestCountBy($author())

A reviewpad.yml example:

rules:
  - name: repo-has-more-than-10-pr-open
    spec: $pullRequestCountBy("", "open") > 10

totalCreatedPullRequests

Description:

Returns 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:

variable	type	description
`userLogin`	string	the GitHub user login

Return value:

int

The total number of created pull requests created by GitHub user login.

Examples:

$totalCreatedPullRequests($author())

A reviewpad.yml example:

rules:
  - name: isJunior
    kind: patch
    description: Verifies if author is junior
    spec: $totalCreatedPullRequests($author()) < 3

Utilities

Set of functions to help handle the queried data.

append

Description:

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

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`slice`	[]string	slice that will have elements appended to it
`elements`	[]string	elements to be added to the end of the slice

Return value:

[]string

Returns a new slice by appending the slices passed to it.

Examples:

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

A reviewpad.yml example:

groups:
  - name: frontendAndBackendDevs
    description: Frontend and backend developers
    kind: developers
    spec: $append($team("frontend"), $team("backend"))

rules:
  - name: authoredByWebDeveloper
    kind: patch
    description: Authored by web developers
    spec: $isElementOf($author(), $group("frontendAndBackendDevs"))

contains

Description:

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

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`text`	string	The text to search in
`searchSentence`	string	The sentence to search for

Return value:

boolean

Returns 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:

rules:
  - name: hasCustomKeywordInTitle
    kind: patch
    description: Verifies if the pull request title has "custom" keyword
    spec: $contains($title(), "custom")

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:

variable	type	description
`searchElement`	literal	The value to search for
`list`	[]literal	The list to search in

Return value:

boolean

Returns true if searchElement is found within the list, false otherwise.

Examples:

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

A reviewpad.yml example:

rules:
  - name: authoredByJunior
    description: Verifies if author is junior
    kind: patch
    spec: $isElementOf($author(), $group("junior"))

length

Description:

Length returns the length of an array.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`array`	[]string	array of elements

Return value:

int

Returns the length of the array.

Examples:

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

A reviewpad.yml example:

rules:
  - name: has-at-least-one-reviewer
    kind: patch
    description: Has more than one reviewer
    spec: '$length($reviewers) > 1'

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:

variable	type	description
`text`	string	The text to search in
`prefix`	string	The prefix

Return value:

boolean

Returns 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:

rules:
  - name: isDevBranch
    kind: patch
    description: Verifies if the head branch of the pull requests starts with dev
    spec: $startsWith($head(), "dev/")

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 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:

variable	type	description
`groupName`	string	the group name to list the member from

Return value:

[]string

Returns all members from the group.

Examples:

$group("techLeads")

A reviewpad.yml example:

groups:
  - name: techLeads
    description: Group with all tech leads
    kind: developers
    spec: '["john", "maria", "arthur"]'

rules:
  - name: isAuthorByTechLead
    description: Verifies if author is a tech lead
    kind: patch
    spec: $isElementOf($author(), $group("techLeads"))

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:

variable	type	description
`ruleName`	string	the rule name

Return value:

bool

Returns the evaluation of the rule.

Examples:

$rule("isSmall")

A reviewpad.yml example:

rules:
  - name: isSmall
    description: Small pull request
    kind: patch
    spec: '$size() > 10'

  - name: isNotSmall
    description: Not a small pull request
    kind: patch
    spec: '!$rule(isSmall)'

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 name property of the label; if the property is not present, then it uses the key as the name.

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

Here's an example:

# ..
labels:
  small:
    name: "Small Change"
    description: Few files
  medium:
    description: Some files
# ...
workflows:
  - name: Add label
    if:
      - rule: is-small
        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:

variable	type	description
`name`	string	name of the label

Return value:

None.

Examples:

$addLabel("bug")

A reviewpad.yml example:

workflows:
  - name: label-small-pull-request
    description: Label small pull request
    if:
      - rule: isSmall
    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:

variable	type	description
`project name`	string	name of the project you want to attach the pull request
`status`	string	status of the pull request (must be present as a status )

Return value:

None.

Examples:

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

A reviewpad.yml example:

workflows:
  - name: add-to-project
    description: Add to project pull requests without linked issues
    if:
      - rule: '!$hasLinkedIssues()'
    then:
      - $addToProject("reviewpad test", "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. Assignees are silently ignored otherwise.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`assignees`	[]string	list of GitHub logins to assign the pull request to

Return value:

none

Examples:

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

A reviewpad.yml example:

workflows:
  - name: assign-to-author
    description: Assign pull request to author
    always-run: true
    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

Return value:

none

Examples:

$assignRandomReviewer()

A reviewpad.yml example:

workflows:
  - name: assign-random-reviewer
    description: Assign random reviewer
    if:
      - rule: tautology
    then:
      - $assignRandomReviewer()

assignReviewer

Description:

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

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:

variable	type	description
`reviewers`	[]string	list of GitHub logins to select from
`total` (optional)	int	total of reviewers to assign. by default assigns to all reviewers

Return value:

none

Examples:

$assignReviewer(["john", "marie", "peter"], 2)

A reviewpad.yml example:

workflows:
  - name: review-code-from-new-joiners
    description: Assign senior reviewers to PRs from new joiners
    if:
      - rule: authoredByJunior
    then:
      - $assignReviewer($group("seniors"), 2)

assignTeamReviewer

Description:

Assigns a list of teams to review the pull request.

Available for:

Type	Available
`issue`	❌
`pull_request`	✅

Parameters:

variable	type	description
`teamReviewers`	[]string	list of GitHub team slugs that will be requested to review

Return value:

none

Examples:

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

A reviewpad.yml example:

workflows:
  - name: review-core-code
    description: Assign review to core team when changes are made in critical code
    if:
      - rule: changesCritical
    then:
      - $assignTeamReviewer(["core"])

close

Description:

Closes an issue / pull request with a given comment.

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:

variable	type	description
`comment` (optional)	string	body of the comment

Return value:

none

Examples:

$close()

A reviewpad.yml example:

workflows:
  - name: close-pull-request
    description: Close pull request
    if:
      - rule: stalePullRequest
    then:
      - $close("Closing for inactivity.")

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:

workflows:
  - name: check-conventional-commits
    description: Check conventional commits
    if:
      - rule: tautology
    then:
      - $commitLint()

comment

Description:

Comments a pull request.

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

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`comment`	string	body of the comment

Return value:

none

Examples:

$comment("This pull request has git conflicts. Please resolve them.")

A reviewpad.yml example:

workflows:
  - name: conflict
    description: Ask to resolve conflict
    if:
      - rule: hasConflicts
    then:
      - $comment("This pull request has git conflicts. Please resolve them.")

commentOnce

Description:

Comments a pull request once.

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

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`comment`	string	body of the comment

Return value:

none

Examples:

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

A reviewpad.yml example:

workflows:
  - name: comment-pull-request
    description: Comment pull request
    if:
      - rule: firstContribution
    then:
      - $commentOnce("This is your first contribution! Thank you!")

disableActions

Description:

Disables the list of actions passed as argument.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`actions`	[]string	the list of actions to be disabled

Examples:

$disableActions(["assignReviewer"])

A reviewpad.yml example:

workflows:
  - name: reviewer-assignment-config
    if:
      - rule: is-draft
    then:
      - '$disableActions(["assignReviewer", "assignTeamReviewer", "assignRandomReviewer"])'

error

Description:

Add a message to the errors section of the report.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`comment`	string	comment to be added in the errors

Examples:

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

A reviewpad.yml example:

workflows:
  - name: error-large-pull-requests
    description: Error about large pull requests
    if:
      - rule: isLarge
    then:
      - $error("This pull request was considered 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:

variable	type	description
`failMessage`	string	fail message

Return value:

none

Examples:

$fail("please review the missing specs")

A reviewpad.yml example:

workflows:
  - name: fail-on-missing-specs
    description: Fails the action on missing specs
    if:
      - rule: missingSpecs
    then:
      - $fail("Please add specs for your change.")

info

Description:

Add a message to the info section of the report.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`comment`	string	comment to be added in the informations

Examples:

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

A reviewpad.yml example:

workflows:
  - name: info-large-pull-requests
    description: Info about large pull requests
    if:
      - rule: isLarge
    then:
      - $info("This pull request was considered too large.")

merge

Requires GitHub token

Please note that this function requires the Reviewpad Action to be installed with a GitHub token

Description:

Merge 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:

variable	type	description
`method`	string	merge method (merge, rebase or squash)

Return value:

none

Examples:

$merge()

A reviewpad.yml example:

workflows:
  - name: auto-merge-small-pull-request
    description: Auto-merge small pull request
    if:
      - rule: isSmall
    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.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`name`	string	name of the label

Return value:

Error if the label does not exist in the repository.

Examples:

$removeLabel("bug")

A reviewpad.yml example:

workflows:
  - name: remove-size-small
    if:
      - rule: $size() > 10
        extra-actions:
          - $removeLabel("small")

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:

workflows:
  - name: pr-title-lint
    description: Lint PR title with conventional commits
    always-run: true
    if:
      - 'true'
    then:
      - $titleLint()

warn

Description:

Add a message to the warnings section of the report.

Available for:

Type	Available
`issue`	✅
`pull_request`	✅

Parameters:

variable	type	description
`comment`	string	comment to be added in the warnings

Examples:

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

A reviewpad.yml example:

workflows:
  - name: warn-large-pull-requests
    description: Warn about large pull requests
    if:
      - rule: isLarge
    then:
      - $warn("This pull request was considered too large.")

Functions​

Pull Request​

assignees​

author​

base​

changed​

commentCount​

comments​

commitCount​

commits​

createdAt​

description​

fileCount​

hasAnnotation​

hasCodePattern​

hasFileExtensions​

hasFileName​

hasFilePattern​

hasLinearHistory​

hasLinkedIssues​

hasUnaddressedThreads​

head​

isDraft​

isWaitingForReview​

labels​

lastEventAt​

milestone​

reviewers​

reviewerStatus​

size​

title​

workflowStatus​

Organization​

organization​

team​

User​

issueCountBy​

pullRequestCountBy​

totalCreatedPullRequests​

Utilities​

append​

contains​

isElementOf​

length​

startsWith​

Engine​

group​

rule​

Actions​

addLabel​

addToProject​

assignAssignees​

assignRandomReviewer​

assignReviewer​

assignTeamReviewer​

close​

commitLint​

comment​

commentOnce​

disableActions​

error​

fail​

info​

merge​

removeLabel​

titleLint​

warn​

Functions

Pull Request

assignees

author

base

changed

commentCount

comments

commitCount

commits

createdAt

description

fileCount

hasAnnotation

hasCodePattern

hasFileExtensions

hasFileName

hasFilePattern

hasLinearHistory

hasLinkedIssues

hasUnaddressedThreads

head

isDraft

isWaitingForReview

labels

lastEventAt

milestone

reviewers

reviewerStatus

size

title

workflowStatus

Organization

organization

team

User

issueCountBy

pullRequestCountBy

totalCreatedPullRequests

Utilities

append

contains

isElementOf

length

startsWith

Engine

group

rule

Actions

addLabel

addToProject

assignAssignees

assignRandomReviewer

assignReviewer

assignTeamReviewer

close

commitLint

comment

commentOnce

disableActions

error

fail

info

merge

removeLabel

titleLint

warn