View on GitHub


Test Coverage
title: Role filtering
layout: default

You may have situations where you only want to deploy to servers matching
a single role. For example, you may have changed some aspect of how the web
role works, but don't want to trigger a deployment to your database servers.

You can use the *role filter* to restrict Capistrano tasks to only servers
match a given role or roles.

If the filter matches no servers, no actions will be taken.

If you specify a filter, it will match any servers that have that role, and
it will run _all_ tasks for each of the roles that server has. For example,
if you filtered for servers with the `web` role, and a server had both the
`web` and `db` role, both the `web` and `db` role tasks would be executed on it.

### Specifying a role filter

There are three ways to specify the role filter.

#### Environment variable

Capistrano will read the role filter from the environment variable `ROLES`
if it is set. You can set it inline:

ROLES=app,web cap production deploy

Specify multiple roles by separating them with a comma.

#### In configuration

You can set the role filter inside your deploy configuration. For example,
you can set the following inside `config/deploy.rb`:

set :filter, :roles => %w{app web}

Note that you specify the filter as an array rather than as a comma-separated
list of roles when using this method.

Note that the keyname `:role` is also supported.

#### On the command line

In a similar way to using the environment variable, you can set the role
filter by specifying it as a command line argument to `cap`:

cap --roles=app,web production deploy

Like the environment variable method, specify multiple roles by separating them
with a comma.

### Using Regular Expressions

Since role names are Ruby symbols they can legitimately contain any characters. However to
allow multiple of them to be specified on one line we use the comma as a separator.

To use a regular expression for a role filter begin and end the string with '/'. Because
of the above these regular expressions may not contain a comma.