Version: v4

YAML Syntax

A Reviewpad configuration file has the following shape:

metrics-on-merge: true | false

extends:
  - configuration_1
  - configuration_2
  ...
  - configuration_N

labels:
  label_1
  label_2
  ...
  label_N

groups:
  - group_1
  - group_2
  ...
  - group_N

dictionaries:
  - dictionary_1
  - dictionary_2
  ...
  - dictionary_N

rules:
  - rule_1
  - rule_2
  ...
  - rule_N

workflows:
  - workflow_1
  - workflow_2
  ...
  - workflow_N

checks:
  check_1
  check_2
  ...
  check_N

note

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

Metrics on merge

The metrics-on-merge property is a boolean flag that determines whether or not a metrics report should be added when a pull request is merged.

This property is optional and can be set to either true or false.

By default, this flag is set to false, so a report will not be added.

If the flag is set to true, the metrics report will include the following information:

Coding Time: the duration between the first commit and the issuance of the pull request;
Pickup Time: the duration between the issuance of the pull request and its first review;
Review Time: the duration between the first review and the merge of the pull request.

Reviewpad metrics report

Example

metrics-on-merge: true

Extends

The extends property allows you to extend other Reviewpad configurations by using their GitHub blob URLs (for example, https://github.com/reviewpad/reviewpad/blob/main/reviewpad.yml).

This property is optional and can be set to a list of GitHub blob URLs.

Note that if the URL isn't a GitHub blob, an error will occur.

For more information on the extends mechanism, please visit this page.

Example

extends:
  - https://github.com/reviewpad/.github/blob/main/reviewpad-models/common.yml

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-ID:
  name: STRING [OPTIONAL]
  description: STRING [OPTIONAL]
  color: STRING [OPTIONAL]

LABEL-ID is used to reference the label in other entities, and if no name is provided, the LABEL-ID is considered the name.
name [OPTIONAL] is the name of the label as seen on GitHub.
description [OPTIONAL] is a short description of the label. Must be 100 characters or fewer.
color [OPTIONAL] is the hexadecimal color code for the label, with or without the leading #.

If the label does not exist in the repository, it will be created.

If the label already exists in the repository and the description or the color is set in the reviewpad.yml file, then both the description and the color will be updated based on the reviewpad.yml file.

Example

labels:
  small:
    name: small # optional
    description: Defines a small pull request # optional
    color: d2697a # optional

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 [OPTIONAL]
  kind: developers [OPTIONAL]
  spec: "[LIST OF GITHUB USERS]"

name of a group is used to reference it in other entities.
description [OPTIONAL] is a string that can be used to provide more details about the group.
kind [OPTIONAL] of group can only be developers at the moment.
spec is an array of Aladino specifications.

Example

groups:
  - name: seniors
    description: project seniors # optional
    kind: developers # optional
    spec: '["peter"]'

Group by filter

- name: STRING
  description: STRING [OPTIONAL]
  kind: developers
  type: filter
  param: VARIABLE-NAME
  where: ALADINO-BOOLEAN-EXPRESSION

name of a group is used to reference it in other entities.
description [OPTIONAL] is a string that can be used to provide more details about the group.
kind of 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.
where is an Aladino boolean expression that uses the param variable to define a condition on which developers should be part of the group.

Example

groups:
  - name: new-joiners
    description: Groups of developers that have created less than 10 pull requests # optional
    kind: developers
    type: filter
    param: dev
    where: $countUserPullRequests($dev) < 10

Dictionary

A dictionary represents a structured list of key/value pairs, specified as follows:

- name: STRING
  description: STRING [OPTIONAL]
  spec:
    key1: value1
    key2: value2
    ...
    keyn: valuen

name of a dictionary is used to reference it in other entities.
description [OPTIONAL] is a string that can be used to provide more details about the dictionary.
spec is a list of YAML key/value pairs. Each key and value should be enclosed in single quotes, and the value should be an Aladino expression, typically either a string or an array.

Example with Aladino string values

dictionaries:
  - name: label-per-file-path
    description: Labels to apply based on the path of the touched files # optional
    spec:
      '**/authentication/**': '"authentication"'
      '**/order/**': '"order"'
      '**/api/**': '"api"'
      'LICENSE': '"license"'
      '.github/workflow/**': '"ops"'

note

When using Aladino string values in dictionaries, ensure values are enclosed in both double quotes and single quotes..

Example with Aladino array values

dictionaries:
  - name: reviewing-teams-per-file-path
    description: Teams to involve in the review process based on the path of the touched files # optional
    spec:
      '**/authentication/**': '["security-team", "developers"]'
      '**/db/**': '["dba-team", "developers"]'
      '.github/workflow/**': '["devops-team"]'

Rule

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

The structure of a rule is as follows:

- name: STRING
  kind: [patch | author] [OPTIONAL]
  description: STRING [OPTIONAL]
  spec: ALADINO-BOOLEAN-EXPRESSION

name of a rule is used to reference it in other rules and workflows.
kind [OPTIONAL] 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 [OPTIONAL] is a string that can be used to provide more details about the rule.
spec is a boolean expression in Aladino.

Example

rules:
  - name: small-change
    kind: patch # optional
    description: Checks if the pull request size is small # optional
    spec: $getSize() < 30

Workflow

A workflow is a specification of a list of actions to be executed if the pull request / issues satisfies any of the specified rules.

The structure of a workflow is as follows:

- name: STRING
  description: STRING [OPTIONAL]
  on:
    - [pull_request | issue] [OPTIONAL]
  trigger-on-check: CHECK_ID [OPTIONAL]
  run:
    - ACTION_1
    ...
    - if: REF_TO_RULE_1 | INLINE_RULE_1
      then: ACTION_2
      else: ALTERNATIVE_ACTION_2
    ...
    - forEach:
        key: KEY_IDENTIFIER [ONLY WITH DICTIONARY]
        value: VALUE_IDENTIFIER
        in: REF_TO_GROUP | REF_TO_DICTIONARY
        do: ACTION_3
    ...
    - ACTION_N

name is a string that identifies the workflows.
description [OPTIONAL] is a string that can be used to provide more details about the workflow.
on [OPTIONAL] field is a list of GitHub entity types that should trigger the workflow. By default, the value is pull_request.
trigger-on-check [OPTIONAL] field designates the unique ID of a check from the available checks. The workflow will only be triggered when an issue is identified by the designated check.
run field specifies the action or the list of actions to be executed in the workflow:
- if field specifies the condition that should be satisfied for the then field to run. The if field can be a reference to a rule by its name or an inline rule.
- then field defines the Reviewpad action or the list of Reviewpad actions to run when if evaluates to true.
- else field defines the Reviewpad action or the list of Reviewpad actions to run when if evaluates to false. This field is optional.
- forEach field initiates a loop over either a group or a dictionary, as defined in the in field.
  - key field specifies the Aladino identifer that can used within the nested Reviewpad actions to access the key of the current key/value pair. This field should be specified only when iterating over a dictionary.
  - value field specifies the Aladino identifer that can used withing the nested Reviewpad actions to access to value of the current element.
  - in field specifies the reference to the group or dictionary over which iteration occurs.
  - do field defines the Reviewpad action or the list of Reviewpad actions to be executed for each element of the group or dictionary.

`run`

The run field can be a single action or a list of actions. An action is an Aladino expression to be executed.

We can also use the:

the if ... then ... else conditional actions to specify a list of actions to run depending on the evaluation of the if field.
the forEach ... key ... value ... in ... do loop structure to iterate over a list of elements withing a group or dictionary, defining a list of actions to perform on each individual element.

Single action

workflows:
  - name: label
    run: $addLabel("bug")

List of actions

workflows:
  - name: label
    run:
      - $addLabel("bug")
      - $addLabel("documentation")

Conditional actions

workflows:
  - name: label
    run:
      - $addLabel("bug")
      - $addLabel("documentation")
      - if: $getSize() < 100
        then: $addLabel("small")
        else: $addLabel("large")

The above configuration specifies one workflow called label which automatically labels pull requests with bug and documentation labels. If the pull request size is less than 100 then the small label is added. Otherwise, a large label is added.

For a pull request with size 150, the labels bug, documentation, and medium will be added.

Nested conditional actions

We can also nest conditional actions by using the then and else fields.

workflows:
  - name: label
    run:
      - $addLabel("bug")
      - $addLabel("documentation")
      - if: $getSize() < 100
        then: $addLabel("small")
        else:
          - if: $getSize() < 500
            then: $addLabel("medium")
            else: $addLabel("large")

In the above example, for a pull request with size 150, the labels bug, documentation, and medium will be added.

It is also important to note both the then and else fields can have a single action or a list of actions.

Example

workflows:
  - name: label
    run:
      - $addLabel("bug")
      - $addLabel("documentation")
      - if: $getSize() < 100
        then:
          # Run a list of actions
          - $addLabel("small")
          - $reportInfo("The pull request size is small")
        else:
          # Run a list of actions
          - $addLabel("large")
          - if: $getSize() > 500
            # Run a single action
            then: $reportInfo("The pull request size is very large")
          - $addReviewerRandomly()

Loop over a group

groups:
  - name: teams
    spec: '["team1", "team2", "team3"]'

workflows:
  - name: assign to the team of the author for review
    run:
      - if: '!$isDraft()'
        then:
          - forEach:
              value: $getTeamMembers
              in: $group("teams")
              do:
                - if: $isElementOf($getAuthor(), $getTeamMembers($getTeamMembers))
                  then:
                    - $addLabel($getTeamMembers)
                    - $addTeamsForReview([$getTeamMembers])

The above configuration outlines a workflow that automatically assigns a pull request for review, selecting a reviewer from the same team as the author of the pull request. Concurrently, it applies the team's label.

Loop over a dictionary

dictionaries:
  - name: approval-team-per-file-path
    spec:
      '**/authentication/**': '"security"'
      '**/db/**': '"dba"'
      '.github/workflows/**': '"devops"'

workflows:
  - name: assign for review based on touched files
    run:
      - if: '!$isDraft()'
        then:
          - forEach:
              key: $filePattern
              value: $getTeamMembers
              in: $dictionary("approval-team-per-file-path")
              do:
                - if: $containsFilePattern($filePattern)
                  then:
                    - $addTeamsForReview([$getTeamMembers])

The above configuration outlines a workflow that automatically assigns pull requests for review to certain teams based on the part of the code that has been modified:

When database migration scripts are modified, the workflow involves the DBA team.
When the authentication layer is modified, the workflow involves the Security team.
When GitHub workflows configuration is modified, the workflow involves the OPS team.

Checks

A check is as a sensor, identifying specific open Pull Requests that might necessitate extra scrutiny. Explore our list of available checks.

The structure of a check is as follows:

CHECK_ID:
  parameters: [OPTIONAL]
    PARAMETER_1-ID: [OPTIONAL] #see check description
    PARAMETER_2-ID: [OPTIONAL] #see check description
    ...
    PARAMETER_N-ID: [OPTIONAL] #see check description
  label: STRING [OPTIONAL]
  activation: on|off [OPTIONAL]

CHECK_ID is the unique ID of the check. See the list of checks.
parameters [OPTIONAL] to configure the available parameters for the check.
label: [OPTIONAL] to specify the label to put on the pull request when an issue is found by the check.
activation [OPTIONAL] is the activation status of the check. This status can be either on or off.

Example

checks:
  stale:
    parameters:
      max-idle-days: 30
    label: stale
    activation: on

VSCode Reviewpad YAML schema

To minimize errors when editing Reviewpad files, you can set up the reviewpad.yml schema on VSCode.

You just need to download the latest JSON schema from schemas/reviewpad and add the following settings to your VSCode workspace:

{
    // Associate Reviewpad schema to reviewpad.(yml|yaml) files
    "yaml.schemas": {
        "https://raw.githubusercontent.com/reviewpad/schemas/main/latest/schema.json": [
            "reviewpad.yml",
            "reviewpad.yaml",
        ]
    },
}

Now, when you are editing you will be able to check if your Reviewpad file is syntactically correct, access the documentation and get auto-completion of certain fields.

Metrics on merge​

Extends​

Label​

Group​

Dictionary​

Rule​

Workflow​

run​

Single action​

List of actions​

Conditional actions​

Nested conditional actions​

Loop over a group​

Loop over a dictionary​

Checks​

VSCode Reviewpad YAML schema​

Metrics on merge

Extends

Label

Group

Dictionary

Rule

Workflow

`run`

Single action

List of actions

Conditional actions

Nested conditional actions

Loop over a group

Loop over a dictionary

Checks

VSCode Reviewpad YAML schema