octokit 4.21.0 → 10.0.0

data/lib/octokit/enterprise_management_console_client/management_console.rb

@@ -1,34 +1,36 @@
+# frozen_string_literal: true
+
 module Octokit
   class EnterpriseManagementConsoleClient
-
     # Methods for the Enterprise Management Console API
     #
     # @see https://developer.github.com/v3/enterprise-admin/management_console/
     module ManagementConsole
-
       # Uploads a license for the first time
       #
       # @param license [String] The path to your .ghl license file.
       # @param settings [Hash] A hash configuration of the initial settings.
       #
-      # @see http: //git.io/j5NT
+      # @see https://docs.github.com/en/enterprise-server@3.4/rest/enterprise-admin/management-console#create-a-github-license
       # @return nil
       def upload_license(license, settings = nil)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
         conn = faraday_configuration
 
-        params = { }
+        params = {}
         params[:license] = Faraday::UploadIO.new(license, 'binary')
         params[:password] = @management_console_password
-        params[:settings] = "#{settings.to_json}" unless settings.nil?
+        params[:settings] = settings.to_json.to_s unless settings.nil?
 
-        @last_response = conn.post("/setup/api/start", params)
+        @last_response = conn.post('/setup/api/start', params)
       end
 
       # Start a configuration process.
       #
       # @return nil
       def start_configuration
-        post "/setup/api/configure", password_hash
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
+        post '/setup/api/configure', password_hash
       end
 
       # Upgrade an Enterprise installation
@@ -37,29 +39,32 @@ module Octokit
       #
       # @return nil
       def upgrade(license)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
         conn = faraday_configuration
 
-        params = { }
+        params = {}
         params[:license] = Faraday::UploadIO.new(license, 'binary')
         params[:api_key] = @management_console_password
-        @last_response = conn.post("/setup/api/upgrade", params)
+        @last_response = conn.post('/setup/api/upgrade', params)
       end
 
       # Get information about the Enterprise installation
       #
       # @return [Sawyer::Resource] The installation information
       def config_status
-        get "/setup/api/configcheck", password_hash
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
+        get '/setup/api/configcheck', password_hash
       end
-      alias :config_check :config_status
+      alias config_check config_status
 
       # Get information about the Enterprise installation
       #
       # @return [Sawyer::Resource] The settings
       def settings
-        get "/setup/api/settings", password_hash
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
+        get '/setup/api/settings', password_hash
       end
-      alias :get_settings :settings
+      alias get_settings settings
 
       # Modify the Enterprise settings
       #
@@ -67,48 +72,53 @@ module Octokit
       #
       # @return [nil]
       def edit_settings(settings)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
         queries = password_hash
-        queries[:query][:settings] = "#{settings.to_json}"
-        put "/setup/api/settings", queries
+        queries[:query][:settings] = settings.to_json.to_s
+        put '/setup/api/settings', queries
       end
 
       # Get information about the Enterprise maintenance status
       #
       # @return [Sawyer::Resource] The maintenance status
       def maintenance_status
-        get "/setup/api/maintenance", password_hash
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
+        get '/setup/api/maintenance', password_hash
       end
-      alias :get_maintenance_status :maintenance_status
+      alias get_maintenance_status maintenance_status
 
       # Start (or turn off) the Enterprise maintenance mode
       #
       # @param maintenance [Hash] A hash configuration of the maintenance settings
       # @return [nil]
       def set_maintenance_status(maintenance)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
         queries = password_hash
-        queries[:query][:maintenance] = "#{maintenance.to_json}"
-        post "/setup/api/maintenance", queries
+        queries[:query][:maintenance] = maintenance.to_json.to_s
+        post '/setup/api/maintenance', queries
       end
-      alias :edit_maintenance_status :set_maintenance_status
+      alias edit_maintenance_status set_maintenance_status
 
       # Fetch the authorized SSH keys on the Enterprise install
       #
       # @return [Sawyer::Resource] An array of authorized SSH keys
       def authorized_keys
-        get "/setup/api/settings/authorized-keys", password_hash
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
+        get '/setup/api/settings/authorized-keys', password_hash
       end
-      alias :get_authorized_keys :authorized_keys
+      alias get_authorized_keys authorized_keys
 
       # Add an authorized SSH keys on the Enterprise install
       #
       # @param key Either the file path to a key, a File handler to the key, or the contents of the key itself
       # @return [Sawyer::Resource] An array of authorized SSH keys
       def add_authorized_key(key)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
         queries = password_hash
         case key
         when String
           if File.exist?(key)
-            key = File.open(key, "r")
+            key = File.open(key, 'r')
             content = key.read.strip
             key.close
           else
@@ -120,7 +130,7 @@ module Octokit
         end
 
         queries[:query][:authorized_key] = content
-        post "/setup/api/settings/authorized-keys", queries
+        post '/setup/api/settings/authorized-keys', queries
       end
 
       # Removes an authorized SSH keys from the Enterprise install
@@ -128,11 +138,12 @@ module Octokit
       # @param key Either the file path to a key, a File handler to the key, or the contents of the key itself
       # @return [Sawyer::Resource] An array of authorized SSH keys
       def remove_authorized_key(key)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.15.0, please use the ManageGHES client instead.')
         queries = password_hash
         case key
         when String
           if File.exist?(key)
-            key = File.open(key, "r")
+            key = File.open(key, 'r')
             content = key.read.strip
             key.close
           else
@@ -144,27 +155,34 @@ module Octokit
         end
 
         queries[:query][:authorized_key] = content
-        delete "/setup/api/settings/authorized-keys", queries
+        delete '/setup/api/settings/authorized-keys', queries
       end
-      alias :delete_authorized_key :remove_authorized_key
-
+      alias delete_authorized_key remove_authorized_key
     end
+
     private
 
     def password_hash
-      { :query => { :api_key => @management_console_password } }
+      { query: { api_key: @management_console_password } }
     end
 
     # We fall back to raw Faraday for handling the licenses because I'm suspicious
-    # that Sawyer isn't handling binary POSTs correctly: http://git.io/jMir
+    # that Sawyer isn't handling binary POSTs correctly: https://github.com/lostisland/sawyer/blob/03fca4c020f465ec42856d0486ec3991859b0aed/lib/sawyer/agent.rb#L85
     def faraday_configuration
-      @faraday_configuration ||= Faraday.new(:url => @management_console_endpoint) do |http|
+      @faraday_configuration ||= Faraday.new(url: @management_console_endpoint) do |http|
         http.headers[:user_agent] = user_agent
-        http.request :multipart
+        begin
+          http.request :multipart
+        rescue Faraday::Error
+          raise Faraday::Error, <<~ERROR
+            The `faraday-multipart` gem is required to upload a license.
+            Please add `gem "faraday-multipart"` to your Gemfile.
+          ERROR
+        end
         http.request :url_encoded
 
         # Disabling SSL is essential for certain self-hosted Enterprise instances
-        if self.connection_options[:ssl] && !self.connection_options[:ssl][:verify]
+        if connection_options[:ssl] && !connection_options[:ssl][:verify]
           http.ssl[:verify] = false
         end
 

data/lib/octokit/enterprise_management_console_client.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require 'octokit/configurable'
 require 'octokit/connection'
 require 'octokit/warnable'
 require 'octokit/enterprise_management_console_client/management_console'
 
 module Octokit
-
   # EnterpriseManagementConsoleClient is only meant to be used by GitHub Enterprise Admins
   # and provides access to the management console API endpoints.
   #
@@ -12,7 +13,6 @@ module Octokit
   #   and GitHub Enterprise.
   # @see https://developer.github.com/v3/enterprise-admin/management_console/
   class EnterpriseManagementConsoleClient
-
     include Octokit::Configurable
     include Octokit::Connection
     include Octokit::Warnable
@@ -20,7 +20,13 @@ module Octokit
 
     def initialize(options = {})
       # Use options passed in, but fall back to module defaults
+      # rubocop:disable Style/HashEachMethods
+      #
+      # This may look like a `.keys.each` which should be replaced with `#each_key`, but
+      # this doesn't actually work, since `#keys` is just a method we've defined ourselves.
+      # The class doesn't fulfill the whole `Enumerable` contract.
       Octokit::Configurable.keys.each do |key|
+        # rubocop:enable Style/HashEachMethods
         instance_variable_set(:"@#{key}", options[key] || Octokit.instance_variable_get(:"@#{key}"))
       end
     end

data/lib/octokit/error.rb

@@ -1,12 +1,16 @@
+# frozen_string_literal: true
+
 module Octokit
   # Custom error class for rescuing from all GitHub errors
   class Error < StandardError
     attr_reader :context
+
     # Returns the appropriate Octokit::Error subclass based
     # on status and response message
     #
     # @param [Hash] response HTTP response
     # @return [Octokit::Error]
+    # rubocop:disable Metrics/CyclomaticComplexity
     def self.from_response(response)
       status  = response[:status].to_i
       body    = response[:body].to_s
@@ -20,6 +24,7 @@ module Octokit
                   when 405      then Octokit::MethodNotAllowed
                   when 406      then Octokit::NotAcceptable
                   when 409      then Octokit::Conflict
+                  when 410      then Octokit::Deprecated
                   when 415      then Octokit::UnsupportedMediaType
                   when 422      then error_for_422(body)
                   when 451      then Octokit::UnavailableForLegalReasons
@@ -33,14 +38,15 @@ module Octokit
         klass.new(response)
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity
 
-     def build_error_context
-       if RATE_LIMITED_ERRORS.include?(self.class)
-         @context = Octokit::RateLimit.from_response(@response)
-       end
-     end
+    def build_error_context
+      if RATE_LIMITED_ERRORS.include?(self.class)
+        @context = Octokit::RateLimit.from_response(@response)
+      end
+    end
 
-    def initialize(response=nil)
+    def initialize(response = nil)
       @response = response
       super(build_error_message)
       build_error_context
@@ -55,7 +61,9 @@ module Octokit
 
     # Returns most appropriate error for 401 HTTP status code
     # @private
+    # rubocop:disable Naming/VariableNumber
     def self.error_for_401(headers)
+      # rubocop:enbale Naming/VariableNumber
       if Octokit::OneTimePasswordRequired.required_header(headers)
         Octokit::OneTimePasswordRequired
       else
@@ -66,25 +74,27 @@ module Octokit
     # Returns most appropriate error for 403 HTTP status code
     # @private
     def self.error_for_403(body)
-      if body =~ /rate limit exceeded/i
+      # rubocop:enable Naming/VariableNumber
+      case body
+      when /rate limit exceeded/i, /exceeded a secondary rate limit/i
         Octokit::TooManyRequests
-      elsif body =~ /login attempts exceeded/i
+      when /login attempts exceeded/i
         Octokit::TooManyLoginAttempts
-      elsif body =~ /returns blobs up to [0-9]+ MB/i
+      when /(returns|for) blobs (up to|between) [0-9-]+ MB/i
         Octokit::TooLargeContent
-      elsif body =~ /abuse/i
+      when /abuse/i
         Octokit::AbuseDetected
-      elsif body =~ /repository access blocked/i
+      when /repository access blocked/i
         Octokit::RepositoryUnavailable
-      elsif body =~ /email address must be verified/i
+      when /email address must be verified/i
         Octokit::UnverifiedEmail
-      elsif body =~ /account was suspended/i
+      when /account was suspended/i
         Octokit::AccountSuspended
-      elsif body =~ /billing issue/i
+      when /billing issue/i
         Octokit::BillingIssue
-      elsif body =~ /Resource protected by organization SAML enforcement/i
+      when /Resource protected by organization SAML enforcement/i
         Octokit::SAMLProtected
-      elsif body =~ /suspended your access|This installation has been suspended/i
+      when /suspended your access|This installation has been suspended/i
         Octokit::InstallationSuspended
       else
         Octokit::Forbidden
@@ -93,7 +103,9 @@ module Octokit
 
     # Return most appropriate error for 404 HTTP status code
     # @private
+    # rubocop:disable Naming/VariableNumber
     def self.error_for_404(body)
+      # rubocop:enable Naming/VariableNumber
       if body =~ /Branch not protected/i
         Octokit::BranchNotProtected
       else
@@ -103,7 +115,9 @@ module Octokit
 
     # Return most appropriate error for 422 HTTP status code
     # @private
+    # rubocop:disable Naming/VariableNumber
     def self.error_for_422(body)
+      # rubocop:enable Naming/VariableNumber
       if body =~ /PullRequestReviewComment/i && body =~ /(commit_id|end_commit_oid) is not part of the pull request/i
         Octokit::CommitIsNotPartOfPullRequest
       elsif body =~ /Path diff too large/i
@@ -116,7 +130,7 @@ module Octokit
     # Array of validation errors
     # @return [Array<Hash>] Error info
     def errors
-      if data && data.is_a?(Hash)
+      if data.is_a?(Hash)
         data[:errors] || []
       else
         []
@@ -150,15 +164,13 @@ module Octokit
       @data ||=
         if (body = @response[:body]) && !body.empty?
           if body.is_a?(String) &&
-            @response[:response_headers] &&
-            @response[:response_headers][:content_type] =~ /json/
+             @response[:response_headers] &&
+             @response[:response_headers][:content_type] =~ /json/
 
             Sawyer::Agent.serializer.decode(body)
           else
             body
           end
-        else
-          nil
         end
     end
 
@@ -178,10 +190,12 @@ module Octokit
     def response_error_summary
       return nil unless data.is_a?(Hash) && !Array(data[:errors]).empty?
 
-      summary = "\nError summary:\n"
+      summary = +"\nError summary:\n"
+      return summary << data[:errors] if data[:errors].is_a?(String)
+
       summary << data[:errors].map do |error|
         if error.is_a? Hash
-          error.map { |k,v| "  #{k}: #{v}" }
+          error.map { |k, v| "  #{k}: #{v}" }
         else
           "  #{error}"
         end
@@ -193,19 +207,21 @@ module Octokit
     def build_error_message
       return nil if @response.nil?
 
-      message =  "#{@response[:method].to_s.upcase} "
-      message << redact_url(@response[:url].to_s) + ": "
+      message = +"#{@response[:method].to_s.upcase} "
+      message << "#{redact_url(@response[:url].to_s.dup)}: "
       message << "#{@response[:status]} - "
-      message << "#{response_message}" unless response_message.nil?
-      message << "#{response_error}" unless response_error.nil?
-      message << "#{response_error_summary}" unless response_error_summary.nil?
+      message << response_message.to_s unless response_message.nil?
+      message << response_error.to_s unless response_error.nil?
+      message << response_error_summary.to_s unless response_error_summary.nil?
       message << " // See: #{documentation_url}" unless documentation_url.nil?
       message
     end
 
     def redact_url(url_string)
-      %w[client_secret access_token].each do |token|
-        url_string.gsub!(/#{token}=\S+/, "#{token}=(redacted)") if url_string.include? token
+      %w[client_secret access_token api_key].each do |token|
+        if url_string.include? token
+          url_string.gsub!(/#{token}=\S+/, "#{token}=(redacted)")
+        end
       end
       url_string
     end
@@ -223,10 +239,10 @@ module Octokit
   # Raised when GitHub returns a 401 HTTP status code
   # and headers include "X-GitHub-OTP"
   class OneTimePasswordRequired < ClientError
-    #@private
-    OTP_DELIVERY_PATTERN = /required; (\w+)/i
+    # @private
+    OTP_DELIVERY_PATTERN = /required; (\w+)/i.freeze
 
-    #@private
+    # @private
     def self.required_header(headers)
       OTP_DELIVERY_PATTERN.match headers['X-GitHub-OTP'].to_s
     end
@@ -306,6 +322,9 @@ module Octokit
   # Raised when GitHub returns a 409 HTTP status code
   class Conflict < ClientError; end
 
+  # Raised when GHES Manage return a 410 HTTP status code
+  class Deprecated < ClientError; end
+
   # Raised when GitHub returns a 414 HTTP status code
   class UnsupportedMediaType < ClientError; end
 
@@ -348,5 +367,5 @@ module Octokit
   # Raised when a repository is created with an invalid format
   class InvalidRepository < ArgumentError; end
 
-  RATE_LIMITED_ERRORS = [Octokit::TooManyRequests, Octokit::AbuseDetected]
+  RATE_LIMITED_ERRORS = [Octokit::TooManyRequests, Octokit::AbuseDetected].freeze
 end

data/lib/octokit/gist.rb

@@ -1,8 +1,8 @@
-module Octokit
+# frozen_string_literal: true
 
+module Octokit
   # Class to parse and create Gist URLs
   class Gist
-
     # !@attribute id
     #   @return [String] Gist ID
     attr_accessor :id
@@ -10,7 +10,7 @@ module Octokit
     # Instantiate {Gist} object from Gist URL
     # @ return [Gist]
     def self.from_url(url)
-      Gist.new(URI.parse(url).path[1..-1])
+      Gist.new(URI.parse(url).path[1..])
     end
 
     def initialize(gist)
@@ -31,6 +31,5 @@ module Octokit
     def url
       "https://gist.github.com/#{@id}"
     end
-
   end
 end

data/lib/octokit/manage_ghes_client/manage_ghes.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Octokit
+  # Client for the Manage GitHub Enterprise Server API
+  class ManageGHESClient
+    # Methods for the Manage GitHub Enterprise Server API
+    #
+    # @see https://developer.github.com/v3/enterprise-admin/manage-ghes
+    module ManageAPI
+      # Get information about the maintenance status of the GHES instance
+      #
+      # @return [nil]
+      def maintenance_mode
+        conn = authenticated_client
+
+        @last_response = conn.get('/manage/v1/maintenance')
+      end
+
+      # Configure the maintenance mode of the GHES instance
+      #
+      # @param maintenance [Hash] A hash configuration of the maintenance mode status
+      # @return [nil]
+      def set_maintenance_mode(enabled, options = {})
+        conn = authenticated_client
+
+        options[:enabled] = enabled
+        @last_response = conn.post('/manage/v1/maintenance', options)
+      end
+      alias configure_maintenance_mode set_maintenance_mode
+    end
+
+    # Uploads a license for the first time
+    #
+    # @param license [String] The path to your .ghl license file.
+    #
+    # @return [nil]
+    def upload_license(license)
+      conn = authenticated_client
+      begin
+        conn.request :multipart
+      rescue Faraday::Error
+        raise Faraday::Error, <<~ERROR
+          The `faraday-multipart` gem is required to upload a license.
+          Please add `gem "faraday-multipart"` to your Gemfile.
+        ERROR
+      end
+      params = {}
+      params[:license] = Faraday::FilePart.new(license, 'binary')
+      params[:password] = @manage_ghes_password
+      @last_response = conn.post('/manage/v1/config/init', params, { 'Content-Type' => 'multipart/form-data' })
+    end
+
+    # Start a configuration process.
+    #
+    # @return [nil]
+    def start_configuration
+      conn = authenticated_client
+      @last_response = conn.post('/manage/v1/config/apply')
+    end
+
+    # Get information about the Enterprise installation
+    #
+    # @return [nil]
+    def config_status
+      conn = authenticated_client
+      @last_response = conn.get('/manage/v1/config/apply')
+    end
+    alias config_check config_status
+
+    # Get information about the Enterprise installation
+    #
+    # @return [nil]
+    def settings
+      conn = authenticated_client
+      @last_response = conn.get('/manage/v1/config/settings')
+    end
+    alias get_settings settings
+
+    # Modify the Enterprise settings
+    #
+    # @param settings [Hash] A hash configuration of the new settings
+    #
+    # @return [nil]
+    def edit_settings(settings)
+      conn = authenticated_client
+      @last_response = conn.put('/manage/v1/config/settings', settings.to_json.to_s)
+    end
+
+    def authorized_keys
+      conn = authenticated_client
+      @last_response = conn.get('/manage/v1/access/ssh')
+    end
+    alias get_authorized_keys authorized_keys
+
+    # Add an authorized SSH keys on the Enterprise install
+    #
+    # @param key Either the file path to a key, a File handler to the key, or the contents of the key itself
+    # @return [nil]
+    def add_authorized_key(key)
+      conn = authenticated_client
+      case key
+      when String
+        if File.exist?(key)
+          key = File.open(key, 'r')
+          content = key.read.strip
+          key.close
+        else
+          content = key
+        end
+      when File
+        content = key.read.strip
+        key.close
+      end
+
+      queries = {}
+      queries[:key] = content
+      @last_response = conn.post('/manage/v1/access/ssh', queries)
+    end
+
+    # Removes an authorized SSH keys from the Enterprise install
+    #
+    # @param key Either the file path to a key, a File handler to the key, or the contents of the key itself
+    # @return [nil]
+    def remove_authorized_key(key)
+      conn = authenticated_client
+      case key
+      when String
+        if File.exist?(key)
+          key = File.open(key, 'r')
+          content = key.read.strip
+          key.close
+        else
+          content = key
+        end
+      when File
+        content = key.read.strip
+        key.close
+      end
+
+      queries = {}
+      queries[:key] = content
+      @last_response = conn.run_request(:delete, '/manage/v1/access/ssh', queries, nil)
+    end
+    alias delete_authorized_key remove_authorized_key
+
+    private
+
+    def basic_authenticated?
+      !!(@manage_ghes_username && @manage_ghes_password)
+    end
+
+    # If no username is provided, we assume root site admin should be used
+    def root_site_admin_assumed?
+      !@manage_ghes_username
+    end
+
+    def authenticated_client
+      @authenticated_client ||= Faraday.new(url: @manage_ghes_endpoint) do |c|
+        c.headers[:user_agent] = user_agent
+        c.request  :json
+        c.response :json
+        c.adapter Faraday.default_adapter
+
+        if root_site_admin_assumed?
+          username = 'api_key'
+        elsif basic_authenticated?
+          username = @manage_ghes_username
+        end
+        c.request(*FARADAY_BASIC_AUTH_KEYS, username, @manage_ghes_password)
+
+        # Disabling SSL is essential for certain self-hosted Enterprise instances
+        c.ssl[:verify] = false if connection_options[:ssl] && !connection_options[:ssl][:verify]
+
+        c.use Octokit::Response::RaiseError
+      end
+    end
+  end
+end