Bitbucket Request changes and Needs work: the reviewer status in Cloud and Data Center
A Bitbucket reviewer can do more than approve: they can say the pull request needs changes first. Bitbucket Cloud calls this Request changes and shows the reviewer as Changes requested. Bitbucket Data Center called it Needs work; its REST reference says the web interface has called it Requested changes since 8.10, while the API still says NEEDS_WORK. Below is how each works, from Atlassian's announcement of Changes requested (December 2020), Suggest or require checks before a merge, the Cloud REST reference, Data Center's Reviewing a pull request and the Data Center REST reference.
Bitbucket Cloud: Changes requested
- What it says: the reviewer would like to see changes before approving. Atlassian's announcement pairs it with comments and tasks that tell the author what to do.
- Blocking the merge: the merge check No changes are requested warns while any reviewer has Changes requested. As with every merge check, it only stops the merge on Premium with Prevent a merge with unresolved merge checks; otherwise it is a warning.
- After a push: Reset requested changes when the source branch is modified clears every Changes requested status when the source branch changes. It sits in the same branch restriction settings; resetting approvals on a push is a separate setting, and Premium only.
- In the REST API:
POST …/pullrequests/{id}/request-changesrequests changes as the authenticated user andDELETEon the same address withdraws it (scopewrite:pullrequest; both answer 400 once the pull request is merged). The participant'sstateis thenchanges_requested. The branch restriction kinds arerequire_no_changes_requestedandreset_pullrequest_changes_requested_on_change. - Webhooks: Changes Request created and Changes Request removed, under Repository settings > Webhooks (Atlassian's announcement).
Bitbucket Data Center: Needs work, now Requested changes
- The names: Data Center 8.8's guide lists Approve and Needs work; the 10.2 guide lists Approve and Request changes, with the same meaning: you reviewed the changes, but the code is not quite ready to be merged. Searches and older posts use both names for the same status.
- Blocking the merge: the merge check No 'changes requested' status refuses the merge while a reviewer has this status (see merge checks).
- In the REST API:
PUT …/pull-requests/{id}/participants/{userSlug}with"status": "NEEDS_WORK"sets it,"APPROVED"approves and"UNAPPROVED"clears either. It changes the current user's status, adds them as a participant if needed, fails for the author, and records the latest commit of the source branch as the participant'slastReviewedCommit.
Requesting changes in IntelliJ IDEA
Pull Request Inbox for Bitbucket, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists the Bitbucket Cloud and Bitbucket Data Center pull requests waiting for your review in an IDE tool window. Its Review… menu offers Approve and Request changes, and whichever you already did is offered to take back instead (Remove approval, Withdraw change request); on Data Center it sets Needs work through the same participant call. Each reviewer shows as approved, changes requested or not reviewed yet, and the merge checks show in plain words (on Data Center, in the server's own words). Approving is refused when new commits arrived after you opened the pull request, so you approve what you saw. The review inbox and the merge checks are free; approving, requesting changes, commenting and merging are Pro, with a 30-day trial.
Get it on JetBrains Marketplace
Bitbucket is a trademark of Atlassian Pty Ltd; 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 · Bitbucket merge checks · review requests · default reviewers · auto-merge · 日本語