bolt 3.24.0 → 3.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ad3bbc9413aac278feeac8a7e31173bd065f0029fb211d7e1906c4803a4c390
-  data.tar.gz: 387d3a07844139eb29a1db06d1792acfdad6a09eab2b5576a9c4d34fdffdaca8
+  metadata.gz: fe3e07dae1f3e80d3b4ade7c9d78749f54c592e246b2fd82e6264ab908b8baa1
+  data.tar.gz: 44af49cb408f92496c9795d892bc2e43e04788dd6ead42070a04e258958f00ac
 SHA512:
-  metadata.gz: 83c1685fc238f049dad5cf841ea55f37c57a1aa59d66ef420d754b78d7b0ba8cca4533accb2cfbe53915587f1832beb7cbf956501486de63e135933b57f5fa98
-  data.tar.gz: c6900fde1fd9234a603171c79c2f2b3a22b2d2661797b94bf0afd2050f4ef5cc32844562734d3e41bd94464806e1efaabaac346d6887773f547c801c33cc3d6f
+  metadata.gz: 0d158d8a0d8c72c99a34464ad4de0df9e7b04a83b1509b048c5b650baccbea9a06f99dfd512bfc8bdc91f5065e22148b76814a895766717bfe9f2c34bd81e55f
+  data.tar.gz: eca8af5592551ff9a273ad508831f9a1e07edf0327aa29dcc7078e5fb44743033c92388d79ab22ae2d3c5ea9574984b0c50849544159ab8dd32c2090a0dad939

data/Puppetfile

@@ -6,7 +6,7 @@ moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
 mod 'puppetlabs-service', '2.2.0'
-mod 'puppetlabs-puppet_agent', '4.11.0'
+mod 'puppetlabs-puppet_agent', '4.12.1'
 mod 'puppetlabs-facts', '1.4.0'
 
 # Core types and providers for Puppet 6
@@ -23,13 +23,16 @@ mod 'puppetlabs-zone_core', '1.0.3'
 
 # Useful additional modules
 mod 'puppetlabs-package', '2.2.0'
-mod 'puppetlabs-powershell_task_helper', '0.1.0'
 mod 'puppetlabs-puppet_conf', '1.3.0'
-mod 'puppetlabs-python_task_helper', '0.5.0'
 mod 'puppetlabs-reboot', '4.2.0'
+mod 'puppetlabs-stdlib', '8.4.0'
+
+# Task helpers
+mod 'puppetlabs-powershell_task_helper', '0.1.0'
 mod 'puppetlabs-ruby_task_helper', '0.6.1'
 mod 'puppetlabs-ruby_plugin_helper', '0.2.0'
-mod 'puppetlabs-stdlib', '8.2.0'
+mod 'puppetlabs-python_task_helper', '0.5.0'
+mod 'puppetlabs-bash_task_helper', '2.0.0'
 
 # Plugin modules
 mod 'puppetlabs-aws_inventory', '0.7.0'

data/bolt-modules/boltlib/lib/puppet/datatypes/applyresult.rb

@@ -12,11 +12,20 @@
 #   keys](applying_manifest_blocks.md#result-keys).
 # @param target
 #   The target the result is from.
+# @param error
+#   An Error object constructed from the `_error` field of the result's value.
+# @param catalog
+#   The Puppet catalog used to configure the target. The catalog describes the
+#   desired state of the target. The catalog is masked with the `Sensitive` data
+#   type to protect any sensitive information in the catalog from being printed
+#   to the console or logs. Using this function automatically unwraps the
+#   catalog. For more information about catalogs and the catalog compilation
+#   process, see [Catalog
+#   compilation](https://puppet.com/docs/puppet/latest/subsystem_catalog_compilation.html).
+
 #
 # @!method action
 #   The action performed. `ApplyResult.action` always returns the string `apply`.
-# @!method error
-#   Returns an Error object constructed from the `_error` field of the result's value.
 # @!method message
 #   The `_output` field of the result's value.
 # @!method ok
@@ -30,10 +39,11 @@ Puppet::DataTypes.create_type('ApplyResult') do
   interface <<-PUPPET
     attributes => {
       'report' => Hash[String[1], Data],
-      'target' => Target
+      'target' => Target,
+      'error' => Optional[Error],
+      'catalog' => Optional[Hash]
     },
     functions => {
-      error => Callable[[], Optional[Error]],
       ok => Callable[[], Boolean],
       message => Callable[[], Optional[String]],
       action => Callable[[], String],

data/lib/bolt/applicator.rb

@@ -280,7 +280,6 @@ module Bolt
                   result
                 end
               else
-
                 arguments = {
                   'catalog' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(catalog),
                   'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins),
@@ -291,7 +290,7 @@ module Bolt
 
                 callback = proc do |event|
                   if event[:type] == :node_result
-                    event = event.merge(result: ApplyResult.from_task_result(event[:result]))
+                    event = event.merge(result: ApplyResult.from_task_result(event[:result], catalog))
                   end
                   @executor.publish_event(event)
                 end
@@ -299,7 +298,7 @@ module Bolt
                 options[:run_as] = @executor.run_as if @executor.run_as && !options.key?(:run_as)
 
                 results = transport.batch_task(batch, catalog_apply_task, arguments, options, &callback)
-                Array(results).map { |result| ApplyResult.from_task_result(result) }
+                Array(results).map { |result| ApplyResult.from_task_result(result, catalog) }
               end
             end
           end

data/lib/bolt/apply_result.rb

@@ -65,23 +65,30 @@ module Bolt
       end
     end
 
-    def self.from_task_result(result)
+    def self.from_task_result(result, catalog = nil)
       if (puppet_missing = puppet_missing_error(result))
         new(result.target,
             error: puppet_missing,
-            report: result.value.reject { |k| k == '_error' })
+            report: result.value.reject { |k| k == '_error' },
+            catalog: catalog)
       elsif !result.ok?
-        new(result.target, error: result.error_hash)
+        new(result.target,
+            error: result.error_hash,
+            catalog: catalog)
       elsif (invalid_report = invalid_report_error(result))
         new(result.target,
             error: invalid_report,
-            report: result.value.reject { |k| %w[_error _output].include?(k) })
+            report: result.value.reject { |k| %w[_error _output].include?(k) },
+            catalog: catalog)
       elsif (resource_error = resource_error(result))
         new(result.target,
             error: resource_error,
-            report: result.value.reject { |k| k == '_error' })
+            report: result.value.reject { |k| k == '_error' },
+            catalog: catalog)
       else
-        new(result.target, report: result.value)
+        new(result.target,
+            report: result.value,
+            catalog: catalog)
       end
     end
 
@@ -89,16 +96,21 @@ module Bolt
     def _pcore_init_hash
       { 'target' => @target,
         'error' => value['_error'],
-        'report' => value['report'] }
+        'report' => value['report'],
+        'catalog' => catalog }
     end
 
-    def initialize(target, error: nil, report: nil)
+    def initialize(target, error: nil, report: nil, catalog: nil)
       @target = target
       @value = {}
       @action = 'apply'
       @value['report'] = report if report
       @value['_error'] = error if error
       @value['_output'] = metrics_message if metrics_message
+
+      if catalog
+        @value['_sensitive'] = Puppet::Pops::Types::PSensitiveType::Sensitive.new({ 'catalog' => catalog })
+      end
     end
 
     def event_metrics
@@ -131,6 +143,10 @@ module Bolt
       @value['report']
     end
 
+    def catalog
+      sensitive.unwrap['catalog'] if sensitive
+    end
+
     def generic_value
       {}
     end

data/lib/bolt/inventory/group.rb

@@ -10,8 +10,10 @@ module Bolt
     class Group
       attr_accessor :name, :groups
 
-      # Regex used to validate group names and target aliases.
-      NAME_REGEX = /\A[a-z0-9_][a-z0-9_-]*\Z/.freeze
+      # Illegal characters that are not permitted in group names or aliases.
+      # These characters are delimiters for target and group names and allowing
+      # them would cause unexpected behavior.
+      ILLEGAL_CHARS = /[\s,]/.freeze
 
       # NOTE: All keys should have a corresponding schema property in schemas/bolt-inventory.schema.json
       DATA_KEYS = %w[config facts vars features plugin_hooks].freeze
@@ -41,7 +43,10 @@ module Bolt
         @name = @plugins.resolve_references(input['name'])
 
         raise ValidationError.new("Group name must be a String, not #{@name.inspect}", nil) unless @name.is_a?(String)
-        raise ValidationError.new("Invalid group name #{@name}", @name) unless @name =~ NAME_REGEX
+
+        if (illegal_char = @name.match(ILLEGAL_CHARS))
+          raise ValidationError.new("Illegal character '#{illegal_char}' in group name '#{@name}'", @name)
+        end
 
         validate_group_input(input)
 
@@ -167,7 +172,9 @@ module Bolt
 
       def insert_alia(target_name, aliases)
         aliases.each do |alia|
-          raise ValidationError.new("Invalid alias #{alia}", @name) unless alia =~ NAME_REGEX
+          if (illegal_char = alia.match(ILLEGAL_CHARS))
+            raise ValidationError.new("Illegal character '#{illegal_char}' in alias '#{alia}'", @name)
+          end
 
           if (found = @aliases[alia])
             raise ValidationError.new(alias_conflict(alia, found, target_name), @name)

data/lib/bolt/inventory/target.rb

@@ -8,6 +8,11 @@ module Bolt
     class Target
       attr_reader :name, :uri, :safe_name, :target_alias, :resources
 
+      # Illegal characters that are not permitted in target names.
+      # These characters are delimiters for target and group names and allowing
+      # them would cause unexpected behavior.
+      ILLEGAL_CHARS = /[\s,]/.freeze
+
       def initialize(target_data, inventory)
         unless target_data['name'] || target_data['uri']
           raise Bolt::Inventory::ValidationError.new("Target must have either a name or uri", nil)
@@ -150,6 +155,10 @@ module Bolt
           raise Bolt::Inventory::ValidationError.new("Target name must be ASCII characters: #{@name}", nil)
         end
 
+        if (illegal_char = @name.match(ILLEGAL_CHARS))
+          raise ValidationError.new("Illegal character '#{illegal_char}' in target name '#{@name}'", nil)
+        end
+
         unless transport.nil? || Bolt::TRANSPORTS.include?(transport.to_sym)
           raise Bolt::UnknownTransportError.new(transport, uri)
         end

data/lib/bolt/module_installer/resolver.rb

@@ -49,7 +49,7 @@ module Bolt
             spec_searcher_configuration: spec_searcher_config(config)
           )
         rescue StandardError => e
-          raise Bolt::Error.new(e.message, 'bolt/module-resolver-error')
+          raise Bolt::Error.new("Unable to resolve modules: #{e.message}", 'bolt/module-resolver-error')
         end
 
         # Create the Puppetfile object.

data/lib/bolt/module_installer/specs/git_spec.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'net/http'
+require 'open3'
 require 'set'
 
 require_relative '../../../bolt/error'
+require_relative '../../../bolt/logger'
+require_relative '../../../bolt/module_installer/specs/id/gitclone'
+require_relative '../../../bolt/module_installer/specs/id/github'
+require_relative '../../../bolt/module_installer/specs/id/gitlab'
 
 # This class represents a Git module specification.
 #
@@ -17,12 +23,19 @@ module Bolt
 
         attr_reader :git, :ref, :resolve, :type
 
-        def initialize(init_hash)
-          @resolve    = init_hash.key?('resolve') ? init_hash['resolve'] : true
-          @name       = parse_name(init_hash['name'])
-          @git, @repo = parse_git(init_hash['git'])
-          @ref        = init_hash['ref']
-          @type       = :git
+        def initialize(init_hash, config = {})
+          @logger  = Bolt::Logger.logger(self)
+          @resolve = init_hash.key?('resolve') ? init_hash['resolve'] : true
+          @git     = init_hash['git']
+          @ref     = init_hash['ref']
+          @name    = parse_name(init_hash['name'])
+          @proxy   = config.dig('proxy')
+          @type    = :git
+
+          unless @resolve == true || @resolve == false
+            raise Bolt::ValidationError,
+                  "Option 'resolve' for module spec #{@git} must be a Boolean"
+          end
 
           if @name.nil? && @resolve == false
             raise Bolt::ValidationError,
@@ -30,9 +43,9 @@ module Bolt
                   "must include a 'name' key when 'resolve' is false."
           end
 
-          unless @resolve == true || @resolve == false
+          unless valid_url?(@git)
             raise Bolt::ValidationError,
-                  "Option 'resolve' for module spec #{@git} must be a Boolean"
+                  "Invalid URI #{@git}. Valid URIs must begin with 'git@', 'http://', or 'https://'."
           end
         end
 
@@ -57,22 +70,6 @@ module Bolt
           match[:name]
         end
 
-        # Gets the repo from the git URL.
-        #
-        private def parse_git(git)
-          return [git, nil] unless @resolve
-
-          repo = if git.start_with?('git@github.com:')
-                   git.split('git@github.com:').last.split('.git').first
-                 elsif git.start_with?('https://github.com')
-                   git.split('https://github.com/').last.split('.git').first
-                 else
-                   raise Bolt::ValidationError, invalid_git_msg(git)
-                 end
-
-          [git, repo]
-        end
-
         # Returns true if the specification is satisfied by the module.
         #
         def satisfied_by?(mod)
@@ -88,14 +85,6 @@ module Bolt
           }
         end
 
-        # Returns an error message that the provided repo is not a git repo or
-        # is private.
-        #
-        private def invalid_git_msg(repo_name)
-          "#{repo_name} is not a public GitHub repository. See https://pup.pt/no-resolve "\
-            "for information on how to install this module."
-        end
-
         # Returns a PuppetfileResolver::Model::GitModule object for resolving.
         #
         def to_resolver_module
@@ -107,90 +96,53 @@ module Bolt
           end
         end
 
-        # Resolves the module's title from the module metadata. This is lazily
-        # resolved since Bolt does not always need to know a Git module's name.
+        # Returns the module's name.
         #
         def name
-          @name ||= begin
-            url      = "https://raw.githubusercontent.com/#{@repo}/#{sha}/metadata.json"
-            response = make_request(:Get, url)
-
-            case response
-            when Net::HTTPOK
-              body = JSON.parse(response.body)
-
-              unless body.key?('name')
-                raise Bolt::Error.new(
-                  "Missing name in metadata.json at #{git}. This is not a valid module.",
-                  "bolt/missing-module-name-error"
-                )
-              end
-
-              parse_name(body['name'])
-            else
-              raise Bolt::Error.new(
-                "Missing metadata.json at #{git}. This is not a valid module.",
-                "bolt/missing-module-metadata-error"
-              )
-            end
-          end
+          @name ||= parse_name(id.name)
         end
 
-        # Resolves the SHA for the specified ref. This is lazily resolved since
-        # Bolt does not always need to know a Git module's SHA.
+        # Returns the SHA for the module's ref.
         #
         def sha
-          @sha ||= begin
-            url      = "https://api.github.com/repos/#{@repo}/commits/#{ref}"
-            headers  = ENV['GITHUB_TOKEN'] ? { "Authorization" => "token #{ENV['GITHUB_TOKEN']}" } : {}
-            response = make_request(:Get, url, headers)
-
-            case response
-            when Net::HTTPOK
-              body = JSON.parse(response.body)
-              body['sha']
-            when Net::HTTPUnauthorized
-              raise Bolt::Error.new(
-                "Invalid token at GITHUB_TOKEN, unable to resolve git modules.",
-                "bolt/invalid-git-token-error"
-              )
-            when Net::HTTPForbidden
-              message = "GitHub API rate limit exceeded, unable to resolve git modules. "
-
-              unless ENV['GITHUB_TOKEN']
-                message += "To increase your rate limit, set the GITHUB_TOKEN environment "\
-                          "variable with a GitHub personal access token."
-              end
-
-              raise Bolt::Error.new(message, 'bolt/github-api-rate-limit-error')
-            when Net::HTTPNotFound
-              raise Bolt::Error.new(invalid_git_msg(git), "bolt/missing-git-repository-error")
-            else
+          id.sha
+        end
+
+        # Gets the ID for the module based on the specified ref and git URL.
+        # This is lazily resolved since Bolt does not always need this information,
+        # and requesting it is expensive.
+        #
+        private def id
+          @id ||= begin
+            # The request methods here return an ID object if the module name and SHA
+            # were found and nil otherwise. This lets Bolt try multiple methods for
+            # finding the module name and SHA, and short circuiting as soon as it does.
+            module_id = Bolt::ModuleInstaller::Specs::ID::GitHub.request(@git, @ref, @proxy) ||
+                        Bolt::ModuleInstaller::Specs::ID::GitLab.request(@git, @ref, @proxy) ||
+                        Bolt::ModuleInstaller::Specs::ID::GitClone.request(@git, @ref, @proxy)
+
+            unless module_id
               raise Bolt::Error.new(
-                "Ref #{ref} at #{git} is not a commit, tag, or branch.",
-                "bolt/invalid-git-ref-error"
+                "Unable to locate metadata and calculate SHA for ref #{@ref} at #{@git}. This may "\
+                "not be a valid module. For more information about how Bolt attempted to locate "\
+                "this information, check the debugging logs.",
+                'bolt/missing-module-metadata-error'
               )
             end
+
+            module_id
           end
         end
 
-        # Makes a generic HTTP request.
+        # Returns true if the URL is valid.
         #
-        private def make_request(verb, url, headers = {})
-          require 'net/http'
-
-          uri      = URI.parse(url)
-          opts     = { use_ssl: uri.scheme == 'https' }
+        private def valid_url?(url)
+          return true if url.start_with?('git@')
 
-          Net::HTTP.start(uri.host, uri.port, opts) do |client|
-            request = Net::HTTP.const_get(verb).new(uri, headers)
-            client.request(request)
-          end
-        rescue StandardError => e
-          raise Bolt::Error.new(
-            "Failed to connect to #{uri}: #{e.message}",
-            "bolt/http-connect-error"
-          )
+          uri = URI.parse(url)
+          uri.is_a?(URI::HTTP) && uri.host
+        rescue URI::InvalidURIError
+          false
         end
       end
     end

data/lib/bolt/module_installer/specs/id/base.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+require_relative '../../../../bolt/error'
+require_relative '../../../../bolt/logger'
+
+module Bolt
+  class ModuleInstaller
+    class Specs
+      class ID
+        class Base
+          attr_reader :name, :sha
+
+          # @param name [String] The module's name.
+          # @param sha [String] The ref's SHA1.
+          #
+          def initialize(name, sha)
+            @name = name
+            @sha  = sha
+          end
+
+          # Request the name and SHA for a module and ref.
+          # This method must return either an ID object or nil. The GitSpec
+          # class relies on this class to return an ID object to indicate
+          # the module was found, or nil to indicate that it should try to
+          # find it another way (such as cloning the repo).
+          #
+          # @param git [String] The URL to the git repo.
+          # @param ref [String] The ref to checkout.
+          # @param proxy [String] A proxy to use when making requests.
+          #
+          def self.request(git, ref, proxy)
+            name, sha = name_and_sha(git, ref, proxy)
+            name && sha ? new(name, sha) : nil
+          end
+
+          # Stub method for retrieving the module's name and SHA. Must
+          # be implemented by all sub classes.
+          #
+          private_class_method def self.name_and_sha(_git, _ref, _proxy)
+            raise NotImplementedError, 'Class does not implemented #name_and_sha'
+          end
+
+          # Makes a HTTP request.
+          #
+          # @param url [String] The URL to make the request to.
+          # @param proxy [String] A proxy to use when making the request.
+          # @param headers [Hash] Headers to send with the request.
+          #
+          private_class_method def self.make_request(url, proxy, headers = {})
+            uri  = URI.parse(url)
+            opts = { use_ssl: uri.scheme == 'https' }
+            args = [uri.host, uri.port]
+
+            if proxy
+              proxy = URI.parse(proxy)
+              args += [proxy.host, proxy.port, proxy.user, proxy.password]
+            end
+
+            Bolt::Logger.debug("Making request to #{loc(url, proxy)}")
+
+            Net::HTTP.start(*args, opts) do |client|
+              client.request(Net::HTTP::Get.new(uri, headers))
+            end
+          rescue StandardError => e
+            raise Bolt::Error.new(
+              "Failed to connect to #{loc(uri, proxy)}: #{e.message}",
+              "bolt/http-connect-error"
+            )
+          end
+
+          # Returns a formatted string describing the URL and proxy used when making
+          # a request.
+          #
+          # @param url [String, URI::HTTP] The URL used.
+          # @param proxy [String, URI::HTTP] The proxy used.
+          #
+          private_class_method def self.loc(url, proxy)
+            proxy ? "#{url} with proxy #{proxy}" : url.to_s
+          end
+
+          # Parses the metadata and validates that it is a Hash.
+          #
+          # @param metadata [String] The JSON data to parse.
+          #
+          private_class_method def self.parse_name_from_metadata(metadata)
+            metadata = JSON.parse(metadata)
+
+            unless metadata.is_a?(Hash)
+              raise Bolt::Error.new(
+                "Invalid metadata. Expected a Hash, got a #{metadata.class}: #{metadata}",
+                "bolt/invalid-module-metadata-error"
+              )
+            end
+
+            unless metadata.key?('name')
+              raise Bolt::Error.new(
+                "Invalid metadata. Metadata must include a 'name' key.",
+                "bolt/missing-module-name-error"
+              )
+            end
+
+            metadata['name']
+          rescue JSON::ParserError => e
+            raise Bolt::Error.new(
+              "Unable to parse metadata as JSON: #{e.message}",
+              "bolt/metadata-parse-error"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/specs/id/gitclone.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative '../../../../bolt/module_installer/specs/id/base'
+
+module Bolt
+  class ModuleInstaller
+    class Specs
+      class ID
+        class GitClone < Base
+          # Returns the name and SHA for the module at the given ref.
+          #
+          # @param git [String] The URL to the git repo.
+          # @param ref [String] The ref to checkout.
+          # @param proxy [String] The proxy to use when cloning.
+          #
+          private_class_method def self.name_and_sha(git, ref, proxy)
+            require 'open3'
+
+            unless git?
+              Bolt::Logger.debug("'git' executable not found, unable to use git clone resolution.")
+              return nil
+            end
+
+            # Clone the repo into a temp directory that will be automatically cleaned up.
+            Dir.mktmpdir do |dir|
+              return nil unless clone_repo(git, ref, dir, proxy)
+
+              # Extract the name from the metadata file and calculate the SHA.
+              Dir.chdir(dir) do
+                [request_name(git, ref), request_sha(git, ref)]
+              end
+            end
+          end
+
+          # Requests a module's metadata and returns the name from it.
+          #
+          # @param git [String] The URL to the git repo.
+          # @param ref [String] The ref to checkout.
+          #
+          private_class_method def self.request_name(git, ref)
+            command = %W[git show #{ref}:metadata.json]
+            Bolt::Logger.debug("Executing command '#{command.join(' ')}'")
+
+            out, err, status = Open3.capture3(*command)
+
+            unless status.success?
+              raise Bolt::Error.new(
+                "Unable to find metadata file at #{git}: #{err}",
+                "bolt/missing-metadata-file-error"
+              )
+            end
+
+            Bolt::Logger.debug("Found metadata file at #{git}")
+            parse_name_from_metadata(out)
+          end
+
+          # Requests the SHA for the specified ref.
+          #
+          # @param git [String] The URL to the git repo.
+          # @param ref [String] The ref to checkout.
+          #
+          private_class_method def self.request_sha(git, ref)
+            command = %W[git rev-parse #{ref}^{commit}]
+            Bolt::Logger.debug("Executing command '#{command.join(' ')}'")
+
+            out, err, status = Open3.capture3(*command)
+
+            if status.success?
+              out.strip
+            else
+              raise Bolt::Error.new(
+                "Unable to calculate SHA for ref #{ref} at #{git}: #{err}",
+                "bolt/invalid-ref-error"
+              )
+            end
+          end
+
+          # Clones the repository. First attempts to clone a bare repository
+          # and falls back to cloning the full repository if that fails. Cloning
+          # a bare repository is significantly faster for large modules, but
+          # cloning a bare repository using a commit is not supported.
+          #
+          # @param git [String] The URL to the git repo.
+          # @param ref [String] The ref to checkout.
+          # @param dir [String] The directory to clone the repo to.
+          # @param proxy [String] The proxy to use when cloning.
+          #
+          private_class_method def self.clone_repo(git, ref, dir, proxy)
+            clone  = %W[git clone #{git} #{dir}]
+            clone += %W[--config "http.proxy=#{proxy}" --config "https.proxy=#{proxy}"] if proxy
+
+            bare_clone = clone + %w[--bare --depth=1]
+            bare_clone.push("--branch=#{ref}") unless ref == 'HEAD'
+
+            # Attempt to clone a bare repository
+            Bolt::Logger.debug("Executing command '#{bare_clone.join(' ')}'")
+            _out, err, status = Open3.capture3(*bare_clone)
+            return true if status.success?
+            Bolt::Logger.debug("Unable to clone bare repository at #{loc(git, proxy)}: #{err}")
+
+            # Fall back to cloning the full repository
+            Bolt::Logger.debug("Executing command '#{clone.join(' ')}'")
+            _out, err, status = Open3.capture3(*clone)
+            Bolt::Logger.debug("Unable to clone repository at #{loc(git, proxy)}: #{err}") unless status.success?
+            status.success?
+          end
+
+          # Returns true if the 'git' executable is available.
+          #
+          private_class_method def self.git?
+            Open3.capture3('git', '--version')
+            true
+          rescue Errno::ENOENT
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/specs/id/github.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative '../../../../bolt/module_installer/specs/id/base'
+
+module Bolt
+  class ModuleInstaller
+    class Specs
+      class ID
+        class GitHub < Base
+          # Returns the name and SHA for the module at the given ref.
+          #
+          # @param git [String] The URL to the git repo.
+          # @param ref [String] The ref to use.
+          # @param proxy [String] The proxy to use when making requests.
+          #
+          private_class_method def self.name_and_sha(git, ref, proxy)
+            repo = parse_repo(git)
+            return nil unless repo
+            [request_name(repo, ref, proxy), request_sha(repo, ref, proxy)]
+          end
+
+          # Parses the repo path out of the URL.
+          #
+          # @param git [String] The URL to the git repo.
+          #
+          private_class_method def self.parse_repo(git)
+            if git.start_with?('git@github.com:')
+              git.split('git@github.com:').last.split('.git').first
+            elsif git.start_with?('https://github.com')
+              git.split('https://github.com/').last.split('.git').first
+            end
+          end
+
+          # Requests a module's metadata and returns the name from it.
+          #
+          # @param repo [String] The repo ID, i.e. 'owner/repo'
+          # @param ref [String] The ref to use.
+          # @param proxy [String] The proxy to use when making requests.
+          #
+          private_class_method def self.request_name(repo, ref, proxy)
+            metadata_url = "https://raw.githubusercontent.com/#{repo}/#{ref}/metadata.json"
+            response     = make_request(metadata_url, proxy)
+
+            case response
+            when Net::HTTPOK
+              Bolt::Logger.debug("Found metadata file at #{loc(metadata_url, proxy)}")
+              parse_name_from_metadata(response.body)
+            else
+              Bolt::Logger.debug("Unable to find metadata file at #{loc(metadata_url, proxy)}")
+              nil
+            end
+          end
+
+          # Requests the SHA for the specified ref.
+          #
+          # @param repo [String] The repo ID, i.e. 'owner/repo'
+          # @param ref [String] The ref to resolve.
+          # @param proxy [String] The proxy to use when making requests.
+          #
+          private_class_method def self.request_sha(repo, ref, proxy)
+            url      = "https://api.github.com/repos/#{repo}/commits/#{ref}"
+            headers  = ENV['GITHUB_TOKEN'] ? { "Authorization" => "token #{ENV['GITHUB_TOKEN']}" } : {}
+            response = make_request(url, proxy, headers)
+
+            case response
+            when Net::HTTPOK
+              JSON.parse(response.body).fetch('sha', nil)
+            when Net::HTTPUnauthorized
+              Bolt::Logger.debug("Invalid token at GITHUB_TOKEN, unable to calculate SHA.")
+              nil
+            when Net::HTTPForbidden
+              message = "GitHub API rate limit exceeded, unable to calculate SHA."
+
+              unless ENV['GITHUB_TOKEN']
+                message += " To increase your rate limit, set the GITHUB_TOKEN environment "\
+                          "variable with a GitHub personal access token."
+              end
+
+              Bolt::Logger.debug(message)
+              nil
+            else
+              Bolt::Logger.debug("Unable to calculate SHA for ref #{ref}")
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/specs/id/gitlab.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative '../../../../bolt/module_installer/specs/id/base'
+
+module Bolt
+  class ModuleInstaller
+    class Specs
+      class ID
+        class GitLab < Base
+          # Returns the name and SHA for the module at the given ref.
+          #
+          # @param git [String] The URL to the git repo.
+          # @param ref [String] The ref to use.
+          # @param proxy [String] The proxy to use when making requests.
+          #
+          private_class_method def self.name_and_sha(git, ref, proxy)
+            repo = parse_repo(git)
+            return nil unless repo
+            [request_name(repo, ref, proxy), request_sha(repo, ref, proxy)]
+          end
+
+          # Parses the repo path out of the URL.
+          #
+          # @param git [String] The URL to the git repo.
+          #
+          private_class_method def self.parse_repo(git)
+            if git.start_with?('git@gitlab.com:')
+              git.split('git@gitlab.com:').last.split('.git').first
+            elsif git.start_with?('https://gitlab.com')
+              git.split('https://gitlab.com/').last.split('.git').first
+            end
+          end
+
+          # Requests a module's metadata and returns the name from it.
+          #
+          # @param repo [String] The repo ID, i.e. 'owner/repo'
+          # @param ref [String] The ref to use.
+          # @param proxy [String] The proxy to use when making requests.
+          #
+          private_class_method def self.request_name(repo, ref, proxy)
+            metadata_url = "https://gitlab.com/#{repo}/-/raw/#{ref}/metadata.json"
+            response     = make_request(metadata_url, proxy)
+
+            case response
+            when Net::HTTPOK
+              Bolt::Logger.debug("Found metadata file at #{loc(metadata_url, proxy)}")
+              parse_name_from_metadata(response.body)
+            else
+              Bolt::Logger.debug("Unable to find metadata file at #{loc(metadata_url, proxy)}")
+              nil
+            end
+          end
+
+          # Requests the SHA for the specified ref.
+          #
+          # @param repo [String] The repo ID, i.e. 'owner/repo'
+          # @param ref [String] The ref to resolve.
+          # @param proxy [String] The proxy to use when making requests.
+          #
+          private_class_method def self.request_sha(repo, ref, proxy)
+            require 'cgi'
+
+            url      = "https://gitlab.com/api/v4/projects/#{CGI.escape(repo)}/repository/commits/#{ref}"
+            headers  = ENV['GITLAB_TOKEN'] ? { "PRIVATE-TOKEN" => ENV['GITLAB_TOKEN'] } : {}
+            response = make_request(url, proxy, headers)
+
+            case response
+            when Net::HTTPOK
+              JSON.parse(response.body).fetch('id', nil)
+            when Net::HTTPUnauthorized
+              Bolt::Logger.debug("Invalid token at GITLAB_TOKEN, unable to calculate SHA.")
+              nil
+            when Net::HTTPForbidden
+              message = "GitLab API rate limit exceeded, unable to calculate SHA."
+
+              unless ENV['GITLAB_TOKEN']
+                message += " To increase your rate limit, set the GITLAB_TOKEN environment "\
+                          "variable with a GitLab personal access token."
+              end
+
+              Bolt::Logger.debug(message)
+              nil
+            else
+              Bolt::Logger.debug("Unable to calculate SHA for ref #{ref}")
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/module_installer/specs.rb

@@ -7,8 +7,10 @@ require_relative 'specs/git_spec'
 module Bolt
   class ModuleInstaller
     class Specs
-      def initialize(specs = [])
-        @specs = []
+      def initialize(specs = [], config = {})
+        @specs  = []
+        @config = config
+
         add_specs(specs)
         assert_unique_names
       end
@@ -49,7 +51,7 @@ module Bolt
       #
       private def spec_from_hash(hash)
         return ForgeSpec.new(hash) if ForgeSpec.implements?(hash)
-        return GitSpec.new(hash)   if GitSpec.implements?(hash)
+        return GitSpec.new(hash, @config) if GitSpec.implements?(hash)
 
         raise Bolt::ValidationError, <<~MESSAGE.chomp
           Invalid module specification:

data/lib/bolt/module_installer.rb

@@ -18,7 +18,7 @@ module Bolt
     # Adds a single module to the project.
     #
     def add(name, specs, puppetfile_path, moduledir, project_file, config)
-      project_specs = Specs.new(specs)
+      project_specs = Specs.new(specs, config)
 
       # Exit early if project config already includes a spec with this name.
       if project_specs.include?(name)
@@ -151,7 +151,7 @@ module Bolt
       @outputter.print_message("Installing project modules\n\n")
 
       if resolve != false
-        specs = Specs.new(specs)
+        specs = Specs.new(specs, config)
 
         # If forcibly installing or if there is no Puppetfile, resolve
         # and write a Puppetfile.

data/lib/bolt/result.rb

@@ -200,16 +200,18 @@ module Bolt
 
     def to_data
       serialized_value = safe_value
+
       if serialized_value.key?('_sensitive') &&
          serialized_value['_sensitive'].is_a?(Puppet::Pops::Types::PSensitiveType::Sensitive)
         serialized_value['_sensitive'] = serialized_value['_sensitive'].to_s
       end
+
       {
         "target" => @target.name,
         "action" => action,
         "object" => object,
         "status" => status,
-        "value" => serialized_value
+        "value"  => serialized_value
       }
     end
 

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '3.24.0'
+  VERSION = '3.25.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 3.24.0
+  version: 3.25.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-06-29 00:00:00.000000000 Z
+date: 2022-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -222,16 +222,22 @@ dependencies:
   name: puppetfile-resolver
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.6.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.6.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: puppet-resource_api
   requirement: !ruby/object:Gem::Requirement
@@ -526,6 +532,10 @@ files:
 - lib/bolt/module_installer/specs.rb
 - lib/bolt/module_installer/specs/forge_spec.rb
 - lib/bolt/module_installer/specs/git_spec.rb
+- lib/bolt/module_installer/specs/id/base.rb
+- lib/bolt/module_installer/specs/id/gitclone.rb
+- lib/bolt/module_installer/specs/id/github.rb
+- lib/bolt/module_installer/specs/id/gitlab.rb
 - lib/bolt/node/errors.rb
 - lib/bolt/node/output.rb
 - lib/bolt/outputter.rb