Improving your users’ onboarding: the case of Amazon CDK

As time passes, we keep seeing new and fancy ways of using Mergify to do other things than just merging pull requests.

Today I’d like to dig into how Amazon Web Services Cloud Development Kit project leverages Mergify to help its contributors.

About AWS CDK

To get a good understanding of what we’re talking about here, AWS CDK is an open-source software development framework to define cloud infrastructure in code and provision it through AWS CloudFormation. It’s a library that developers can use to deploy their infrastructure on top of Amazon Web Services.

The fact that it is open-source and available on GitHub makes it easy for its users to contribute their changes. The development team behind AWS CDK gets a few pull requests every day from external contributors — people that do not work at Amazon but are just using the service.

Getting external contributors is essential. It allows you to get a better understanding of what your users are doing with your software, and make sure they feel included in the development of the solution.

How AWS CDK uses Mergify

AWS CDK has a good pace and merges between 5 and 10 pull requests every day. They use Mergify for a wide variety of actions.

Labelling Pull Requests

To get organized, AWS CDK uses a rule named label core which label any pull request authored by a core member with a contribution/core label.

- name: label core
    actions:
      label:
        add: [ contribution/core ]
    conditions:
      - author~=^(eladb|RomainMuller|garnaat|nija-at|shivlaks|skinny85|rix0rrr|NGL321|Jerry-AWS|SomayaB)$
      - -label~="contribution/core"

This is an excellent way to categorize your issues at a glance. Note that they could also use a GitHub team to match this rather than listing people manually — whatever works.

Automatic Merge

That’s the rule everybody loves, and CDK is not an exception. What we like in this project flow, is that they also make Mergify make a gentle comment to indicate they the PR is going to be merged.

Their conditions are pretty standard, and they merge only pull requests that have been approved by at least one repository member and when there are no changes requested on the reviews. They also filter out based on labels to not merge pull requests labeled as WIP or do-not-merge.

- name: automatic merge
    actions:
      comment:
        message: Thank you for contributing! Your pull request is now being automatically merged.
      merge:
        strict: smart
        method: squash
        strict_method: merge
      delete_head_branch: {}
    conditions:
      - -title~=(WIP|wip)
      - -label~=(blocked|do-not-merge)
      - -merged
      - -closed
      - "#approved-reviews-by>=1"
      - "#changes-requested-reviews-by=0"
      - status-success~=AWS CodeBuild us-east-1
      - status-success=Semantic Pull Request

The CDK project likes a tidy repository, so they also use delete_head_branch to delete the pull request branch once it’s merged.

Comment Checklist

To ease contributors onboarding, they send a comment to each new pull request that is not authored by one of the bots they use (Dependabot in this case). It contains a list of things to check for your pull request to be merged.

This is rather easy to do with the comment action.

Hinting on CI failure

When one of their CI jobs fails, CDK sends a comment to help their contributors fixing their pull request.

- name: if fails conventional commits
    actions:
      comment:
        message: Title does not follow the guidelines of [Conventional Commits](https://www.conventionalcommits.org). Please adjust title before merge.
    conditions:
      - author!=dependabot[bot]
      - author!=dependabot-preview[bot]
      - status-failure=Semantic Pull Request
      - -merged
      - -closed

In this case, they want the pull request title to follow Conventional Commits. If a contributor never heard of this, it’s great to give them a hint about what conventional commits are and how to fix their PR!

Removing Stale Reviews

When a pull request gets updated, it’s always a good idea to remove its “review” status. That way, you’re sure that an approval is not kept around for code that has been modified.

- name: remove stale reviews
    actions:
      dismiss_reviews: {}
    conditions:
      - author!=dependabot[bot]
      - author!=dependabot-preview[bot]
        # List out all the people whose work is okay to provisionally approve
      - author!=eladb
      - author!=RomainMuller
      - author!=garnaat
      - author!=nija-at
      - author!=shivlaks
      - author!=skinny85
      - author!=rix0rrr
      - author!=NGL321
      - author!=Jerry-AWS
      - author!=SomayaB
      - base=master
      - -merged
      - -closed

AWS CDK is smartly doing this, as they’re keeping reviews status for some of their core members. That way, you know there’s no way to re-approve a pull request is one of the members you already trust is just fixing a typo!

Conclusion

It’s fantastic to see how open source projects can leverage Mergify to streamline their development process. We’re always curious to see how creative people get with their rules, so feel free to share yours!