Bitbucket draft pull requests: marking ready, who is notified, and the API
A draft pull request shows work in progress: reviewers can look and comment, but it cannot be merged, manually or automatically, until it is marked as ready for review. Bitbucket Cloud has had drafts since April 2, 2025 (BCLOUD-12503, opened in 2016, 1,903 votes). Bitbucket Data Center has had them since 8.18.0 (BSERV-4262, 526 votes).
Creating, marking ready, and back
- Mark as ready. On both, a draft has a Mark as ready button; the pull request can then be merged like any other, and its activity shows READY FOR REVIEW. Approvals and change requests given on the draft stay (Cloud documentation, Data Center documentation).
- Back to draft. The pull request's action menu (…) has Mark as draft; the activity shows DRAFT. On Cloud this works for any open pull request, also one that was not created as a draft (Atlassian's announcement).
- Creating. On Data Center, select Create as draft when creating the pull request.
- Data Center's list hides drafts. The pull requests list leaves drafts out until you select Show drafts.
- Builds still run. Data Center's documentation says Bamboo builds a draft as it builds any pull request.
Who is notified
Here the two differ. On Cloud, reviewers you add to a draft are not notified until you mark it as ready; then they get an email. On Data Center, the reviewers you add get an email about the draft right away, and another one when it is made ready for review. On Data Center, add reviewers later if they should not hear about the draft yet.
Through the REST API
- Cloud. A pull request has a
draftfield, which creating and updating (PUT /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{id}) take. Soon after the launch, the list call withstate=OPENreturned only pull requests that were not drafts; reported April 9 and fixed April 15, 2025 (BCLOUD-23659; the workaround wasq=state="OPEN" AND (draft=true OR draft=false)). - Cloud: an inactive reviewer blocks updates. When a reviewer of the pull request has left or been deactivated, an update fails with 400 "Malformed reviewers list", whatever it changes, until that reviewer is removed (BCLOUD-23093, open). That includes marking a draft ready through the API.
- Data Center. The list call (
GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests) takesdraftto return only drafts or only the others. The update (PUTon the pull request) takesdraftfrom 8.18:falsepublishes, and leaving it out keeps the draft status. - Data Center: the update sets the reviewers. The reviewers you send become the list; a current reviewer left out is made a mere participant (PullRequestUpdateRequest). The update also needs the pull request's current
version; an old one is refused as out-of-date information. So read the pull request first and send its title, description and reviewers back with"draft": false.
Drafts in IntelliJ IDEA
Pull Request Inbox for Bitbucket, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the pull requests of Bitbucket Cloud and, in beta, of Bitbucket Data Center 8.9 or later in an IDE tool window, with drafts marked [draft]. It creates a pull request or a draft from the current branch (drafts on Data Center 8.18 and later), and from version 1.0.36 its Mark as Ready button takes a draft out of draft, sending its title, description and reviewers back as they are. The review inbox, diffs, discussions and merge checks are free; approving, commenting, merging and marking ready are Pro (US$1.50 a month, with a 30-day trial).
Get it on JetBrains Marketplace
Bitbucket and Atlassian are trademarks of Atlassian; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Atlassian or JetBrains.
More: decline, and reopening · find every pull request waiting for your review · Bitbucket merge checks · Bitbucket code suggestions · Bitbucket pull request plugins for IntelliJ IDEA, compared · 日本語