feat: 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/[email protected]/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