🎉 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.)

Enable Mergetastic on your repositories

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. 

Configuring Mergetastic

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 mergetastic.yaml file:

  
queues:
  master: 
    required_builds:
      - LINTING
      - UNIT_TESTS
      - INTEGRATION_TESTS
  

Let's walk through this one line at a time:

  • The root element in the mergetastic.yaml config above is queues. This section describes the list of branches you'd like to make a queue out of.
  • In this example, the queues section contains only one queue: master. This is typically of many workflows, where the Pull Requests are targetted towards the main or the master branch. At the moment, only one queue per repository is officially supported, but that should change soon.
  • Inside the configuration section for the master queue, is a required_builds section. This is the list of Bitbucket build statuses that should be posted to a commit for Mergetastic to consider that commit "ready to merge". In the example above, build statuses with the keys LINTING, UNIT_TESTS, and INTEGRATION_TESTS are 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
  

This 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.

Adding your Pull Request to the queue

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.

Building the commits in the merge queue

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 mergetastic- prefix.

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.

Inspecting the Merge Queue

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).