New draft and undraft actions

Pull requests are an essential part of the GitHub workflow. While they are mainly used as a way to merge your code into the base branch, it is not their only purpose.

What if you wanted to create a prototype of a feature you would like to implement, just to discuss the idea? 🤔

In this case, you wouldn't want your code to be merged yet since it would be more of an idea than an actual piece of functional code.

There is a way to do that with pull requests: drafts.

What is a draft pull request?

The main purpose of a draft is to block the merger and a signal for your collaborators that the pull request is not fully ready.

Because your pull request might just be a proof-of-concept, you may want to prevent your code to be included in the target branch. Or maybe you want your CI to not run the tests until the pull request is marked as ready for review; you could configure your CI to ignore draft pull requests and save CI time.

Since it is pretty easy to tell if a pull request is a draft with the GitHub API, you could use this feature for any other reason that might fit your needs.

However, if you were to use this feature, you would quickly notice something: it is quite tedious to go back and forth from your code and to the pull request page to change its state.

This is where this new edit action from Mergify becomes useful.

Automatically draft and undraft pull requests

Mergify can now mark a pull request as a draft or as ready for review with a simple boolean, instead of using the GitHub UI.

That is handy compared to GitHub UI design which does not make these actions obvious; look at the tiny button located at the top of the page, or at the button to reverse it at the very bottom of the page (quite far away when you have commented a lot on your pull request).

Even better: you can use any of the Mergify conditions to change the pull request state.

For example, you could automatically convert the pull request to a draft if a draft label exists or mark the pull request as ready to review if there is no conflict with the base branch. You could even use time-based conditions.

How to set this up

All you have to do is to write the conditions and actions in your configuration file using the edit action.

If you want your pull request to become a draft or the opposite, you could write a rule like this:

pull_request_rules:
  -  name: convert pull requests to draft if they have a draft label
     conditions:
       - label=draft
     actions:
       edit:
         draft: true

or like this:

pull_request_rules:
  -  name: mark PR as a draft when they have no review request and CI fails
     conditions:
       -  "#check-failure>=1"
       -  "#review-requested=0"
     actions:
       edit:
         draft: true

Try it yourself! 🚀

Upcoming edit parameters

The idea behind the edit action is that it will be possible to edit other parts of the pull request in the future: for example, the body and the title. Stay tuned for upcoming changes and features on this action!