Deployment Strategy

This document serves to outline the approach to deployment that Garment takes, and the associated conventions it defines based on this approach. See the Deployment Configuration documentation for how you configure your deployments.


Environments are containers for your various deployment scenarios, you might have just a production environment, or you may have more complex setups that involve multiple environments (qa, staging, etc).

Their names are free form and you can call them anything you like that suits your deployment needs.


Releases refer to an archive of an application that is identified by a time stamp (ISO8601), the GIT reference and the user specification that deployed the release:


Releases are maintained in a designated folder on each of the Hosts and a configurable number of historical releases are kept around for easy rollbacks should a deployment go awry.

Each Host keeps a full copy of the repository. On each deployment the local copy of the repository is updated using git pull.

To create a release the git archive command is used. We also support adding files from the submodules in a project.


Hosts are the targets that you wish to deploy your application to. They can be assigned roles that can be used to only run certain Steps on certain Hosts when running the Stages.


Roles are arbitrary items that you create that can be used to control which of the different Stages you define run on which Hosts.

There is a special role named all that is used for targeting all hosts by internal Garment operations (like sending the release). You do not need to assign any roles to your hosts if you don’t need them to accomplish your deployments.


Stages make up the workflow of the deployment process and are named as follows:

  • before
  • after
  • rollback
  • cleanup

Steps within the Stages are defined as an ordered list and run in the order that they are defined.

Inside each Step is some configuration about the execution environment (working directory, command prefixes, environment variables, etc) and then an ordered list of shell commands that will be executed.

All commands in a Stage must succeed for the Stage to be considered a success, if a Step fails then deployment stops.

Currently no clean up is done on failed deployments to ensure that you have the opportunity to investigate the failure manually while implementing your config. Your deployment shouldn’t ever fail after that point so if it does leaving the machine in the broken state allows you to fix it properly.

Deployment preparation

When a release is being deployed Garment will first prepare the release by generating a name, as described above, and then making an archive of the repository into the releases directory under this new name.

This is done entirely automatically and can only be influenced through the Base configuration.

Before stage

The before stage is run once the release is prepared and it allows you to prepare the application for becoming the running release. It also allows you to do any backup related tasks that can be used during the rollback stage.

If your application does not require any special preparation you do not need to specify any tasks in the before stage and it can be omitted.

Examples of things that are done in the before stage:

  • Installing dependencies (virtualenv, rvm, composer, etc)
  • Run database migrations
  • Managing/preparing static content
  • Backing up the current environment
  • Backing up the database

After stage

Like the before stage the after stage allows you to further prepare the application for becoming the running release. You can also preform any backup tasks you’d like as well.

If your application does not require any special preparation you do not need to specify any tasks in the before stage and it can be omitted.

Examples of things that are done in the after stage:

  • Restarting application servers


Operations are the different workflows that Garment exposes. The following describes each of the operations and specifies which stages are run and in which order.


When you ask Garment to deploy it does the following:

  1. Prepares the release
  2. Runs the before stage
  3. Makes the new release the current release
  4. Runs the after stage


When you ask Garment to rollback it does the following:

  1. Runs the rollback stage
  2. Makes the rollback release the current release
  3. Runs the after stage