I spend a lot of time working on deploying a variety of software applications smoothly to different environments. A tool central to my workflow is Capistrano, an SSH-based deployment framework written in Ruby.

In its Ruby-ish way, Capistrano’s multistage functionality requires stubbing out different Ruby files for each stage — staging, production, etc. In our environment, I decided it was better to instead store all of the per-stage configuration in one single configuration file, and I chose to do it in the simple YAML format.

There are several advantages to this approach:

• The file format is straightforward and can be modified both by humans and scripts, including automatic updates from a central source of truth.
• There are fewer configuration files, and within the single configuration file there is much less repetition of configuration, because we can use YAML’s built-in anchor/alias functionality.
• It strongly encourages storing deployment logic in the deploy.rb file and hooking tasks using Capistrano’s before/after callback functionality, rather than building stage-specific tasks.

The module I built is inspired by Jamis Buck’s original Capistrano multistage module, as well as Lee Hambly’s prototype YAML multistage extension, which was never packaged and is no longer maintained.

My capistrano-multiyaml module is available on GitHub along with documentation, and can be installed via RubyGems.