This article explains how to deploy with Capistrano 2.x. If you are using Capistrano 3.x, please refer to the current Capistrano documentation instead.

To prepare your project for Capistrano, go into the root directory of that project and run capify:

cd my_project
capify .

Set up SSH keys

To be able to deploy, your server needs to be able to access your repos. Check out this guide to get that set up.

Settings

Here are the 5 most notable Capistrano config options (found in deploy.rb):

default_run_options[:pty] = true  # Must be set for the password prompt
                                  # from git to work
set :repository, "git@github.com:user/repo.git"  # Your clone URL
set :scm, "git"
set :user, "deployer"  # The server's user for deploys
set :scm_passphrase, "p@ssw0rd"  # The deploy user's password

Agent Forwarding

If you're using your own private keys for git, you want to tell Capistrano to use agent forwarding with this command. Agent forwarding can make key management much simpler as it uses your local keys instead of keys installed on the server.

set :ssh_options, { :forward_agent => true }

Want to know more? Check out this guide for more information on SSH agent forwarding.

Set Branch

You need to tell cap the branch to checkout during deployment:

set :branch, "master"

Remote Cache

In most cases you want to use this option, otherwise each deploy will do a full repository clone every time.

set :deploy_via, :remote_cache

Remote caching will keep a local git repository on the server you're deploying to and simply run a fetch from that rather than an entire clone. This is probably the best option as it will only fetch the changes since the last deploy.

Shallow Clone

As an alternative to the remote cache approach, you can use shallow cloning.

set :git_shallow_clone, 1

Shallow cloning will do a clone each time, but will only get the top commit, not the entire repository history. Be warned, shallow clone won't work well with the set :branch option.

Submodules

If you're using git submodules you must tell cap to fetch them.

set :git_enable_submodules, 1

Known Hosts bug

If you are not using agent forwarding, the first time you deploy may fail due to Capistrano not prompting with this message:

# The authenticity of host 'github.com (207.97.227.239)' can't be established.
# RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
# Are you sure you want to continue connecting (yes/no)?

To fix this, ssh into your server as the user you will deploy with, run ssh git@github.com and confirm the prompt. If that does not solve the problem, consult Capistrano's documentation.