Class: Capistrano::Plugin

Inherits:
Rake::TaskLib
  • Object
show all
Includes:
DSL
Defined in:
lib/capistrano/plugin.rb

Overview

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:

  • set_defaults

  • register_hooks

  • define_tasks

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

Direct Known Subclasses

SCM::Plugin

Instance Method Summary collapse

Methods included from DSL

#execute, #invoke, #invoke!, #local_user, #lock, #on, #revision_log_message, #rollback_log_message, #run_locally, #scm, #sudo, #t

Methods included from DSL::Stages

#stage_definitions, #stage_set?, #stages

Methods included from DSL::Paths

#asset_timestamp, #current_path, #deploy_config_path, #deploy_path, #deploy_to, #join_paths, #linked_dir_parents, #linked_dirs, #linked_file_dirs, #linked_files, #map_dirnames, #now, #release_path, #releases_path, #repo_path, #repo_url, #revision_log, #set_release_path, #shared_path, #stage_config_path

Methods included from DSL::Env

#asset_timestamp, #env, #release_roles, #release_timestamp, #role_properties, #roles

Methods included from TaskEnhancements

#after, #before, #default_tasks, #define_remote_file_task, #deploying?, #ensure_stage, #exit_deploy_because_of_exception, #tasks_without_stage_dependency

Instance Method Details

#define_tasks ⇒ Object

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



79
 
# File 'lib/capistrano/plugin.rb', line 79

def define_tasks; end

#register_hooks ⇒ Object

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



59
 
# File 'lib/capistrano/plugin.rb', line 59

def register_hooks; end

#set_defaults ⇒ Object

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



47
 
# File 'lib/capistrano/plugin.rb', line 47

def set_defaults; end