🎉 Thank you for installing Mergetastic! 🎉
This guide will help you set it up. (In case you haven't yet installed Mergetastic, take a look at Installing Mergetastic.)
After you install Mergetastic on your Bitbucket account, you'll need to enable it on the repositories you want to use it on. Head over to the settings page for the repository you want to enable Mergetastic on and look for Mergetastic settings in the left sidebar as shown in the figure below.
Figure 1: The Mergetastic settings for your repository
Use the toggle shown in Figure 1 above to enable Mergetastic for your repository.
Once you've enabled Mergetastic for your repository, you need to tell Mergetastic about the target branch that it needs to manage. This configuration happens using a
mergetastic.yaml file in your repository source code. You just have to add this file to your "main branch" (you can find out what that is by going to repository settings > Repository Details > Advanced > Main branch). If you're not sure what your main branch is, it's probably "master".
Here's a simple
queues: master: required_builds: - LINTING - UNIT_TESTS - INTEGRATION_TESTS
Let's walk through this one line at a time:
mergetastic.yamlconfig above is
queues. This section describes the list of branches you'd like to make a queue out of.
master. This is typically of many workflows, where the Pull Requests are targetted towards the
masterbranch. At the moment, only one queue per repository is officially supported, but that should change soon.
INTEGRATION_TESTSare required to be posted as successful for the commit to be merged by Mergetastic.
Note that if you've been using Bitbucket's built-in Merge checks, you're probably used to providing a specific number of successful builds. You can do that with Mergetastic too if you'd like:
queues: master: required_builds: 3
mergetastic.yaml file above basically says that as long as 3 successful builds are posted to a commit in the Merge Queue, Mergetastic should attempt to merge it into the target.
And that's it! Mergetastic is all set up. The rest of the document will go over how you and your team will use Mergetastic.
This is extremely simple. When you're ready to merge your Pull Request, instead of merging it directly yourself, you'll just use a button provided by mergetastic to add it to the queue. That's it!
Figure 2: Adding a PR to a queue is extremely simple
If you change your mind, you should also be able to remove the Pull Request from the queue using the same button.
Mergetastic can work with any build system. If you're already using a build system, you can continue to use it. When Mergetastic has one or more PRs in the Merge Queue, it creates a merge commit for them and sets it as the target of a build branch. For example, if your target branch is main, then the build branch
mergetastic will be
mergetastic-main. The build branch is always named the same as your target branch with a
You'll need to change your build system to make sure that it builds the Mergetastic build branch. See What's a Merge Queue and what is it good for? for an overview of the concepts and Integrating Mergetastic with Bitbucket Pipelines for an example of how to integrate a build system with Mergetastic.
Mergetastic provides a simple way of inspecting your Merge Queue. For each repository, there is a queue overview page accessible from the left sidebar in Bitbucket.
Figure 3: Merge Queue overview page
In Figure 3 shown above, you can see how easy it is to see an overview of the Merge Queue for this repository. To generate the screenshot above, 4 Pull Requests were added to the queue in rapid succession into a fresh repository. As soon as the first PR was added to the queue, Mergetastic created a new merge commit with it and placed it in the RUNNING state.
As new PRs were added to the Merge Queue, they start showing up as the "upcoming attempt" (the second row in the table).