cap_git_tools

Re-usable, composable Capistrano tasks for git tagging and other work with the git repository you use for your Cap deploys.

• Ensure your local git is committed and pushed, so you are deploying what you think you are.
• Automatically git tag the deploy
• Enforce a multistage workflow where only a tagged staging release can be deployed to production (ala gitflow)

Functionality is split into discrete yet composable tasks, with sensible defaults but configurable, so you can build a cap recipe that fits your requirements and workflow. Ordinary single stage or multi-stage; with or without interactive confirmation prompts; using git however you're already or would like to be using it.

(_Inspired by Alan Pinstein and Josh Nichols' neat gitflow, but refactored for more flexiblity with less hardcoded workflow. Some functionality changed in the process.)

Installation

gem install cap_git_tools

Or if in the context of something using bundler such as Rails, add to Gemfile eg:

gem 'cap_git_tools', :group => :development

Add to top of a relevant Capistrano file (such as config/deploy.rb ordinarily):

require 'cap_git_tools/tasks'

This makes cap_git_tool's tasks available to you, but doesn't automatically wire them up to be used by your cap deploy. See below.

You probably want to make sure you have an ssh-agent set up, or you'll have to enter your private key password to access git several times.

Note: You will need to be running your cap recipes from a directory with a git checkout (usual behavior for cap usage, but not actually required otherwise by cap).

Ensure git is committed and pushed when deploying

Have you ever deployed the 'wrong' thing, because you forgot to commit and/or push your changes to git? I have.

Have cap make sure you're committed and pushed before deploying by adding to your recipe in deploy.rb:

before "deploy:update_code", "git:guard_committed", "git:guard_upstream"

Or use just one or the other

• guard_committed makes sure you have no uncommitted changes. IF you have a :branch set in your cap recipe, it will also make sure your curent checkout matches that branch.
• guard_upstream makes sure the current working copy branch committed tip (or local branch matching Cap :branch, if set) matches the upstream remote version.

Automatically tag on deploy

Every time you deploy, want to have Capistrano automatically tag exactly what gets deployed, with a tag like "deploy-2012-04-11-1517"?

Add this to your Cap recipe, usefully combining with the tasks to make sure your git copy is 'clean' as discussed above:

before "deploy:update_code", "git:guard_committed", "git:guard_upstream", "git:tag"

That's a date and timestamp, deploy-yyyy-mm-dd-hhmm.

If you are using multistage, instead of "deploy-" as a prefix, it'll use the current stage name like "production" or "staging" (but see below for fancier multi-stage workflow).

Ordinarily what's in your current git checkout will be tagged; but if you have set cap's :branch, it'll tag and deploy the HEAD of that branch even if that's not your current checkout.

You can customize the prefix and other aspects of tagging, both in your recipe and with command line over-rides, see cap -e git:tag for more info.

Multistage workflow

Are you using Capistrano's multistage extension? In one commonly desired multistage workflow (similar to what gitflow enforces):

• Under staging, you want automatic tagging with staging-yyyy-mm-dd-hhmm, just as above under 'Automatically tag on deploy'. Add to your config/deploy/staging.rb:

      before "deploy:update_code", "git:guard_committed", "git:guard_upstream", "git:tag"
  

• Under production, you want to take the most recent 'staging' tag, and promote it by deploying that tag to production, re-tagging with a "production-" tag. Maybe you also want to print out the commit log between the last production tag and what you're about to deploy, and require interactive confirmation. Add to your config/deploy/production.rb:

      before "deploy:update_code",  "git:commit_log", "git:retag"
      set :confirm_tag, true
  

Say you cap staging deploy on April 1 2012 at noon, your deploy will be tagged staging-2012-04-01-1200.

Say on April 2 at noon, you run cap production deploy

• you'll be a shown a commit log of changes between the previous production- commit and your most recent staging- commit, staging-2012-04-01-1200. (git:commit_log)
• You'll be asked to confirm, (set :confirm_tag, true)
• And then the deploy will happen, with new tag added production-2012-04-02-1200 (git:retag).
  • Note it's timestamped with date of production deploy. The commit message for the production- tag will say which staging- tag was retagged.

The git:retag task has some configurable options (in your recipe or on the individual command line invocation) too, see cap -e git:retag.

Make your own recipe

Look at cap -T git to see the tasks added by cap_git_tools. Run cap -e taskname to see expanded documentation info on each one, covering more specifics of what it does and what cap variables can alter it's behavior.

Some behaviors can be customized by 'capistrano variables'. These can be set in a recipe:

set :variable, "value"

Or set/over-ridden on the individual cap command line invocation:

cap deploy -s variable=value

Doesn't matter if you use cap '-s' or '-S', cap_git_tools tasks always lazily look up these values.

Other tools

cap git:commit_log to see the commits between the last tagged release and what you'd deploy now with cap deploy. Works in singlestage recipe, or multistage under 'cap staging git:commit_log' or 'cap production git:commit_log'.

cap git:show_tags to show the last 3 deploy tags, with meta information. Works in single stage recipe or multistage.

To Be Done

• Tag names are automatically created with a year-month-day-hour-minute timestamp. However, if you try to deploy again before the minute's changed on the clock, the tasks will try to re-tag using an already used name. You'll get an error and the task will abort, but the task could be written to catch this and add a suffix. But it ain't yet.

• There is some limited experimental functionality to change the format and add new components to the automatically created tag name, using a :tag_template variable. This theoretically allows the who and what components used by gitflow. But doing the 'right thing' in multistage (copying the 'what' from the previous tag, but regenerating the rest) is a bit tricky, and hasn't been done yet, which is what keeps this functionality limited and experimental at this point.

Let me know

Feedback, pull requests, complaints, welcome. Not sure if anyone's gonna use this.