If you have any questions, feedback, or issues please let us know via GitHub Issues or by using Intercom on pullapprove.com.

Migrating from v1 to v2

Below are the changes between the original .pullapprove.yml implementation and the new "v2".

Migrating to the new settings should be straightforward, with a few minor changes you'll be ready to take full advantage of the new features and flexiblity they provide.


The key difference

In v1, you essentially reviewed a PR once, no matter how many review groups you were a part of. Now either via pullapprove.com or via GitHub PR comments (by putting a different approve_regex on each group) you can make your approvals one at a time.

Additionally, all of the PullApprove settings from before can now be specified at the group level, allowing you to determine exactly what kind of behavior each group has (when approval are reset, how they are triggered, what rejection means, etc.).


How to migrate

If you're using templates:

Exactly how you migrate is up to you, depending on whether you can afford any "downtime" (where PR's may get an error status). If you can, just change you template to the new v2 then update each .pullapprove.yml to do the same.

If you'd like to avoid any time where your settings are invalid, you just need to take a couple additional steps. We suggest creating a new template, with a different name and the settings written in v2. Then go through each repo using the original (there will be a list next to the template on pullapprove.com) and update it to use the new template and specify version: 2. If you do this step through a PR, we'll let you know if there is an error in your configuration. Once all of your .pullapprove.yml files are updated, you can safely delete your old v1 template.

If you're not using templates:

Easy! Just open a PR that modifies .pullapprove.yml to the new configuration. Our status check will see that you're changing your settings and ensure that the proposed configuration is valid. Merge it in and you're ready to go!


.pullapprove.yml changes

  • You must specify version: 2, otherwise it will use the original "v1" settings by default.
    version: 2
    ...
  • The reviewers setting has been renamed to groups.
    # version: 1 (by default)
    reviewers:
      ...
    version: 2
    groups:
      ...
  • When naming reviewer groups, the name is now the key instead of having a name: admins setting.
    # version: 1 (by default)
    reviewers:
      -
        name: admins
        ...
    version: 2
    groups:
      admins:
        ...
  • members has been renamed to users. This, along with the original teams now more closely matches GitHub terminology, since that's what you're specifying.
    # version: 1 (by default)
    reviewers:
      -
        name: admins
        members:
          - usernameone
          - usernametwo
        ...
    version: 2
    groups:
      admins:
        users:
          - usernameone
          - usernametwo
  • signed_off_by is now nested under requirements
  • All conditions (files, branches, labels) now support either a list or specific include and/or exclude lists. For example, if the files excluding x still includes y, then the group should review it. More details here.
  • All of the v1 settings (aside from signed_off_by) can now be applied at a group-level. Meaning each group can have their own approve_regex, reset_on_push, etc. giving you much more flexiblity over each group's review flow.
  • Some settings which previously just took a true or false value, now use enabled: true/false to allow for more flexibility going forward. Affected are reset_on_push, reset_on_reopened.

YAML template changes

  • Both the template and .pullapprove.yml must specify version: 2
  • When extending templates, dictionary-like objects will now merge as opposed to override.
    ### "example" template
    version: 2
    groups:
      admins:
        users: all
        required: 3
    
    ### .pullapprove.yml
    version: 2
    extends: example
    groups:
      admins:
        required: 1
        # "users: all" will be kept from the template