# Capistrano: SSH Deployment Automation for Ruby Projects

> Capistrano is a Ruby framework for scripting deployments over SSH, built around Rake tasks, server roles and a fixed release directory layout. It is a good fit for teams that already deploy by hand over SSH and want that process repeated the same way every time.

**capistrano/capistrano** — A deployment automation tool built on Ruby, Rake, and SSH.

- Repository: https://github.com/capistrano/capistrano
- Website: http://www.capistranorb.com
- Stars: 13,007 · Forks: 1,738
- Language: Ruby
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/capistrano-capistrano

## What Capistrano automates, and for whom

Capistrano targets a specific gap: deployments that are already a known sequence of SSH commands, but that live in someone's shell history instead of in a repository. The README describes the tool as sitting between "simple rsync bash scripts" and "complex containerized toolchains", and states plainly that it "automates what you already know how to do manually with SSH, but in a repeatable, scalable fashion. There is no magic here!" That sentence is the honest summary of the project's scope.

The audience follows from that. You need to be comfortable SSH-ing into a Linux box and working on the command line, because every task ultimately becomes an SSH command. Although Capistrano is written in Ruby, the README says it can deploy projects of any language or framework, including Rails, Java and PHP. What it does not do is equally important: it does not provision servers, and it does not know how to execute your application once the code is in place. Restarting a process, reloading a web server or running a migration is something you write, or something you take from a community gem.

## Roles, stages and the release directory

The mechanism is a Rake task graph executed over SSH. You tag each server with one or more roles, then attach tasks to those roles, so the same deployment definition can address a database server, an app server and a worker differently. Stages parameterize the same definition for environments such as qa, staging and production, which means you only specify what differs between them, typically addresses. Tasks run concurrently across a fleet, and the README notes that connection pooling is used for speed.

The README's task example shows the shape of the API: a task named restart_sidekiq calls on roles(:worker) and within that block calls execute :service, "sidekiq restart", and a hook then attaches it after "deploy:published". That is the whole model in miniature. You are not writing a plugin against an internal API; you are writing Rake tasks that emit shell commands against role-scoped server lists.

The conventions are the other half. Capistrano defines a standard deployment process and a standard place for deployed files, so you do not decide how to structure scripts or where releases land. The docs directory and the features directory in the repository are where the longer-form specification of that process lives; the README itself only sketches it.

## Installing Capistrano and running a first deploy

Capistrano is distributed as a Ruby gem. The README's quick start adds it to the project Gemfile inside the development group with require: false, which keeps it out of the application's runtime load path. The README uses the constraint "~> 3.17" in that example; the current release line is 3.20, so pin to whatever your team has verified.

```ruby
group :development do
  gem "capistrano", "~> 3.17", require: false
end
```

Then install it through Bundler:

```sh
$ bundle install
```

Before running the installer, make sure the project does not already contain a Capfile or capfile. Then run the install task:

```sh
$ bundle exec cap install
```

According to the README, this generates a Capfile, config/deploy.rb, config/deploy/production.rb, config/deploy/staging.rb and a lib/capistrano/tasks directory. Those two stages are the default; the README shows STAGES=local,sandbox,qa,production as the way to choose different ones. The README is explicit that the generated files are templates to get you started, not finished configuration.

Once stages and roles are configured, the everyday command is the one from the README's opening example:

```sh
$ cd my-capistrano-enabled-project
$ cap production deploy
```

What you should see is Capistrano connecting to the servers listed for the production stage over SSH and running the deployment task graph there. If nothing appears to happen, the first thing to check is that key-based SSH to those hosts works without a password prompt, because that is a stated prerequisite.

## Where Capistrano is the wrong tool

The gotchas section is unusually candid, and it is the part worth reading before adopting anything. Four constraints stand out.

First, Capistrano is not a provisioning tool. It has no requirements beyond SSH, but your application probably needs database software, a web server and a language runtime, and installing those is outside its scope. If your servers are not already built, Capistrano is the second problem, not the first.

Second, it assumes key-based, password-less SSH. That is a hard prerequisite, not a preference.

Third, it is designed around a single non-privileged SSH user in a non-interactive session. The README says deployments requiring sudo, interactive prompts, or authenticating as one user while running commands as another can probably be accomplished, but may be difficult. Read that as: the tool will fight you, and the friction is architectural rather than a missing flag.

Fourth, the shell matters. Capistrano 3 expects a POSIX shell such as Bash or Sh, and the README states that tcsh and csh may work but probably will not. If your fleet is standardized on a non-POSIX shell, this is not a configuration problem you can paper over.

There is also the blank space after the deploy. Out of the box Capistrano can get code onto servers, but it does not know how to execute it. Whether foreman needs to run or Apache needs a restart is knowledge you supply.

## How Capistrano differs from configuration management and image builds

The closest comparison in the README's own framing is a hand-written rsync script, and the difference there is conventions plus roles: the script does one thing to one host, while Capistrano parameterizes the same definition across stages and runs tasks concurrently across role-tagged servers.

A more useful contrast is with configuration management tools such as Ansible, Chef or Puppet. Those describe the desired state of a machine and converge it there, which is why they cover package installation, users, services and file templates. Capistrano describes a sequence of commands to run against machines that already exist and are already configured. It pushes a release and runs your hooks; it does not decide what a correct server looks like. Teams often run both, using configuration management for the box and Capistrano for the release.

The other contrast is with container image builds. A Dockerfile bakes the application into an immutable artifact and the deploy becomes a pull and a restart. Capistrano deploys into a directory structure on a long-lived host and expects the SCM binary (git, hg or svn) to be present on the server so it can check the code out. That is a meaningful difference in operational model: with containers the server is disposable, with Capistrano the server is a pet you keep deploying to. The repository does ship a docker-compose.yml that builds an SSH server from the .docker directory and maps port 2022 to 22, which is a test fixture for exercising deploys against a throwaway host rather than a production deployment pattern.

## Maintenance, upgrades and the MIT licence

The last push to the default branch was on 2026-07-19, and the most recent release listed is v3.20.1 from 2026-05-16, following v3.20.0 in December 2025 and v3.19.2 in November 2024. The repository is not archived. That release cadence matters for planning: the gap between 3.19.2 and 3.20.0 is roughly thirteen months, so this is a mature project that moves deliberately rather than a fast-moving one.

Upgrade cost is concentrated in the major version boundary. The repository carries an UPGRADING-3.7.md file at the top level, and the README points readers of the older line to a separate 2.x documentation archive. If you are on Capistrano 2, the move to 3.x is a rewrite of your task definitions, not a version bump. Within 3.x the changelog is the place to check before moving between minor versions, since task libraries in the community ecosystem may lag behind a release.

Capistrano is MIT licensed, which is permissive and places few obligations on how you use or redistribute it. That covers Capistrano itself. Community task gems are separate packages with their own licences, and the README's claim that many Ruby projects ship Capistrano tasks built-in does not tell you anything about the terms of those tasks. Check each one you add.

## Conclusion

Adopt Capistrano if your deploys are already a sequence of SSH commands and you want them in version control with roles and stages. Do not adopt it if you need provisioning, sudo-heavy steps or interactive prompts, or if you are not comfortable on a Linux command line. Before rolling it out, verify key-based SSH works non-interactively to every target server and that the SCM binary (git, hg or svn) is installed there, then run bundle exec cap install and confirm the generated Capfile, config/deploy.rb and config/deploy/production.rb match your layout.

## FAQ

### What is Capistrano?

It is a deployment automation framework built on Ruby, Rake and SSH, distributed as a gem. You write Rake tasks that run shell commands on role-tagged servers, and the cap command executes them for a chosen stage.

### What is Capistrano used for?

It automates deployments you would otherwise perform by hand over SSH, giving them a standard release layout, stages such as staging and production, server roles and parallel execution across a fleet.

### How do I install Capistrano in a Ruby project?

Add the capistrano gem to your Gemfile in the development group with require: false, run bundle install, then run bundle exec cap install to generate the Capfile and config/deploy files.

### Does Capistrano provision servers or install software on them?

No. The README lists provisioning as a gotcha and states that server provisioning steps are not done by Capistrano, which assumes the supporting software is already in place.

### Can Capistrano deploy non-Ruby applications?

Yes. The README says that although Capistrano is written in Ruby, it can be used to deploy projects of any language or framework, naming Rails, Java and PHP as examples.

## Sources

- [capistrano/capistrano on GitHub](https://github.com/capistrano/capistrano)
- [License: MIT](https://github.com/capistrano/capistrano/blob/master/LICENSE)
- [Project website](http://www.capistranorb.com)
- [README](https://github.com/capistrano/capistrano/blob/master/README.md)
- [Releases](https://github.com/capistrano/capistrano/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/capistrano-capistrano