Product GuideChangelogCommunity DiscordDiscussionsBlogGitHub
Log In

Reviewpad Syntax

Suggest Edits

A Reviewpad configuration file has the following shape:

api-version: reviewpad.com/v2.x

edition: EDITION
mode: MODE

labels:
 label_1
 label_2
 ...
 label_N

groups:
  group_1
  group_2
  ...
  group_N

rules:
  rule_1
  rule_2
  ...
  rule_N

workflows:
  - workflow_1
  - workflow_2
  ...
  - workflow_N

You can see the latest formal version of the format here.

If you use VSCode, we recommend that you setup yaml.schemas to enjoy syntax checking and auto-completion.

The central concept in this specification is the workflow.

A workflow is a specification of a list of actions to be executed if the pull request satisfies any of the rules in its specification.

Example. Automated labelling of pull requests

Consider the following reviewpad.yml:

api-version: reviewpad.com/v2.x

labels:
  small:
    color: "f15d22"
    description: Pull requests with less than 90 LOC

rules:
  - name: isSmallPatch
     kind: patch
     description: Patch has less than 90 LOC
     spec: $size() < 90

workflow:
  - name: labelSmall
    description: Label small pull requests
    if:
      - rule: isSmallPatch
    then:
      - $addLabel("small")

This configuration file specifies one workflow called labelSmall which automatically labels a pull request with small if it changes less than 90 lines of code.

API Version

The api-version is the version of Reviewpad specification format. The version is necessary so the the format can be evolved, and the field is used for the parser to know how to interpret the content.

Edition

The edition is a flag that allows you to access different capabilities of Reviewpad. We currently support the team and professional editions. The difference is that team edition is completely open-source and the professional edition contains closed sourced code for certain built-ins. At the moment, they are both free so we recommend the use of the professional edition by default.

Mode

The mode is a flag that allows you to enable or disable a report of Reviewpad as a pull request comment. By default, Reviewpad runs on silent mode. However, you can choose to use verbose mode and Reviewpad will comment on the pull request with the execution results.

Label

A label specifies a label that can be used as an argument to the label related functions.

The structure of a label is as follows:

LABEL-NAME:
  description: STRING [OPTIONAL]
  color: STRING [OPTIONAL]
  • name of a label is used to reference it in other entities.
  • description is a short description of the label. Must be 100 characters or fewer.
  • color is the hexadecimal color code for the label, without the leading #.

If the label does not exist in the repository, it will be created. If it already exists in the repository, no action will be taken.

Group

A group specifies a list of entities. At the moment, we only support GitHub users.

There are two ways to specify a group:

Group By Enumeration

- name: STRING
   description: STRING
   kind: developers
   spec: '[LIST OF GITHUB USERS]'
  • name of a group is used to reference it in other entities.
  • kind of a group can only be developers at the moment.
  • description is a string that can be used to provide more details about the group.
  • spec is an Aladino array.

Example. Group by Enumeration 

- name: groupWithMarcelo
   description: The group composed of marcelosousa
   kind: developers
   spec: '["marcelosousa"]'

Group By Filter

- name: STRING
   description: STRING
   kind: developers
   type: filter
   param: VARIABLE
   spec: ALADINO-BOOLEAN-EXPRESSION
  • name of a group is used to reference it in other entities.
  • kind of a group can only be developers at the moment.
  • type with filter specifies that we will require a param and a boolean spec.
  • param declares the name of a variable representing a single developer.
  • spec is an Aladino boolean expression that uses the param variable to define a condition on which developers should be part of the group.

Example. Group by Filter 

- name: newJoiners
   description: Group of devs that have created less than 10 PRs
   kind: developers
   type: filter
   param: dev
   where: $totalCreatedPRs($dev) < 10

Rule

A Reviewpad rule specifies a boolean condition on a pull request.

The structure of a rule is as follows:

- name: STRING
   kind: [patch | author]
   description: STRING
   spec: ALADINO-BOOLEAN-EXPRESSION
  • name of a rule is used to reference it in other rules and workflow.
  • kind of a rule can be either patch or author. The kind is related to different properties of pull requests that will be used in the evaluation of the spec field.
  • description is a string that can be used to provide more details about the rule.
  • spec is a boolean expression in Aladino.

Workflow

The structure of a workflow is as follows:

- name: STRING
  description: STRING
  always-run: BOOLEAN
  if:
    - rule: REF_TO_RULE_1
      extra-actions: [OPTIONAL]
        - ACTION_1
        - ACTION_2
        ...
        - ACTION_N
    ...
    - rule: REF_TO_RULE_N
  then: [OPTIONAL]
    - ACTION_1
    - ACTION_2
    ...
    - ACTION_N
  • name is a string that identifies the workflow.
  • description is a string that can be used to provide more details about the rule.
  • always-run field is a boolean that specifies the workflow should always be checked or not. By default, this value is false.
  • if field specifies which rules should be checked. For each rule, we can also specify a list of extra actions that will be executed if this rule is activated by the pull request.
  • then field is a list of Aladino actions that should run.

Updated 12 days ago

Did this page help you?