A draft pull request: showing work early

A draft pull request is the same pull request, only flagged as not ready to merge. GitHub disables the merge button on it, and in return you get a way to show direction before the work is finished.

Why open one early

The point of a draft is to get feedback on the approach before you have spent a day on it. You have a skeleton, a first migration, a rough interface - you open a draft, and a colleague can say "wrong table" before you have built twelve more files on top of it. Without a draft the choice is thinner: either sit silent in your branch for a day, or open a normal pull request and call people in on something half-done. A finished pull request asks to be read in full; a draft says "check whether I am heading the right way", and those are different requests.

How to open one as a draft

You push the branch to the server as usual, git sees no difference. The draft is chosen on the site: the Create pull request button has a dropdown, and in it is Create draft pull request. From the terminal the GitHub CLI does the same:

$ gh pr create --draft

A grey Draft label appears on the page, and the merge button stays disabled.

What changes

A draft does not ping the required reviewers (the ones CODEOWNERS or branch protection assign): GitHub does not request their review and sends no notification while the pull request is a draft. A formal review is not spent on a half-built thing, and nobody gets a "please review" mail about code that will be rewritten tomorrow.

Reading and commenting on a draft is not blocked. The diff is open, line comments are left as on any pull request - the only difference is that no review is formally requested and the merge is locked.

The automation usually runs as always: the build and the tests run on every commit, and you see green or red as you go. Turning that off takes an explicit setting, when the workflow is configured to run only on ready pull requests (the ready_for_review event).

How to mark it ready

When the work is done, the page has a Ready for review button, and the terminal has gh pr ready. At that moment GitHub requests review from the required reviewers and lifts the lock on merging. The reverse is there too: a ready pull request can be turned back into a draft with Convert to draft.

Common mistakes

A draft is not private. Everyone with access to the repository sees it; it is a way to mark readiness, not to hide code from other eyes.

A draft left in draft state never gets its review. Nothing has called the reviewers, and they wait for a signal that never comes. Once it is done, mark it Ready for review, or the finished work just hangs there without a single comment.

Where this is in the book

Chapter 7. How teams actually use git. What a pull request is in full is in the pull request article.