Unlocking the Power of a Config in a Parameter

Tugboat (and many deploy preview tools) works by asking users to commit a config.yml file to a specific directory in the linked git repository. While this provides a quick way to get up and running with building on-demand environments, there are cases when this process represents a constraint for organizations. To facilitate integration with a popular open-source CMS framework’s issue queue, we’ve added a new feature to Tugboat’s API: the ability to accept a config.yml as a parameter, instead of requiring it to be committed to the linked git repository. This new feature opens the door for a lot of interesting build possibilities!

Simple use case: iterate on the config.yml without pushing commits

When you’re testing a new Tugboat config.yml file, or changes to an existing config.yml, the historic process has been make a change, commit, push to a branch, and then rebuild. By passing the config as a parameter, you can quickly iterate toward a final config.yml file without pushing every commit.

1. Create basic config.yml with just the services you think you need
2. Run tugboat create preview main repo=[REPO-ID] config=./config.yml in the Tugboat CLI
3. Wait for the Preview to build.
4. Make another change to the config.yml, then go to step 2 to use the CLI to create a Preview with the updated config.
5. Keep making small changes and repeating 2 through 4 until you get a fully working config.yml.

Interesting use case: dynamically generate config parameters on the fly

A more interesting use case, and the one that initially prompted us to implement this functionality, is using the option to pass a config parameter to create Preview environments on-the-fly in more complex build scenarios.

For example, the traditional workflow of creating a config.yml and committing it works if your infrastructure is consistent. However, if you want to customize the infrastructure for something like user-selected options, you’d either need to commit a ton of config.yml options to account for all possible permutations, or pass the config as a dynamically-generated parameter when building the environment based on the user-selected options.

This new feature dramatically expands the possibilities for really interesting, complex environment builds. We’re excited to see how people will use it!

Creative use case: run Lighthouse reports in locked Previews

Beyond the build process itself, the option to pass a config as a parameter opens up some really creative ancillary ways to use Tugboat Previews. For example, one thing we’ve been working on recently is using Tugboat to generate and store Lighthouse reports. One of our developers brainstormed this workflow to run Lighthouse reports:

1. Create a Preview that has a Google Lighthouse server in it.
2. Lock the Preview.
3. Use it as the destination for test results.

In this scenario, the developer creates a Lighthouse server Preview using the API, and then Locks it. Then the developer uses a Tugboat config to build their sites, and associated Base Preview. When the Base Preview builds, it runs a Lighthouse report on it, uploads that report to the Lighthouse server, and sets it as the “Base” in Lighthouse terminology. Then, when new pull requests come in, Tugboat builds them, generates a Lighthouse report, and uploads it to the Lighthouse server Preview.

Pretty cool, right? We love these creative, outside-the-box ways of using Tugboat Previews with this new functionality.

How to submit a config as a parameter

The option to submit a config as a parameter instead of by committing it to the linked git repository is detailed in Tugboat’s API documentation, at Create a Preview → config. It’s an option on POST when creating a Preview. You’ll need to create a JSON object that describes the services in your Preview, similar to how you’d create the infrastructure as code if you were using the traditional config.yml option. You can see request samples in the API documentation, and can drill down into available options for setting up your infrastructure via the API.

Alternately, if you’re running the Tugboat CLI version 2.20.44 or later, you can use this command to pass a local config.yml to build a Preview without needing to commit it to the linked repository:

tugboat create preview [BRANCH-NAME] repo=[REPO-ID] config=./config.yml

Have questions? Join our Support Slack.

If you think this new functionality sounds cool, but have questions about implementing it for your own Tugboat projects, feel free to join our Support Slack. It’s a great community of developers who use Tugboat, as well as Tugboat’s own developers, who can answer questions and get you going. And if you come up with a new, creative, or interesting way to use Tugboat Previews with the new config parameter feature, let us know - we’d love to hear about it!

‍