How to enforce a format for a (pull request) merge commit message in BitBucket

Question

Our team is migrating to BitBucket. Our workflow requires certain formatting for commit messages for code that is merged into the main origin repo.

Each developer has one (or more) fork(s). Our workflow is to push a feature/bug branch to the fork and create a pull request from that branch. Two other devs must review and +1 the pull request before it can be merged.

When someone clicks Merge, BitBucket displays a dialog with the title "Merge Pull Request". At that point, the dev can edit the text message that is logged for the merge before clicking the second Merge button. This is the message that needs to conform to a specific format.

I have read the documentation here: https://scriptrunner.adaptavist.com/latest/bitbucket/StashMergeChecks.html It has several very specific examples, but nothing that pertains to our use case. I have not been able to find a good, general-purpose reference for how to create merge checks.

I can write a condition that checks for a specific string value:

mergeRequest.message == "My Message"

But I need it to check against a regular expression. How can I write a pre-merge hook to reject the merge if the message doesn't conform to a regex?

Addition

From the documentation, it seems like the condition check script code would be the right place to enforce this condition. The script can be added in Repository Settings > SCRIPTRUNNER > Script Merge Checks > Conditional merge check. There is a long list of examples shown for the conditional merge check, including things like:

• Current user in a particular group
• Changed files contains .XYZ files
• Changed files in sensitive directory
• Target branch is release

After some search & experiment I found I could block merges based on the commit message. But so far I have only found examples of comparing entire strings against constant string expressions. I haven't found how to use a regex in this comparison.

Answer 1

OP here after pushing this issue to the back burner for a few weeks. Issue is solved. You can check your merge commit messages against a regular expression without using a plugin. Solution is here for those who come searching with the same problem.

First, it was more challenging than it should have been to find the documentation for the objects that are most relevant to writing a Merge Check script. So here are a couple of links for the current 6.3.0 API:

• PullRequest - In the end, my script didn't use this object, but the pull request is closely related to the merge request and others may need the documentation.

• MergeRequest - This object has a method to determine the context (see below).

Second, the Merge Check script fires in two distinct contexts: (1) when bitbucket is trying to determine if it should enable/disable the Merge button on the Pull Request page, and (2) when someone clicks the Merge button on the Merge pull request dialog. In the first context the merge message is null, so it cannot match a regex. And anyway it doesn't make sense to disable the button in this case. I really only wanted the check to occur in the second context. So the script needs a way to distinguish the contexts.

Third, the message object is a Java String, so the script can call the matches() method to check if the message matches a regex.

After you have all the information at your fingertips, writing the script is pretty easy:

// the message regex
String pattern = "(PATTERN1|PATTERN2|etc)"
// reject if not dry-run and
//           message doesn't match regex
! mergeRequest.isDryRun() &&
    ! mergeRequest.message.matches(pattern)