Closeup photo of white paper boat. Photo by Artak Petrosyan on Unsplash.

Have you ever thought: “Wow, I love speeding up my Tugboat Preview builds by using Base Previews, but I wish Tugboat could automatically select which Base Preview to build from, instead of building them all.”

Us, too!

After thinking carefully about what the common use cases would be, and what this should look like, we’ve put together some new functionality for Tugboat’s Base Previews: Base Preview Types, and Base Preview Auto Select.

We rolled out this new functionality overnight, so by the time you read this article, you’ll already have the new options in your Tugboat repositories!

Use cases for automatically selecting a specific Base Preview

In order to decide how to implement this feature, we took a look at the most common use cases that might benefit from it. There are a lot of ways this might be used, but a few common things include:

  • Handling concurrent Feature, Development, Release, and Production branches within a repo, and building only from the Base Preview relevant to each branch. For example, developers working on a specific Feature Branch - like the branch to add the Base Preview Auto Select functionality to Tugboat - wouldn’t necessarily want to trigger builds of their code against the Release branch when they’re still developing the feature.
  • Maintaining different versions of a framework as branches within a repository, and only building Previews from the framework version relevant to a given pull request. For example, a Drupal repository might have branches for 8.7, 8.8 and 9.0; and a git pull request against the 9.0 branch shouldn’t necessarily trigger a build from 8.7.
  • Testing new infrastructure configurations or upgrades on specific branches.
  • Managing multiple feature development workflows independently.

In the end, looking at the most common use cases led us to create two different types of Base Previews. We could then let Tugboat match against these Base Preview Types when determining which Base Previews to use when building a new Preview.

Introducing: Base Preview Types

In breaking down the most common use cases to have Tugboat automatically select a Base Preview to use when building new Previews, we determined that introducing two types of Base Previews would address those common use cases. We coined these concepts:

  • Repository Base Previews
  • Branch Base Previews

Repository Base Previews

Thinking about this feature and how we had previously been using Base Previews, we decided that the default Base Preview Type should be a Repository Base Preview. When you set a Repository Base Preview, every new Preview built within that repository automatically builds against that Base Preview. This is a great option for many customers using simple git workflows.

Got a simple static site? Set main as a Repository Base Preview, and all new Preview builds will start from that main Base Preview. This is a fast and easy way to test new content, configuration changes, styling changes and other tweaks. This is also the fastest way to take advantage of Tugboat’s Visual Diffs to keep tabs on any visual regressions in your site.

You can set more than one Repository Base Preview, so if you’ve got something like main and an example-branch with different styling, you can easily see how code changes affect both Base Previews. Any new pull request created within a repository that has Repository Base Previews triggers a Preview build starting from those Repository Base Previews.

If you’ve been using Base Previews prior to this new functionality, all of your Base Previews have automatically become Repository Base Previews. You won’t see any change in functionality, except a new Preview Settings option in the UI, which gives you a new place to manage those Base Previews.

Branch Base Previews

A lot of the versatility and new functionality in the feature to automatically select Base Previews comes from the addition of the second Base Preview type: Branch Base Previews. When you designate a Preview build as a Branch Base Preview, every pull request that merges into that branch kicks off a new Preview build specifically from that Branch Base Preview.

Previously, a more complex git workflow might use four or five (or more!) Repository Base Previews in Tugboat. Every pull request in the linked git repository would kick off four or five new Preview builds from those Base Previews, even though only one of them might be relevant to the pull request.

The Branch Base Preview changes that. Now, you could have four or five Base Previews, but if they’re all Branch Base Previews, only one Preview build would be triggered when a pull request is made - a Preview build from the Branch Base Preview that the pull request is merging into. For example, if you’re using only Branch Base Previews, and you make a pull request against the example-branch branch, only one Preview will build - the one starting from that Branch Base Preview.

This very targeted Base Preview type opens up the ability to use Base Previews for a lot of more complex git workflows, where using multiple Base Previews previously might have used too many resources or added lots of noise.

How Tugboat automatically selects Base Previews for your Deployment Builds

So with the introduction of these two new Base Preview Types, how does Tugboat know which Base Preview to select when a new pull request is made? We wanted to reduce code complexity, while simultaneously building in the ability to expand this functionality if we wanted to down the road, so they created a simple matching algorithm. When a new pull request is created in a git repository that is linked to Tugboat, Tugboat automatically kicks off deployment builds from all matching Base Preview Types.

For example, if you’re using main as a Repository Base Preview, and my-other-branch as a Branch Base Preview, and you create a pull request that merges into my-other-branch, Tugboat kicks off two Preview builds: one for the Repository Base Preview, and one for the Branch Base Preview. If main and example-branch are both set as Repository Base Previews, and my-other-branch is a Branch Base Preview, you’ll get three Preview builds; one for each applicable Base Preview.

Preview Settings and Managing Base Previews

With the introduction of Base Preview Types, we’ve added a new UI element: Preview Settings.

Tugboat Dashboard with new Preview Settings element circled

We’ve also removed a UI element: the Manage Base Previews link.

Tugboat Dashboard with old Manage Base Previews link

Instead of using the Manage Base Previews link to add Base Previews or stop using Base Previews, you’ll now go into Preview Settings on each individual Preview to say whether it should be used as a Base Preview, and if so, specify the Preview type.

Setting Base Preview and selecting Base Preview Type in the new Preview Settings page

For more details about these changes, check out our new and updated documentation:

If you have questions we don’t cover in the documentation, ask us in our Slack support channel, or email.