Automations

You can write automation scripts which act on new or existing sites to perform tasks such as adding gems, updating configuration, inserting code, copying files, and much more.

Automations are similar in concept to Gatsby Recipes or Rails App Templates. They’re uniquely powerful when combined with plugins, as an automation can install and configure one or more plugins from a single script.

You could also write an automation to run multiple additional automations, and apply that to a brand-new site to set everything up exactly how you want it in a repeatable and automatic fashion.

Automations can be loaded from a local path, or they can be loaded from remote URLs including repositories. You can also run automation scripts from within Rake tasks, and the exact same automation DSL can be used directly within custom commands.

Running Automations #

For a new site, you can apply an automation as part of the creation process using --apply= or -a:

bridgetown new mysite --apply=/path/to/automation.rb

For existing sites, you can use the apply command:

bin/bridgetown apply /path/to/automation.rb

If you don’t supply any filename or URL to apply, it will look for bridgetown.automation.rb in the current working directory

vim bridgetown.automation.rb # save an automation script

bin/bridgetown apply

Remote URLs to automation scripts are also supported, and GitHub repo or gist URLs, GitLab repos, and Codeberg repos are automatically transformed to locate the right file from their servers:

# Install and configure the bridgetown-cloudinary gem
bin/bridgetown apply https://github.com/bridgetownrb/bridgetown-cloudinary

You can also load a file other than bridgetown.automation.rb from a repo:

# Set up a default configuration for Netlify hosting
bin/bridgetown apply https://github.com/bridgetownrb/automations/netlify.rb

Writing Automations #

An automation script is nothing more than a Ruby code file run in the context of an instance of Bridgetown::Commands::Apply. Available to you are all the automation tasks provided by Freyia, such as run to run a CLI executable, or ask to prompt the user for details, or say_status to provide helpful messages in the terminal.

You can read documentation on file tasks, shell tasks, and Bridgetown-specific tasks.

Here’s an example of an automation which creates a new file in a site repo:

create_file "netlify.toml" do
  <<~NETLIFY
    [build]
      command = "bin/bridgetown deploy"
      publish = "output"
    [build.environment]
      NODE_VERSION = "22"
    [context.production.environment]
      BRIDGETOWN_ENV = "production"
  NETLIFY
end

Bridgetown provides tasks which are useful specifically for working in the context of website projects.

Here’s an example of a plugin’s bridgetown.automation.rb which adds itself as a gem to a site and updates configuration based on user input:

say_status "Cloudinary", "Installing the bridgetown-cloudinary plugin..."

cloud_name = ask("What's your Cloudinary cloud name?")

add_bridgetown_plugin "bridgetown-cloudinary"

append_to_file "bridgetown.config.yml" do
  <<~YAML

    cloudinary:
      cloud_name: #{cloud_name}
  YAML
end

There is a whole variety of possible tasks at your disposal:

add_bridgetown_plugin "my-plugin" # bundle add…
add_npm_for_gem "my-plugin"  # npm install (looks up npm metadata in plugin gemspec)
add_npm_package "-D some-package-name"

# add another gem, but still continue if there's a Bundler error
run 'bundle add some-other-gem --version ">= 4.1.0, < 4.3.0"', abort_on_failure: false

create_builder "my_nifty_builder.rb" do # adds file in plugins/builders
  <<~RUBY
    class MyNeatBuilder < SiteBuilder
      def build
        puts MyPlugin.hello
      end
    end
  RUBY
end

javascript_import do # updates frontend/javascript/index.js
  <<~JS
    import { MyPlugin } from "my-plugin"

    const myPlugin = MyPlugin.setup({
      // configuration options
    })
  JS
end

create_file "src/_data/plugin_data.yml" do
  <<~YAML
    data:
      goes:
        here
  YAML
end

color = ask("What's your favorite color?")

append_to_file "bridgetown.config.yml" do
  <<~YAML

    my_plugin:
      favorite_color: #{color}
  YAML
end

In summary, automations are a fantastic method of saving repeatable setup steps for you to reuse later in new projects, or you can share scripts with the world at large. Use them for plugins, themes, or quick one-off scripts.

Variables