class Capistrano::Plugin
IMPORTANT: The Capistrano::Plugin
system is not yet considered a stable, public API, and is subject to change without notice. Eventually it will be officially documented and supported, but for now, use it at your own risk.
Base class for Capistrano
plugins. Makes building a Capistrano
plugin as easy as writing a ‘Capistrano::Plugin` subclass and overriding any or all of its three template methods:
Within the plugin you can use any methods of the Rake or Capistrano
DSLs, like ‘fetch`, `invoke`, etc. In cases when you need to use SSHKit’s backend outside of an ‘on` block, use the `backend` convenience method. E.g. `backend.test`, `backend.execute`, or `backend.capture`.
Package up and distribute your plugin class as a gem and you’re good to go!
To use a plugin, all a user has to do is install it in the Capfile, like this:
# Capfile require "capistrano/superfancy" install_plugin Capistrano::Superfancy
Or, to install the plugin without its hooks:
# Capfile require "capistrano/superfancy" install_plugin Capistrano::Superfancy, load_hooks: false
Public Instance Methods
Implemented by subclasses to define Rake tasks. Typically a plugin will call ‘eval_rakefile` to load Rake tasks from a separate .rake file.
Example:
def define_tasks eval_rakefile File.expand_path("../tasks.rake", __FILE__) end
For simple tasks, you can define them inline. No need for a separate file.
def define_tasks desc "Do something fantastic." task "my_plugin:fantastic" do ... end end
# File lib/capistrano/plugin.rb, line 79 def define_tasks; end
Implemented by subclasses to hook into Capistrano’s deployment flow using using the ‘before` and `after` DSL methods. Note that `register_hooks` will not be called if the user has opted-out of hooks when installing the plugin.
Example:
def register_hooks after "deploy:updated", "my_plugin:do_something" end
# File lib/capistrano/plugin.rb, line 59 def register_hooks; end
Implemented by subclasses to provide default values for settings needed by this plugin. Typically done using the ‘set_if_empty` Capistrano
DSL method.
Example:
def set_defaults set_if_empty :my_plugin_option, true end
# File lib/capistrano/plugin.rb, line 47 def set_defaults; end
Private Instance Methods
Convenience to access the current SSHKit backend outside of an ‘on` block.
# File lib/capistrano/plugin.rb, line 92 def backend SSHKit::Backend.current end
Read and eval a .rake file in such a way that ‘self` within the .rake file refers to this plugin instance. This gives the tasks in the file access to helper methods defined by the plugin.
# File lib/capistrano/plugin.rb, line 86 def eval_rakefile(path) contents = IO.read(path) instance_eval(contents, path, 1) end