capistrano 2.8.0 → 3.19.0

data/lib/capistrano/plugin.rb

@@ -0,0 +1,95 @@
+require "capistrano/all"
+require "rake/tasklib"
+
+# 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
+#
+class Capistrano::Plugin < Rake::TaskLib
+  include Capistrano::DSL
+
+  # 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
+  #
+  def set_defaults; 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
+  #
+  def register_hooks; end
+
+  # 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
+  #
+  def define_tasks; end
+
+  private
+
+  # 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.
+  def eval_rakefile(path)
+    contents = IO.read(path)
+    instance_eval(contents, path, 1)
+  end
+
+  # Convenience to access the current SSHKit backend outside of an `on` block.
+  def backend
+    SSHKit::Backend.current
+  end
+end

data/lib/capistrano/proc_helpers.rb

@@ -0,0 +1,13 @@
+module Capistrano
+  module ProcHelpers
+    module_function
+
+    # Tests whether the given object appears to respond to `call` with
+    # zero parameters. In Capistrano, such a proc is used to represent a
+    # "deferred value". That is, a value that is resolved by invoking `call` at
+    # the time it is first needed.
+    def callable_without_parameters?(x)
+      x.respond_to?(:call) && (!x.respond_to?(:arity) || x.arity.zero?)
+    end
+  end
+end

data/lib/capistrano/scm/git.rb

@@ -0,0 +1,105 @@
+require "capistrano/scm/plugin"
+require "cgi"
+require "securerandom"
+require "shellwords"
+require "uri"
+
+class Capistrano::SCM::Git < Capistrano::SCM::Plugin
+  def set_defaults
+    set_if_empty :git_shallow_clone, false
+    set_if_empty :git_wrapper_path, lambda {
+      # Use a unique name that won't collide with other deployments, and
+      # that cannot be guessed by other processes that have access to /tmp.
+      "#{fetch(:tmp_dir)}/git-ssh-#{SecureRandom.hex(10)}.sh"
+    }
+    set_if_empty :git_environmental_variables, lambda {
+      {
+        git_askpass: "/bin/echo",
+        git_ssh: fetch(:git_wrapper_path)
+      }
+    }
+    set_if_empty :git_max_concurrent_connections, 10
+    set_if_empty :git_wait_interval, 0
+  end
+
+  def register_hooks
+    after "deploy:new_release_path", "git:create_release"
+    before "deploy:check", "git:check"
+    before "deploy:set_current_revision", "git:set_current_revision"
+    before "deploy:set_current_revision_time", "git:set_current_revision_time"
+  end
+
+  def define_tasks
+    eval_rakefile File.expand_path("../tasks/git.rake", __FILE__)
+  end
+
+  def repo_mirror_exists?
+    backend.test " [ -f #{repo_path}/HEAD ] "
+  end
+
+  def check_repo_is_reachable
+    git :'ls-remote', git_repo_url, "HEAD"
+  end
+
+  def clone_repo
+    if (depth = fetch(:git_shallow_clone))
+      git :clone, "--mirror", "--depth", depth, "--no-single-branch", git_repo_url, repo_path.to_s
+    else
+      git :clone, "--mirror", git_repo_url, repo_path.to_s
+    end
+  end
+
+  def update_mirror
+    # Update the origin URL if necessary.
+    git :remote, "set-url", "origin", git_repo_url
+
+    # Note: Requires git version 1.9 or greater
+    if (depth = fetch(:git_shallow_clone))
+      git :fetch, "--depth", depth, "origin", fetch(:branch)
+    else
+      git :remote, :update, "--prune"
+    end
+  end
+
+  def verify_commit
+    git :"verify-commit", fetch_revision
+  end
+
+  def archive_to_release_path
+    if (tree = fetch(:repo_tree))
+      tree = tree.slice %r#^/?(.*?)/?$#, 1
+      components = tree.split("/").size
+      git :archive, fetch(:branch), tree, "| #{SSHKit.config.command_map[:tar]} -x --strip-components #{components} -f - -C", release_path
+    else
+      git :archive, fetch(:branch), "| #{SSHKit.config.command_map[:tar]} -x -f - -C", release_path
+    end
+  end
+
+  def fetch_revision
+    backend.capture(:git, "rev-list --max-count=1 #{fetch(:branch)}")
+  end
+
+  def fetch_revision_time
+    backend.capture(:git, "log -1 --pretty=format:\"%ct\" #{fetch(:branch)}")
+  end
+
+  def git(*args)
+    args.unshift :git
+    backend.execute(*args)
+  end
+
+  def git_repo_url
+    if fetch(:git_http_username) && fetch(:git_http_password)
+      URI.parse(repo_url).tap do |repo_uri|
+        repo_uri.user     = fetch(:git_http_username)
+        repo_uri.password = CGI.escape(fetch(:git_http_password))
+      end.to_s
+    elsif fetch(:git_http_username)
+      URI.parse(repo_url).tap do |repo_uri|
+        repo_uri.user = fetch(:git_http_username)
+      end.to_s
+    else
+      repo_url
+    end
+  end
+end

data/lib/capistrano/scm/hg.rb

@@ -0,0 +1,55 @@
+require "capistrano/scm/plugin"
+require "securerandom"
+
+class Capistrano::SCM::Hg < Capistrano::SCM::Plugin
+  def register_hooks
+    after "deploy:new_release_path", "hg:create_release"
+    before "deploy:check", "hg:check"
+    before "deploy:set_current_revision", "hg:set_current_revision"
+  end
+
+  def define_tasks
+    eval_rakefile File.expand_path("../tasks/hg.rake", __FILE__)
+  end
+
+  def hg(*args)
+    args.unshift(:hg)
+    backend.execute(*args)
+  end
+
+  def repo_mirror_exists?
+    backend.test " [ -d #{repo_path}/.hg ] "
+  end
+
+  def check_repo_is_reachable
+    hg "id", repo_url
+  end
+
+  def clone_repo
+    hg "clone", "--noupdate", repo_url, repo_path.to_s
+  end
+
+  def update_mirror
+    hg "pull"
+  end
+
+  def archive_to_release_path
+    if (tree = fetch(:repo_tree))
+      tree = tree.slice %r#^/?(.*?)/?$#, 1
+      components = tree.split("/").size
+      temp_tar = "#{fetch(:tmp_dir)}/#{SecureRandom.hex(10)}.tar"
+
+      hg "archive -p . -I", tree, "--rev", fetch(:branch), temp_tar
+
+      backend.execute :mkdir, "-p", release_path
+      backend.execute :tar, "-x --strip-components #{components} -f", temp_tar, "-C", release_path
+      backend.execute :rm, temp_tar
+    else
+      hg "archive", release_path, "--rev", fetch(:branch)
+    end
+  end
+
+  def fetch_revision
+    backend.capture(:hg, "log --rev #{fetch(:branch)} --template \"{node}\n\"")
+  end
+end

data/lib/capistrano/scm/plugin.rb

@@ -0,0 +1,13 @@
+require "capistrano/plugin"
+require "capistrano/scm"
+
+# Base class for all built-in and third-party SCM plugins. Notice that this
+# class doesn't really do anything other than provide an `scm?` predicate. This
+# tells Capistrano that the plugin provides SCM functionality. All other plugin
+# features are inherited from Capistrano::Plugin.
+#
+class Capistrano::SCM::Plugin < Capistrano::Plugin
+  def scm?
+    true
+  end
+end

data/lib/capistrano/scm/svn.rb

@@ -0,0 +1,56 @@
+require "capistrano/scm/plugin"
+
+class Capistrano::SCM::Svn < Capistrano::SCM::Plugin
+  def register_hooks
+    after "deploy:new_release_path", "svn:create_release"
+    before "deploy:check", "svn:check"
+    before "deploy:set_current_revision", "svn:set_current_revision"
+  end
+
+  def define_tasks
+    eval_rakefile File.expand_path("../tasks/svn.rake", __FILE__)
+  end
+
+  def svn(*args)
+    args.unshift(:svn)
+    args.push "--username #{fetch(:svn_username)}" if fetch(:svn_username)
+    args.push "--password #{fetch(:svn_password)}" if fetch(:svn_password)
+    args.push "--revision #{fetch(:svn_revision)}" if fetch(:svn_revision)
+    backend.execute(*args)
+  end
+
+  def repo_mirror_exists?
+    backend.test " [ -d #{repo_path}/.svn ] "
+  end
+
+  def check_repo_is_reachable
+    svn_username = fetch(:svn_username) ? "--username #{fetch(:svn_username)}" : ""
+    svn_password = fetch(:svn_password) ? "--password #{fetch(:svn_password)}" : ""
+    backend.test :svn, :info, repo_url, svn_username, svn_password
+  end
+
+  def clone_repo
+    svn :checkout, repo_url, repo_path.to_s
+  end
+
+  def update_mirror
+    # Switch the repository URL if necessary.
+    repo_mirror_url = fetch_repo_mirror_url
+    svn :switch, repo_url unless repo_mirror_url == repo_url
+    svn :update
+  end
+
+  def archive_to_release_path
+    svn :export, "--force", ".", release_path
+  end
+
+  def fetch_revision
+    backend.capture(:svnversion, repo_path.to_s)
+  end
+
+  def fetch_repo_mirror_url
+    backend.capture(:svn, :info, repo_path.to_s).each_line do |line|
+      return $1 if /\AURL: (.*)\n\z/ =~ line
+    end
+  end
+end

data/lib/capistrano/scm/tasks/git.rake

@@ -0,0 +1,84 @@
+# This trick lets us access the Git plugin within `on` blocks.
+git_plugin = self
+
+namespace :git do
+  desc "Upload the git wrapper script, this script guarantees that we can script git without getting an interactive prompt"
+  task :wrapper do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      execute :mkdir, "-p", File.dirname(fetch(:git_wrapper_path)).shellescape
+      upload! StringIO.new("#!/bin/sh -e\nexec /usr/bin/env ssh -o PasswordAuthentication=no -o StrictHostKeyChecking=no \"$@\"\n"), fetch(:git_wrapper_path)
+      execute :chmod, "700", fetch(:git_wrapper_path).shellescape
+    end
+  end
+
+  desc "Check that the repository is reachable"
+  task check: :'git:wrapper' do
+    fetch(:branch)
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      with fetch(:git_environmental_variables) do
+        git_plugin.check_repo_is_reachable
+      end
+    end
+  end
+
+  desc "Clone the repo to the cache"
+  task clone: :'git:wrapper' do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      if git_plugin.repo_mirror_exists?
+        info t(:mirror_exists, at: repo_path)
+      else
+        within deploy_path do
+          with fetch(:git_environmental_variables) do
+            git_plugin.clone_repo
+          end
+        end
+      end
+    end
+  end
+
+  desc "Update the repo mirror to reflect the origin state"
+  task update: :'git:clone' do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      within repo_path do
+        with fetch(:git_environmental_variables) do
+          git_plugin.update_mirror
+          git_plugin.verify_commit if fetch(:git_verify_commit)
+        end
+      end
+    end
+  end
+
+  desc "Copy repo to releases"
+  task create_release: :'git:update' do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      with fetch(:git_environmental_variables) do
+        within repo_path do
+          execute :mkdir, "-p", release_path
+          git_plugin.archive_to_release_path
+        end
+      end
+    end
+  end
+
+  desc "Determine the revision that will be deployed"
+  task :set_current_revision do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      within repo_path do
+        with fetch(:git_environmental_variables) do
+          set :current_revision, git_plugin.fetch_revision
+        end
+      end
+    end
+  end
+
+  desc "Determine the unix timestamp that the revision that will be deployed was created"
+  task :set_current_revision_time do
+    on release_roles(:all), in: :groups, limit: fetch(:git_max_concurrent_connections), wait: fetch(:git_wait_interval) do
+      within repo_path do
+        with fetch(:git_environmental_variables) do
+          set :current_revision_time, git_plugin.fetch_revision_time
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/scm/tasks/hg.rake

@@ -0,0 +1,53 @@
+# TODO: this is nearly identical to git.rake. DRY up?
+
+# This trick lets us access the Hg plugin within `on` blocks.
+hg_plugin = self
+
+namespace :hg do
+  desc "Check that the repo is reachable"
+  task :check do
+    on release_roles :all do
+      hg_plugin.check_repo_is_reachable
+    end
+  end
+
+  desc "Clone the repo to the cache"
+  task :clone do
+    on release_roles :all do
+      if hg_plugin.repo_mirror_exists?
+        info t(:mirror_exists, at: repo_path)
+      else
+        within deploy_path do
+          hg_plugin.clone_repo
+        end
+      end
+    end
+  end
+
+  desc "Pull changes from the remote repo"
+  task update: :'hg:clone' do
+    on release_roles :all do
+      within repo_path do
+        hg_plugin.update_mirror
+      end
+    end
+  end
+
+  desc "Copy repo to releases"
+  task create_release: :'hg:update' do
+    on release_roles :all do
+      within repo_path do
+        hg_plugin.archive_to_release_path
+      end
+    end
+  end
+
+  desc "Determine the revision that will be deployed"
+  task :set_current_revision do
+    on release_roles :all do
+      within repo_path do
+        set :current_revision, hg_plugin.fetch_revision
+      end
+    end
+  end
+end

data/lib/capistrano/scm/tasks/svn.rake

@@ -0,0 +1,53 @@
+# TODO: this is nearly identical to git.rake. DRY up?
+
+# This trick lets us access the Svn plugin within `on` blocks.
+svn_plugin = self
+
+namespace :svn do
+  desc "Check that the repo is reachable"
+  task :check do
+    on release_roles :all do
+      svn_plugin.check_repo_is_reachable
+    end
+  end
+
+  desc "Clone the repo to the cache"
+  task :clone do
+    on release_roles :all do
+      if svn_plugin.repo_mirror_exists?
+        info t(:mirror_exists, at: repo_path)
+      else
+        within deploy_path do
+          svn_plugin.clone_repo
+        end
+      end
+    end
+  end
+
+  desc "Pull changes from the remote repo"
+  task update: :'svn:clone' do
+    on release_roles :all do
+      within repo_path do
+        svn_plugin.update_mirror
+      end
+    end
+  end
+
+  desc "Copy repo to releases"
+  task create_release: :'svn:update' do
+    on release_roles :all do
+      within repo_path do
+        svn_plugin.archive_to_release_path
+      end
+    end
+  end
+
+  desc "Determine the revision that will be deployed"
+  task :set_current_revision do
+    on release_roles :all do
+      within repo_path do
+        set :current_revision, svn_plugin.fetch_revision
+      end
+    end
+  end
+end

data/lib/capistrano/scm.rb

@@ -0,0 +1,115 @@
+module Capistrano
+  # Base class for SCM strategy providers.
+  #
+  # @abstract
+  #
+  # @attr_reader [Rake] context
+  #
+  # @author Hartog de Mik
+  #
+  class SCM
+    attr_reader :context
+
+    # Provide a wrapper for the SCM that loads a strategy for the user.
+    #
+    # @param [Rake] context     The context in which the strategy should run
+    # @param [Module] strategy  A module to include into the SCM instance. The
+    #    module should provide the abstract methods of Capistrano::SCM
+    #
+    def initialize(context, strategy)
+      @context = context
+      singleton = class << self; self; end
+      singleton.send(:include, strategy)
+    end
+
+    # Call test in context
+    def test!(*args)
+      context.test(*args)
+    end
+
+    # The repository URL according to the context
+    def repo_url
+      context.repo_url
+    end
+
+    # The repository path according to the context
+    def repo_path
+      context.repo_path
+    end
+
+    # The release path according to the context
+    def release_path
+      context.release_path
+    end
+
+    # Fetch a var from the context
+    # @param [Symbol] variable The variable to fetch
+    # @param [Object] default  The default value if not found
+    #
+    def fetch(*args)
+      context.fetch(*args)
+    end
+
+    # @abstract
+    #
+    # Your implementation should check the existence of a cache repository on
+    # the deployment target
+    #
+    # @return [Boolean]
+    #
+    def test
+      raise NotImplementedError, "Your SCM strategy module should provide a #test method"
+    end
+
+    # @abstract
+    #
+    # Your implementation should check if the specified remote-repository is
+    # available.
+    #
+    # @return [Boolean]
+    #
+    def check
+      raise NotImplementedError, "Your SCM strategy module should provide a #check method"
+    end
+
+    # @abstract
+    #
+    # Create a (new) clone of the remote-repository on the deployment target
+    #
+    # @return void
+    #
+    def clone
+      raise NotImplementedError, "Your SCM strategy module should provide a #clone method"
+    end
+
+    # @abstract
+    #
+    # Update the clone on the deployment target
+    #
+    # @return void
+    #
+    def update
+      raise NotImplementedError, "Your SCM strategy module should provide a #update method"
+    end
+
+    # @abstract
+    #
+    # Copy the contents of the cache-repository onto the release path
+    #
+    # @return void
+    #
+    def release
+      raise NotImplementedError, "Your SCM strategy module should provide a #release method"
+    end
+
+    # @abstract
+    #
+    # Identify the SHA of the commit that will be deployed.  This will most likely involve SshKit's capture method.
+    #
+    # @return void
+    #
+    def fetch_revision
+      raise NotImplementedError, "Your SCM strategy module should provide a #fetch_revision method"
+    end
+  end
+end

data/lib/capistrano/setup.rb

@@ -0,0 +1,36 @@
+require "capistrano/doctor"
+require "capistrano/immutable_task"
+include Capistrano::DSL
+
+namespace :load do
+  task :defaults do
+    load "capistrano/defaults.rb"
+  end
+end
+
+require "airbrussh/capistrano"
+# We don't need to show the "using Airbrussh" banner announcement since
+# Airbrussh is now the built-in formatter. Also enable command output by
+# default; hiding the output might be confusing to users new to Capistrano.
+Airbrussh.configure do |airbrussh|
+  airbrussh.banner = false
+  airbrussh.command_output = true
+end
+
+stages.each do |stage|
+  Rake::Task.define_task(stage) do
+    set(:stage, stage.to_sym)
+
+    invoke "load:defaults"
+    Rake.application["load:defaults"].extend(Capistrano::ImmutableTask)
+    env.variables.untrusted! do
+      load deploy_config_path
+      load stage_config_path.join("#{stage}.rb")
+    end
+    configure_scm
+    I18n.locale = fetch(:locale, :en)
+    configure_backend
+  end
+end
+
+require "capistrano/dotfile"