Add GHES Manage API client

README.md

@@ -709,6 +709,9 @@ Octokit:
 | `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password.                                                                                                                                                    |
 | `OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT`                    | GitHub Enterprise hostname.                                                                                                                                                                       |
 | `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint.                                                                                                                                                    |
+| `OCTOKIT_TEST_GITHUB_MANAGE_GHES_ENDPOINT`                          | GitHub Enterprise Server GHES Manage Endpoint.                                                                                                                                                    |
+| `OCTOKIT_TEST_GITHUB_MANAGE_GHES_USERNAME`                          | GitHub Enterprise Server GHES Manage Username.                                                                                                                                                    |
+| `OCTOKIT_TEST_GITHUB_MANAGE_GHES_PASSWORD`                          | GitHub Enterprise Server GHES Manage Password.                                                                                                                                                    |
 | `OCTOKIT_TEST_GITHUB_INTEGRATION`                            | [GitHub Integration](https://developer.github.com/early-access/integrations/) owned by your test organization.                                                                                    |
 | `OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION`               | Installation of the GitHub Integration specified above.                                                                                                                                           |
 | `OCTOKIT_TEST_INTEGRATION_PEM_KEY`                           | File path to the private key generated from your integration.                                                                                                                                     |

lib/octokit.rb

@@ -4,6 +4,7 @@
 require 'octokit/client'
 require 'octokit/enterprise_admin_client'
 require 'octokit/enterprise_management_console_client'
+require 'octokit/manage_ghes_client'
 
 # Ruby toolkit for the GitHub API
 module Octokit
@@ -41,12 +42,24 @@ def enterprise_management_console_client
       @enterprise_management_console_client = Octokit::EnterpriseManagementConsoleClient.new(options)
     end
 
+    # ManageGHESClient client based on configured options {Configurable}
+    #
+    # @return [Octokit::ManageGHESClient] API wrapper
+    def manage_ghes_client
+      if defined?(@manage_ghes_client) && @manage_ghes_client.same_options?(options)
+        return @manage_ghes_client
+      end
+
+      @manage_ghes_client = Octokit::ManageGHESClient.new(options)
+    end
+
     private
 
     def respond_to_missing?(method_name, include_private = false)
       client.respond_to?(method_name, include_private) ||
         enterprise_admin_client.respond_to?(method_name, include_private) ||
-        enterprise_management_console_client.respond_to?(method_name, include_private)
+        enterprise_management_console_client.respond_to?(method_name, include_private) ||
+        manage_ghes_client.respond_to?(method_name, include_private)
     end
 
     def method_missing(method_name, *args, &block)
@@ -56,6 +69,8 @@ def method_missing(method_name, *args, &block)
         return enterprise_admin_client.send(method_name, *args, &block)
       elsif enterprise_management_console_client.respond_to?(method_name)
         return enterprise_management_console_client.send(method_name, *args, &block)
+      elsif manage_ghes_client.respond_to?(method_name)
+        return manage_ghes_client.send(method_name, *args, &block)
       end
 
       super

lib/octokit/configurable.rb

@@ -32,6 +32,12 @@ module Configurable
     #   @return [String] An admin password set up for your GitHub Enterprise management console
     # @!attribute management_console_endpoint
     #   @return [String] Base URL for API requests to the GitHub Enterprise management console
+    # @!attribute manage_ghes_endpoint
+    #   @return [String] Base URL for API requests to the GitHub Enterprise Server Manage API
+    # @!attribute manage_ghes_username
+    #   @return [String] API username for requests to the GitHub Enterprise Server Manage API
+    # @!attribute manage_ghes_password
+    #   @return [String] API user password for requests to the GitHub Enterprise Server Manage API
     # @!attribute middleware
     #   @see https://github.com/lostisland/faraday
     #   @return [Faraday::Builder or Faraday::RackBuilder] Configure middleware for Faraday
@@ -59,7 +65,10 @@ module Configurable
                   :middleware, :netrc, :netrc_file,
                   :per_page, :proxy, :ssl_verify_mode, :user_agent
     attr_writer :password, :web_endpoint, :api_endpoint, :login,
-                :management_console_endpoint, :management_console_password
+                :management_console_endpoint, :management_console_password,
+                :manage_ghes_endpoint,
+                :manage_ghes_username,
+                :manage_ghes_password
 
     class << self
       # List of configurable keys for {Octokit::Client}
@@ -77,6 +86,9 @@ def keys
           login
           management_console_endpoint
           management_console_password
+          manage_ghes_endpoint
+          manage_ghes_username
+          manage_ghes_password
           middleware
           netrc
           netrc_file
@@ -126,6 +138,10 @@ def management_console_endpoint
       File.join(@management_console_endpoint, '')
     end
 
+    def manage_ghes_endpoint
+      File.join(@manage_ghes_endpoint, '')
+    end
+
     # Base URL for generated web URLs
     #
     # @return [String] Default: https://github.com/

lib/octokit/default.rb

@@ -12,6 +12,11 @@
   rescue LoadError
     Octokit::Warnable.octokit_warn 'To use retry middleware with Faraday v2.0+, install `faraday-retry` gem'
   end
+  begin
+    require 'faraday/multipart'
+  rescue LoadError
+    Octokit::Warnable.octokit_warn 'To use multipart middleware with Faraday v2.0+, install `faraday-multipart` gem; note: this is used by the ManageGHES client for uploading licenses'
+  end
 end
 
 module Octokit
@@ -102,6 +107,24 @@ def management_console_endpoint
         ENV.fetch('OCTOKIT_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT', nil)
       end
 
+      # Default GHES Manage API endpoint from ENV
+      # @return [String]
+      def manage_ghes_endpoint
+        ENV.fetch('OCTOKIT_MANAGE_GHES_ENDPOINT', nil)
+      end
+
+      # Default GHES Manage API username from ENV
+      # @return [String]
+      def manage_ghes_username
+        ENV.fetch('OCTOKIT_MANAGE_GHES_USERNAME', nil)
+      end
+
+      # Default GHES Manage API password from ENV
+      # @return [String]
+      def manage_ghes_password
+        ENV.fetch('OCTOKIT_MANAGE_GHES_PASSWORD', nil)
+      end
+
       # Default options for Faraday::Connection
       # @return [Hash]
       def connection_options

lib/octokit/enterprise_management_console_client/management_console.rb

@@ -14,6 +14,7 @@ module ManagementConsole
       # @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.14.0, please use the ManageGHES client instead.')
         conn = faraday_configuration
 
         params = {}
@@ -28,6 +29,7 @@ def upload_license(license, settings = nil)
       #
       # @return nil
       def start_configuration
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.14.0, please use the ManageGHES client instead.')
         post '/setup/api/configure', password_hash
       end
 
@@ -37,6 +39,7 @@ def start_configuration
       #
       # @return nil
       def upgrade(license)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.14.0, please use the ManageGHES client instead.')
         conn = faraday_configuration
 
         params = {}
@@ -49,6 +52,7 @@ def upgrade(license)
       #
       # @return [Sawyer::Resource] The installation information
       def config_status
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.14.0, please use the ManageGHES client instead.')
         get '/setup/api/configcheck', password_hash
       end
       alias config_check config_status
@@ -57,6 +61,7 @@ def config_status
       #
       # @return [Sawyer::Resource] The settings
       def settings
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.14.0, please use the ManageGHES client instead.')
         get '/setup/api/settings', password_hash
       end
       alias get_settings settings
@@ -67,6 +72,7 @@ def settings
       #
       # @return [nil]
       def edit_settings(settings)
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.14.0, please use the ManageGHES client instead.')
         queries = password_hash
         queries[:query][:settings] = settings.to_json.to_s
         put '/setup/api/settings', queries
@@ -76,6 +82,7 @@ def edit_settings(settings)
       #
       # @return [Sawyer::Resource] The maintenance status
       def maintenance_status
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.14.0, please use the ManageGHES client instead.')
         get '/setup/api/maintenance', password_hash
       end
       alias get_maintenance_status maintenance_status
@@ -85,6 +92,7 @@ def maintenance_status
       # @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.14.0, please use the ManageGHES client instead.')
         queries = password_hash
         queries[:query][:maintenance] = maintenance.to_json.to_s
         post '/setup/api/maintenance', queries
@@ -95,6 +103,7 @@ def set_maintenance_status(maintenance)
       #
       # @return [Sawyer::Resource] An array of authorized SSH keys
       def authorized_keys
+        octokit_warn('The Management Console API will be deprecated in GitHub Enterprise Server 3.14.0, please use the ManageGHES client instead.')
         get '/setup/api/settings/authorized-keys', password_hash
       end
       alias get_authorized_keys authorized_keys
@@ -104,6 +113,7 @@ def authorized_keys
       # @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.14.0, please use the ManageGHES client instead.')
         queries = password_hash
         case key
         when String
@@ -128,6 +138,7 @@ def add_authorized_key(key)
       # @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.14.0, please use the ManageGHES client instead.')
         queries = password_hash
         case key
         when String

lib/octokit/error.rb

@@ -10,6 +10,7 @@ class Error < StandardError
     #
     # @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
@@ -23,6 +24,7 @@ def self.from_response(response)
                   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
@@ -36,6 +38,7 @@ def self.from_response(response)
         klass.new(response)
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity
 
     def build_error_context
       if RATE_LIMITED_ERRORS.include?(self.class)
@@ -317,6 +320,9 @@ class NotAcceptable < ClientError; end
   # 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
 

lib/octokit/manage_ghes_client.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'octokit/configurable'
+require 'octokit/connection'
+require 'octokit/warnable'
+require 'octokit/manage_ghes_client/manage_ghes'
+
+module Octokit
+  # ManageGHESClient is only meant to be used by GitHub Enterprise Server (GHES) operators
+  # and provides access to the Manage GHES API endpoints.
+  #
+  # @see Octokit::Client Use Octokit::Client for regular API use for GitHub
+  #   and GitHub Enterprise.
+  # @see https://developer.github.com/v3/enterprise-admin/manage-ghes/
+  class ManageGHESClient
+    include Octokit::Configurable
+    include Octokit::Connection
+    include Octokit::Warnable
+    include Octokit::ManageGHESClient::ManageAPI
+
+    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
+
+    protected
+
+    def endpoint
+      manage_ghes_endpoint
+    end
+
+    # Set Manage GHES API endpoint
+    #
+    # @param value [String] Manage GHES API endpoint
+    def manage_ghes_endpoint=(value)
+      reset_agent
+      @manage_ghes_endpoint = value
+    end
+
+    # Set Manage GHES API username
+    #
+    # @param value [String] Manage GHES API username
+    def manage_ghes_username=(value)
+      reset_agent
+      @manage_ghes_username = value
+    end
+
+    # Set Manage GHES API password
+    #
+    # @param value [String] Manage GHES API password
+    def manage_ghes_password=(value)
+      reset_agent
+      @manage_ghes_password = value
+    end
+  end
+end