Using draft pull requests effectively

A draft pull request is a pull request that says “not ready for review yet”. It runs CI, shows up in the repository’s list, and can collect comments, but it does not request reviews, cannot be merged and stays out of code owners’ queues. Used well, drafts give an author early CI results and early design feedback while keeping reviewers’ queues limited to work that is actually ready. Used badly, they become a parking lot of abandoned branches, or a way to skip the review request and quietly flip to ready at the last minute. This page covers when to open a draft, how to ask for early feedback on one, how to tune CI for drafts, how to mark it ready, and how to keep old drafts from piling up, within code review workflow engineering.

When to use this approach

  • You want CI feedback on a branch before it is ready for review.
  • You want early comments on an approach before finishing the implementation.
  • Reviewers’ queues are cluttered with pull requests that are not finished.
  • You use review targets, as in setting review turnaround targets and escalation, and need drafts excluded from them.

Step 1 — Open a draft early

Open the draft as soon as the branch has a first commit worth running CI on. Early drafts show others what you are working on and reduce duplicated work.

git switch -c feature/rate-limits
git commit --allow-empty -m "WIP: rate limits for the public API"
git push -u origin feature/rate-limits
gh pr create --draft --title "Rate limits for the public API" --body "Early draft — approach in description, implementation in progress."
The life of a draft pull requestThe author opens a draft with the first commit and CI runs. The author may ask specific people for early feedback on the approach. When the work is complete and CI is green, the author marks it ready, which requests review. Review and merge follow as normal.Open draftfirst commitCI runsearly signalEarly feedbackask named peopleMark readycomplete + greenReview, mergenormal flowreview requests happen at 'mark ready', not at creation

Step 2 — Ask for early feedback explicitly

A draft does not ask anyone for anything by default. When you want an opinion on the approach, say exactly what you want feedback on, and mention the people you are asking.

gh pr comment 1234 --body "@priya @jonas — early feedback wanted on the approach only:
does a token bucket per API key in Redis fit how we deploy? Ignore naming and tests for now."

Narrow requests get fast, useful answers. “Any thoughts?” on a half-finished draft gets neither.

Step 3 — Tune CI for drafts

Drafts benefit from fast checks; expensive suites can wait for ready. Skip slow jobs on drafts, and run them when the pull request is marked ready.

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
jobs:
  fast:
    runs-on: ubuntu-latest
    steps: [{ uses: actions/checkout@v4 }, { run: make lint unit }]
  slow:
    if: ${{ !github.event.pull_request.draft }}
    runs-on: ubuntu-latest
    steps: [{ uses: actions/checkout@v4 }, { run: make integration e2e }]

The ready_for_review event makes the slow jobs run as soon as the draft is marked ready. More on event selection is in optimizing CI triggers for path-specific changes.

Step 4 — Mark ready only when it is ready

“Ready” means complete, green, described and sized for review. A short checklist in the template makes this concrete.

gh pr checks 1234 --required && gh pr ready 1234
Draft or ready?If the work is incomplete or CI is red, keep it as a draft. If the work is complete but you want feedback on a specific question first, keep it as a draft and ask named people. If the work is complete, CI is green and the description explains it, mark it ready for review.What state is the work in?incomplete or redStay draftkeep pushingcomplete, open questionStay draftask named peoplecomplete, green, describedMark readyreview requestedready is a promise to reviewers that their time will be well spent

Step 5 — Keep drafts out of review metrics and queues

Exclude drafts from review dashboards, reminders and latency measurements; including them makes every metric look worse and trains people to ignore reminders.

gh pr list --state open --search "draft:false review:required"     # review queue
gh pr list --state open --search "draft:true"                       # drafts, listed separately

Step 6 — Clean up stale drafts

Drafts that stop moving clutter the list and hide abandoned branches. Remind authors after a few weeks of inactivity, and close after longer; closing is reversible.

gh pr list --state open --search "draft:true updated:<$(date -d '30 days ago' +%F)" --json number,author,title \
  --jq '.[] | "#\(.number) @\(.author.login) \(.title)"'
# Closing keeps the branch; reopen any time
gh pr close 1234 --comment "Closing stale draft after 60 days without activity — reopen any time."

Branch lifetime limits generally are covered in limiting feature branch lifetime.

Step 7 — Convert back to draft when needed

If review shows that more work is needed than a round of fixes, convert the pull request back to draft. That removes it from reviewers’ queues until it is ready again, and makes the state honest.

gh pr ready 1234 --undo
gh pr comment 1234 --body "Back to draft while I restructure the storage layer — will re-request review."
Draft and ready pull requests comparedA draft runs fast CI, can receive comments when asked, but requests no reviews, cannot merge and is excluded from review metrics. A ready pull request runs full CI, requests reviewers and code owners, can merge once approved, and counts toward turnaround targets.DraftReadyCIfast jobsfull pipelinereview requestsnonereviewers + ownerscan mergenoafter approvalcounts in review targetsnoyesthe state tells reviewers whether their time is wanted yet

Validation checklist

Frequently Asked Questions

Do code owners get notified about drafts?

No. Code owner review requests are made when the pull request is marked ready, which is one reason drafts keep queues clean.

Should drafts be allowed on forks?

Yes. Drafts from forks run CI under the same rules as other fork pull requests, and are a good way for outside contributors to signal work in progress.

Can a draft be merged by mistake?

No. The forge blocks merging until it is marked ready, so the only risk is someone marking it ready prematurely — which branch protection and required reviews still catch.