Passing parameters to Capistrano

Update: For Capistrano 3, see scieslak's answer below.

---

Has jarrad has said, capistrano-ash is a good basic set of helper modules to deploy other project types, though it's not required as at the end of the day. It's just a scripting language and most tasks are done with the system commands and end up becoming almost shell script like.

To pass in parameters, you can set the -s flag when running cap to give you a key value pair. First create a task like this.

desc "Parameter Testing"
task :parameter do
  puts "Parameter test #{branch} #{tag}"
end

Then start your task like so.

cap test:parameter -s branch=master -s tag=1.0.0

For the last part. I would recommend setting up passwordless access using ssh keys to your server. But if you want to take it from the current logged in user. You can do something like this.

desc "Parameter Testing"
task :parameter do
  system("whoami", user)
  puts "Parameter test #{user} #{branch} #{tag}"
end

UPDATE: Edited to work with the latest versions of Capistrano. The configuration array is no longer available.

Global Parameters: See comments Use set :branch, fetch(:branch, 'a-default-value') to use parameters globally. (And pass them with -S instead.)

Update. Regarding passing parameters to Capistrano 3 task only.

I know this question is quite old but still pops up first on Google when searching for passing parameters to Capistrano task. Unfortunately, the fantastic answer provided by Jamie Sutherland is no longer valid with Capistrano 3. Before you waste your time trying it out except the results to be like below:

cap test:parameter -s branch=master 

outputs :

cap aborted!
OptionParser::AmbiguousOption: ambiguous option: -s
OptionParser::InvalidOption: invalid option: s

and

cap test:parameter -S branch=master 

outputs:

invalid option: -S

The valid answers for Capistrano 3 provided by @senz and Brad Dwyer you can find by clicking this gold link: Capistrano 3 pulling command line arguments

For completeness see the code below to find out about two option you have.

1st option:

You can iterate tasks with the key and value as you do with regular hashes:

desc "This task accepts optional parameters"

task :task_with_params, :first_param, :second_param do |task_name, parameter|
  run_locally do
    puts "Task name: #{task_name}"
    puts "First parameter: #{parameter[:first_param]}"
    puts "Second parameter: #{parameter[:second_param]}"
  end
end

Make sure there is no space between parameters when you call cap:

cap production task_with_params[one,two]

2nd option:

While you call any task, you can assign environmental variables and then call them from the code:

set :first_param, ENV['first_env'] || 'first default'
set :second_param, ENV['second_env'] || 'second default'

desc "This task accepts optional parameters"
task :task_with_env_params do
  run_locally do
    puts "First parameter: #{fetch(:first_param)}"
    puts "Second parameter: #{fetch(:second_param)}"
  end
end

To assign environmental variables, call cap like bellow:

cap production task_with_env_params first_env=one second_env=two

Hope that will save you some time.