Automatic Merging When Builds Pass

[#1]

This is a community article version of the blog post available here: https://bitbucket.org/blog/automatic-merging-when-builds-pass

Today Bitbucket is releasing a new labs feature, "Pending Merges", which allows for automatic merging of pull requests when builds pass. This means no more continually checking back in on your pull request, just waiting and waiting for your builds to pass before you can finally merge it. You will no longer be forced to begrudgingly fix that one-character whitespace typo in your comment that you really should fix, but that means you're in for another 30-60 minutes of watching your builds. Even if your builds just take 1-2 minutes, we get it. Who wants to watch builds?

This functionality works in essentially the same manner that you’d otherwise merge your pull request. When you have all required merge checks except successful builds completed, you will be able select the Merge option and we’ll take it from there.

How to Use Automatic Merging

In three pictures:

Select Merge on the open pull request.

And when all that’s remaining is passing builds…

You will be able to go ahead and request a merge of the change.

If the builds pass, we’ll go ahead and merge the change. But if they fail, we won’t merge the change and we’ll send a notification to the user that requested the merge.

An example e-mail notification for when builds fail

Merge Checks Support

This functionality works alongside merge check requirements, so branches that have required merge checks (such as a required number of approvers, all tasks being resolved, etc.) will have those checks honored. This works by preventing the option the merge if there are any open merge checks, with the exception of successful builds.

An example change that doesn’t have the required number of approvals

Results in not being able to request a pending merge

Configuring Automatic Merging

By default this functionality is not enabled on repositories, and must be enabled on each branch that wishes to grant the ability to automatically merge when builds pass.

This is selectable by repository administrators under Repository Settings -> Branch Permissions -> Edit/Add branch permission -> Allow automatic merge when builds pass.

This functionality must be enabled under the “Branch permissions” workflow

To try Pending merges, you'll need to enable the functionality in Bitbucket labs. Pending merges is being released as a beta feature. We would love to hear your feedback before we promote the feature to all users. If you have anything to share, please click the Give feedback link under the Pending merges feature on the labs page.

The feature is available in Bitbucket Labs

Happy merging!

[Chris Fouts]

I tried this today, and nada! My pull-request was NOT automatically merged. I RTFM'ed!

[Tim Peeters]

Hey,

We tried this today. When we clicked "merge" the pull request was immediately merged instead of waiting for the build to finish. Is it possible this only works when you have the "Premium" option?

Thanks in advance.

[Brandon Reppert]

@Tim Peeters Thanks for letting us know. I think it's definitely possible that the feature isn't working properly on non-premium accounts, though we intended the functionality to be available to non-premium users. We'll try to reproduce and fix the issue.

@Chris Fouts I'm sorry to hear that the feature didn't work for you. Did you receive any e-mail notifications explaining why the pull request wasn't merged? There are a number of reasons that a pending merge might be cancelled (e.g. a change was pushed to the branch or there was an error merging the branch to the destination), but we should send an e-mail notification on each failure. If you didn't receive an e-mail, that's definitely a bug and we'd need to look into that.

[Travis Hill]

I turned on the option in Labs and checked the box in my branch permissions, but it doesn't seem to have changed anything.

We do have a premium account, and I have the merge checks set up to prevent a merge with unresolved merge checks with 1 successful build required.

When I open a PR, and the only thing it's waiting on is a successful build, I don't get the option to merge. The button is grayed out and the message just says 1 failed merge check and nothing about when all builds are successful.

[Brandon Reppert]

@Tim Peeters We were unable to reproduce the issue ourselves on a free account. Could you provide some more details for your configuration, either here or by opening a BCLOUD ticket at https://jira.atlassian.com/secure/Dashboard.jspa. If you do open a BCLOUD ticket please let me know here and mention me on the ticket so I can be sure to see and triage the issue appropriately.

@Travis Hill I think this is a problem with our interface, but the functionality should work. If you click the gray "Merge" button while the builds are pending it should open up a modal that allows you schedule the merge. We should update the button styling regardless, but please let me know if that doesn't work for you.

[Chris Fouts]

@Brandon Reppert we got nothing. ALL of the merge conditions were met, and the "Merge" button on the PR was enabled, but NO automatic merge. So we just merged it manually. We do have a Premium account.

[Ihor Posmashnyi]

@Chris Fouts you don't have to wait until all the conditions are met. You should click on the gray "Merge" button when the builds are processing. Then you'll have the ability to schedule the merge via blue "Merge" button with a clock icon on the popup.
As @Brandon Reppert already said, the issue comes from our user experience. 
I hope that helps.

[Chris Fouts]

@Ihor Posmashnyi Oh I understand now. Once I create PR, I click the greyed out "Merge" button, but don't have to keep checking until all the conditions are met for it to "really" get merged.

Edit.

I RTFM'ed more and now note that the feature does NOT pend on other merge conditions, that is, the clock near the blue Merge button on the pop-up window does NOT appear if other conditions, other than builds or merge tasks passing, are not met. For example, if we have "number of approvals" condition, I don't get the blue clock Merge button on the pop-up. Then this feature is NOT that useful at all, for us anyway.

[Travis Hill]

It doesn't seem to be just an issue with the button style. Clicking the disabled button does nothing. It has the "disabled" cursor icon and the message above does not say anything about merging when builds are successful. It is all the exact same as if I didn't have the feature turned on at all. But I triple checked, and I do have it enabled, and the permission set up for this branch.

[Brandon Reppert]

@Chris Fouts Yes that's definitely it, sorry for the confusion. Pending merges is specifically for scheduling automatic merging against builds. It's not designed to automatically merge the request as soon as all of the merge checks pass. It'd definitely be useful to have the option for the merge to go through as soon as all merge checks are completed though, regardless of their relation to the builds. That's certainly a possible piece of functionality to build -- I'll log it but can't promise any prioritization.

@Travis Hill I think you may be in the same scenario as Chris. Otherwise without being able to look into your repo/situation I'm not sure why the merge would not be selectable.

[Jack Gersten]

I'm seeing the same behavior as Travis where turning on the new feature doesn't appear to do anything and the pop-up's Merge button is still disabled

 

[Brandon Reppert]

Those screenshots are helpful, thanks @Jack Gersten! You definitely have the right configuration and there's a bug here.

@Roman Panchenko I'll add some details to our internal bug ticket. I see some inconsistent logic applied in the modal that should give us an idea of what's going on here.

Thanks everyone for your reports -- we'll be looking into this next week.

[Brandon Poe]

Hi @Brandon Reppert ,

After requesting "Automatic Merging When Builds Pass", is there a way to cancel that request before the automatic merge occurs? 

For example, say someone noticed one more thing on the PR.

[Chris Fouts]

@Brandon Poe maybe just add a task to the PR?

[Brandon Reppert]

@Brandon Poe @Chris Fouts You can cancel the merge by clicking the "Merge" button again and then selecting "Cancel Merge" on the modal.

On a separate note, we have discovered the source of the bug that we believe is the root cause for the above issues. It's related to how we gated the feature as a labs feature making the functionality unavailable in some cases where it should be available. We're working on a fix.

[Brandon Reppert]

We have fixed the issue related to the functionality not being available in cases where it should have been enabled. Thanks again for everyone that raised the issue here.

Anyone who was having difficulties scheduling pending merges should be able to re-try using the feature now and let us know if you have any continued issues.

[Chris Fouts]

Still no dice when "other" conditions are not met, e.g., > 1 approvals. It'd arguably be more useful if it covered all conditions.

[Brandon Reppert]

@Chris Fouts Noted -- I agree it definitely would be useful to have the feature able to schedule the pending merge to complete as soon as all merge checks are passed.

However as it's currently set up it's a feature specifically against builds, and would need somewhat significant changes to check against all the different merge conditions. We have those changes noted in our backlog, but that'll be a feature change, not a bug.

[Tom Somerville]

Hi @Brandon Reppert 

Following on from what @Chris Fouts  said, in my case I require 1 approval and builds to pass before it can be merged. When I have the approval the option for the scheduled merge does not show up. When I remove the requirement for it to have 1 approval it does appear.

Just to be really clear here, the issue is when I DO have an approval and I require 1 approval.

[raijinsetsu]

This appears to be broken today. The lab is enabled for my account, all Branch Permissions for the repository have the checkbox to allow the pending merge, yet clicking "Merge" does not have the option of scheduling a merge.  I disabled extensions in my browser on the off-chance that they were the cause: still no dice. Everyone else on my team is having the same issue.

Although we have configured other merge checks, all but the build checks have passed. So, the option should be available.

I looked at the debugger on Chrome and found this request:

GET https://bitbucket.org/!api/internal/repositories/mtdevs/webapi-server/pullrequests/1608/pending_merge

And it returned this:

{"can_create_post_build_merge": true, "blocking_post_build_merge": []}

Hope this helps.

[Brandon Reppert]

Thanks @raijinsetsu!

We recently released a pretty major refactor that unfortunately broke some functionality, but we have a fixed version ready to go that should be out soon. Let us know if your issue persists (especially if it persists into next week).

[Brandon Reppert]

@Tom Somerville Thanks for the info and sorry for the delayed response -- I'm not able to reproduce that bug on my side. I'll take another look after our most recent round of refactors/fixes to see if I'm able to reproduce what you're seeing.

[Tom Somerville]

Hi @Brandon Reppert this has since been resolved it seems, suddenly it started working, thanks

[olockwood]

We like this a lot.

Is this functionality available (even if undocumented for now!) on the version 2.0 APIs?  It would be extremely helpful to us if so.  I tried guessing a URL like 

.../pullrequests/${pr number}/post-build-merge

without success; the BitBucket UI uses an internal API that I don't think is programatically accessible for us.

And is there an ETA for this becoming core functionality (i.e. completing the beta)?

Many thanks.

[Brandon Reppert]

Hi @olockwood, glad the feature is proving useful for you.

The internal API should be accessible to your team in the same manner that the public API would, but the caveat with internal APIs is that the documentation isn't publicly accessible and we retain the ability to make breaking changes to the API at any time. Let me know if you have any questions or issues with that and I'll be happy to help out, but we don't have any current plans to make those APIs publicly available as 2.0 APIs.

Additionally we're planning on moving the feature from beta to GA within the next month, and we could be making this move as early as next week. We're making the feature a premium feature, but that is being done only because the use case doesn't really make sense for non-premium users at this time (since non-premium users are always presented with the option to merge the PR regardless of build status).