Capistrano recipe for a deployment workflow based on git tags
Switch branches/tags
Clone or download
Pull request Compare This branch is 80 commits behind technicalpickles:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


gitflow: a Capistrano recipe for git deployment using tags in a multistage environment.

The best thing about this recipe is that there is almost nothing to learn – your cap deploy process barely changes. Gitflow simply adds some tagging/logging/workflow magic.

$ cap deploy              # 'master' goes to staging
$ cap production deploy   # 'master' goes to production

$ cap deploy                                                          
# 'master' goes to staging; tag staging-YYYY-MM-DD.X created
$ cap production deploy
# deploys latest staging tag, or if last tag is a production tag then that, to production
# for specifying the tag by hand add `-s tag=staging-YYYY-MM-DD-X-user-description`
# tag 'staging-YYYY-MM-DD-X' goes to production
# tag 'production-YYYY-MM-DD-X' created; points to staging-YYYY-MM-DD-X

cap gitflow:commit_log              
# displays a commit log pushed to staging
# ... alternatively, if you're using GitHub, will open a page using branch compare
cap production gitflow:log_log   
# displays a commit log of what will be pushed to production


First, install the gem:

gem install capistrano-gitflow

Then update config/deploy.rb

require 'capistrano/ext/multistage'
require 'capistrano/gitflow' # needs to come after multistage


After experimenting with several workflows for deployment in git, I've finally found one I really like.

  • You can push to staging at any time; every staging push is automatically tagged with a unique tag.

  • You can only push a staging tag to production. This helps to enforce QA of all pushes to production.


Whenever you want to push the currently checked-out code to staging, just do:

cap staging deploy

gitflow will automatically:

  • create a unique tag in the format of 'staging-YYYY-MM-DD.X'

  • configure multistage to use that tag for the deploy

  • push the code and tags to the remote “origin”

  • and run the normal deploy task for the staging stage.


Whenever you want to push code to production, you must specify the staging tag you wish to promote to production:

cap production deploy -s tag=staging-2009-09-08.2

gitflow will automatically:

  • alias the staging tag to a production tag like: production-2008-09-08.2

  • configure multistage to use that tag for the deploy

  • push the code and tags to the remote “origin”

  • and run the normal deploy task for the production stage.


  • you may need to wipe out the cached-copy on the remote server that cap uses when switching to this workflow; I have seen situations where the cached copy cannot cleanly checkout to the new branch/tag. it's safe to try without wiping it out first, it will fail gracefully.

  • if your stages already have a “set :branch, 'my-staging-branch'” call in your configs, remove it. This workflow configures it automatically.


Originally forked from Alan Pinstein's git_deployment repo. Gemified and hacked by Josh Nichols. There wasn't really a license originally, so…