Draft pull requests
It might sometimes take you more time than planned to put a pull request together so you’d like to avoid unnecessary feedback or accidental merging until it is ready.
By creating a draft pull request, you can clearly signal to your team that the work is still in progress. You can still use all of Bitbucket’s collaborative features to get early feedback while your pull request is a draft, but merging is prevented and the look and feel of the draft tells your teammates where things are at.
At the same time, with the help of webhooks, you can update your integrations with CI tools and other platforms to track draft pull requests, thus maintaining total control over your workflows.
On this page:
Once your pull request is ready for review and merging, it’s easy to mark it as such. Check out the following screenshot.
The information note lets you and the reviewers know that you’re viewing a draft. The Mark as ready button in the note allows you to submit your draft for further review and merge.
The Draft lozenge (DRAFT) will be displayed on a draft pull request across the whole user interface until you mark the pull request as ready for review.
The Mark as ready button allows you to submit your draft for further review and merge.
Create a draft pull request
You start creating a draft pull request in the same way as you create a regular pull request. When you’re ready to save the draft pull request, select Create as draft.
Check out the more detailed guidelines:
Select Create pull request in the sidebar or on the Pull requests page.
Before you proceed, check the Diff and Commits tabs at the bottom of the page to compare the source and destination branches.
Select the source tag or branch and the destination branch. Then, select Continue.
Enter the title and description of your draft pull request.
In the Reviewers field, mention individual team members or reviewer groups from whom you’re expecting feedback on your draft pull request. The added reviewers will receive an email notification about the draft pull request.
If default reviewers or code owners are configured for the branches you’re working with, these people will be automatically added as reviewers to your pull request. If you don’t wish to share your work with all of them, remove the corresponding user tags from the field. If you remove at least one reviewer, the Default reviewers or Code owners quick add buttons respectively will appear under the field, showing you how many reviewers you can still add from each group.Feel free to skip adding reviewers when you’re only creating a draft pull request. You can add them later. For example, when editing the draft to make it ready for review.
Select Create as draft.
Your draft pull request has been created and you can continue your work.
Make a draft pull request ready for review
When you’re ready to share your code for further review and merge, you can mark your draft pull request as ready for review. To do this, select the Mark as ready button.
At this stage, you can also add reviewers to your pull request manually or, if applicable, manage the automatically added default reviewers or code owners with the corresponding quick add buttons under the Reviewers field.
Your draft will immediately become ready for review and merge, just as your regular pull requests. In the activity history, the pull request will be marked as Ready for review (READY FOR REVIEW). The reviewers you’ve added will receive an email notification about the pull request made ready for review.
Convert a regular pull request to a draft
If you want to convert your pull request back to draft to continue working on it, go to the pull request action menu (
) and select Mark as draft. In the activity history, the pull request will be marked as Draft (DRAFT).
Review a draft pull request
You review draft pull requests in the same way as you review regular pull requests: you can approve drafts or request changes to them. These reviewer statuses will remain after the draft pull request is marked as ready for review.
Note that until a draft is marked as ready for review, it isn’t eligible for merging, either manually or automatically.
View draft pull requests
By default, draft pull requests are hidden from the list of pull requests in your Bitbucket instance. To view draft pull requests:
Go to the Pull requests page.
Select the Show drafts checkbox.
Drafts will be displayed on the list with other pull requests in the order based on the time of their last update.
Webhooks for draft pull requests
Draft pull requests not only ensure a seamless internal process but can also play well with other applications, giving you total control over your workflows.
To signal the draft nature of pull requests to your Bitbucket integrations with CI tools or communication platforms like Slack, use updated webhooks.
Audit log events
The Bitbucket audit log allows you to have a full history of changes to draft pull requests: when they were created, made ready for review, or converted back to drafts.
Check the audit log events for draft pull requests
Bamboo-Bitbucket integration
If you're using Bamboo with Bitbucket Data Center, note that Bamboo builds are triggered for draft pull requests in the same way as for regular pull requests. Draft pull requests have no impact on Bamboo's behavior.