A draft PR is a regular pull request in a special state. It exists on the server, is visible to everyone, and CI runs on it. GitHub knows the author is still working, so it:
- Does not assign reviewers automatically (via CODEOWNERS).
- Does not send a "requested your review" notification.
- Blocks merge until the PR is marked ready.
This formalizes the old practice of prefixing PR titles with "WIP." Draft does the same thing, but GitHub enforces the rules.
When to use a draft
- To get feedback on an early prototype. Open a draft, drop the link in chat: "here's a rough draft, take a look at the approach, ignore the details." Reviewers understand it is not final.
- To run CI before you consider the PR ready. Sometimes you need to see green or red from the test suite before asking colleagues to review. Draft lets you do that without the noise.
- To make work visible to the team. The team can see you are working on something, drop in to discuss, but no one is called to review right now.
- Stacked PRs. Dependent PRs are often opened as drafts and marked ready one by one as the base PR is merged.
Creating a draft
bash
# via gh
gh pr create --draft
# or via UI: when creating a PR, click the dropdown next to
# "Create pull request" and choose "Create draft pull request"
Marking ready
bash
gh pr ready # current PR (on the current branch)
gh pr ready 123 # a specific PR by number
Or click "Ready for review" in the UI. After that:
- CODEOWNERS assigns reviewers.
- Reviewers receive a notification.
- Merge becomes possible (when all other conditions are met).
The reverse is also available:
bash
gh pr ready --undo
Useful if you marked it ready too soon.
Pitfalls
- Draft does not mean private. The PR is visible to everyone who can see the repo. For private work, use a private branch or a private fork.
- CI still runs. If you have a paid CI with limited runners, a draft does not save resources. Some teams configure workflows with a condition to skip runs on drafts.
- CODEOWNERS is not auto-assigned, but you can add reviewers
manually. If you want a specific reviewer even on a draft, add
them with
gh pr edit --add-reviewer @alice. - Draft PRs are unavailable on some GitHub plans (older free private repos). On most current plans they are available.
Alternative: committing to a feature branch without a PR
If work is very early, it is sometimes simpler to commit directly to the feature branch without opening a PR at all. Open a draft when you want CI and public visibility. Before that point, it is often easier not to show unfinished code.