Merge branch '4-stable' into readme-style-update

.github/workflows/octokit.yml

@@ -20,7 +20,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu ]
-        ruby: [ 2.5, 2.6, 2.7, head ]
+        ruby: [ 2.5, 2.6, 2.7, '3.0', 3.1, head ]
 
     steps:
       - uses: actions/checkout@v2

README.md

@@ -10,23 +10,25 @@ Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
 ## Table of Contents
 
 1. [Philosophy](#philosophy)
-2. [Quick start](#quick-start)
+2. [Installation](#quick-start)
 3. [Making requests](#making-requests)
+   1. [Additional Query Parameters](#additional-query-parameters)
 4. [Consuming resources](#consuming-resources)
 5. [Accessing HTTP responses](#accessing-http-responses)
-6. [Authentication](#authentication)
+6. [Handling errors](#handling-errors)
+7. [Authentication](#authentication)
    1. [Basic Authentication](#basic-authentication)
    2. [OAuth access tokens](#oauth-access-tokens)
    3. [Two-Factor Authentication](#two-factor-authentication)
    4. [Using a .netrc file](#using-a-netrc-file)
    5. [Application authentication](#application-authentication)
-7. [Pagination](#pagination)
+8. [Pagination](#pagination)
    1. [Auto pagination](#auto-pagination)
-8. [Working with GitHub Enterprise](#working-with-github-enterprise)
+9. [Working with GitHub Enterprise](#working-with-github-enterprise)
    1. [Interacting with the GitHub.com APIs in GitHub Enterprise](#interacting-with-the-githubcom-apis-in-github-enterprise)
    2. [Interacting with the GitHub Enterprise Admin APIs](#interacting-with-the-github-enterprise-admin-apis)
    3. [Interacting with the GitHub Enterprise Management Console APIs](#interacting-with-the-github-enterprise-management-console-apis)
-9. [SSL Connection Errors](#ssl-connection-errors)
+   4. [SSL Connection Errors](#ssl-connection-errors)
 10. [Configuration and defaults](#configuration-and-defaults)
     1. [Configuring module defaults](#configuring-module-defaults)
     2. [Using ENV variables](#using-env-variables)
@@ -66,7 +68,7 @@ client.readme 'al3x/sovereign', :accept => 'application/vnd.github.html'
 [wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper
 [github-api]: https://developer.github.com/v3/
 
-## Quick start
+## Installation
 
 Install via Rubygems
 
@@ -80,7 +82,7 @@ Access the library in Ruby:
 
     require 'octokit'
 
-### Making requests
+## Making requests
 
 [API methods][] are available as client instance methods.
 
@@ -95,7 +97,7 @@ client = Octokit::Client.new(:access_token => 'personal_access_token')
 client.user
 ```
 
-### Additional Query Parameters
+### Additional query parameters
 
 When passing additional parameters to GET based request use the following syntax:
 
@@ -111,7 +113,7 @@ When passing additional parameters to GET based request use the following syntax
 
 [api methods]: http://octokit.github.io/octokit.rb/method_list.html
 
-### Consuming resources
+## Consuming resources
 
 Most methods return a `Resource` object which provides dot notation and `[]`
 access for fields returned in the API response.
@@ -134,7 +136,7 @@ user.rels[:gists].href
 **Note:** URL fields are culled into a separate `.rels` collection for easier
 [Hypermedia](#hypermedia-agent) support.
 
-### Accessing HTTP responses
+## Accessing HTTP responses
 
 While most methods return a `Resource` object or a Boolean, sometimes you may
 need access to the raw HTTP response headers. You can access the last HTTP
@@ -146,6 +148,23 @@ response  = client.last_response
 etag      = response.headers[:etag]
 ```
 
+## Handling errors
+
+When the API returns an error response, Octokit will raise a Ruby exception.
+
+A range of different exceptions can be raised depending on the error returned
+by the API - for example:
+
+* A `400 Bad Request` response will lead to an `Octokit::BadRequest` error 
+* A `403 Forbidden` error with a "rate limited exceeded" message will lead
+  to a `Octokit::TooManyRequests` error
+
+All of the different exception classes inherit from `Octokit::Error` and
+expose the `#response_status`, `#response_headers` and `#response_body`.
+For validation errors, `#errors` will return an `Array` of `Hash`es
+with the detailed information
+[returned by the API](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#client-errors).
+
 ## Authentication
 
 Octokit supports the various [authentication methods supported by the GitHub
@@ -588,7 +607,9 @@ stack = Faraday::RackBuilder.new do |builder|
   builder.use Octokit::Middleware::FollowRedirects
   builder.use Octokit::Response::RaiseError
   builder.use Octokit::Response::FeedParser
-  builder.response :logger
+  builder.response :logger do |logger|
+    logger.filter(/(Authorization: "(token|Bearer) )(\w+)/, '\1[REMOVED]')
+  end
   builder.adapter Faraday.default_adapter
 end
 Octokit.middleware = stack

lib/octokit/client.rb

@@ -238,11 +238,11 @@ def client_without_redirects(options = {})
       conn_opts[:ssl] = { :verify_mode => @ssl_verify_mode } if @ssl_verify_mode
       conn = Faraday.new(conn_opts) do |http|
         if basic_authenticated?
-          http.basic_auth(@login, @password)
+          http.request :basic_auth, @login, @password
         elsif token_authenticated?
-          http.authorization 'token', @access_token
+          http.request :authorization, 'token', @access_token
         elsif bearer_authenticated?
-          http.authorization 'Bearer', @bearer_token
+          http.request :authorization, 'Bearer', @bearer_token
         end
         http.headers['accept'] = options[:accept] if options.key?(:accept)
       end

lib/octokit/client/organizations.rb

@@ -731,7 +731,7 @@ def remove_organization_membership(org, options = {})
       # @return [Sawyer::Resource] Hash representing the new migration.
       # @example
       #   @client.start_migration('github', ['github/dotfiles'])
-      # @see https://developer.github.com/v3/orgs/migrations/#start-a-migration
+      # @see https://docs.github.com/en/rest/reference/migrations#start-an-organization-migration
       def start_migration(org, repositories, options = {})
         options = ensure_api_media_type(:migrations, options)
         options[:repositories] = repositories
@@ -744,7 +744,7 @@ def start_migration(org, repositories, options = {})
       #
       # @param org [String, Integer] Organization GitHub login or id.
       # @return [Array<Sawyer::Resource>] Array of migration resources.
-      # @see https://developer.github.com/v3/orgs/migrations/#get-a-list-of-migrations
+      # @see https://docs.github.com/en/rest/reference/migrations#list-organization-migrations
       def migrations(org, options = {})
         options = ensure_api_media_type(:migrations, options)
         paginate "#{Organization.path(org)}/migrations", options
@@ -756,7 +756,7 @@ def migrations(org, options = {})
       #
       # @param org [String, Integer] Organization GitHub login or id.
       # @param id [Integer] ID number of the migration.
-      # @see https://developer.github.com/v3/orgs/migrations/#get-the-status-of-a-migration
+      # @see https://docs.github.com/en/rest/reference/migrations#get-an-organization-migration-status
       def migration_status(org, id, options = {})
         options = ensure_api_media_type(:migrations, options)
         get "#{Organization.path(org)}/migrations/#{id}", options
@@ -768,7 +768,7 @@ def migration_status(org, id, options = {})
       #
       # @param org [String, Integer] Organization GitHub login or id.
       # @param id [Integer] ID number of the migration.
-      # @see https://developer.github.com/v3/orgs/migrations/#download-a-migration-archive
+      # @see https://docs.github.com/en/rest/reference/migrations#download-an-organization-migration-archive
       def migration_archive_url(org, id, options = {})
         options = ensure_api_media_type(:migrations, options)
         url = "#{Organization.path(org)}/migrations/#{id}/archive"
@@ -783,7 +783,7 @@ def migration_archive_url(org, id, options = {})
       #
       # @param org [String, Integer] Organization GitHub login or id.
       # @param id [Integer] ID number of the migration.
-      # @see https://developer.github.com/v3/orgs/migrations/#delete-a-migration-archive
+      # @see https://docs.github.com/en/rest/reference/migrations#delete-an-organization-migration-archive
       def delete_migration_archive(org, id, options = {})
         options = ensure_api_media_type(:migrations, options)
         delete "#{Organization.path(org)}/migrations/#{id}/archive", options
@@ -796,7 +796,7 @@ def delete_migration_archive(org, id, options = {})
       # @param org [String, Integer] Organization GitHub login or id.
       # @param id [Integer] ID number of the migration.
       # @param repo [String] Name of the repository.
-      # @see https://developer.github.com/v3/orgs/migrations/#unlock-a-repository
+      # @see https://docs.github.com/en/rest/reference/migrations#unlock-an-organization-repository
       def unlock_repository(org, id, repo, options = {})
         options = ensure_api_media_type(:migrations, options)
         delete "#{Organization.path(org)}/migrations/#{id}/repos/#{repo}/lock", options

lib/octokit/client/pub_sub_hubbub.rb

@@ -91,9 +91,9 @@ def pub_sub_hubbub_request(options = {})
         conn = Faraday.new(:url => @api_endpoint) do |http|
           http.headers[:user_agent] = user_agent
           if basic_authenticated?
-            http.basic_auth(@login, @password)
+            http.request :basic_auth, @login, @password
           elsif token_authenticated?
-            http.authorization 'token', @access_token
+            http.request :authorization, 'token', @access_token
           end
           http.request  :url_encoded
           http.use Octokit::Response::RaiseError

lib/octokit/connection.rb

@@ -107,13 +107,13 @@ def agent
         http.headers[:content_type] = "application/json"
         http.headers[:user_agent] = user_agent
         if basic_authenticated?
-          http.basic_auth(@login, @password)
+          http.request :basic_auth, @login, @password
         elsif token_authenticated?
-          http.authorization 'token', @access_token
+          http.request :authorization, 'token', @access_token
         elsif bearer_authenticated?
-          http.authorization 'Bearer', @bearer_token
+          http.request :authorization, 'Bearer', @bearer_token
         elsif application_authenticated?
-          http.basic_auth(@client_id, @client_secret)
+          http.request :basic_auth, @client_id, @client_secret
         end
       end
     end
@@ -176,7 +176,7 @@ def sawyer_options
         :links_parser => Sawyer::LinkParsers::Simple.new
       }
       conn_opts = @connection_options
-      conn_opts[:builder] = @middleware if @middleware
+      conn_opts[:builder] = @middleware.dup if @middleware
       conn_opts[:proxy] = @proxy if @proxy
       if conn_opts[:ssl].nil?
         conn_opts[:ssl] = { :verify_mode => @ssl_verify_mode } if @ssl_verify_mode

lib/octokit/enterprise_management_console_client/management_console.rb

@@ -11,7 +11,7 @@ module ManagementConsole
       # @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)
         conn = faraday_configuration
@@ -156,7 +156,7 @@ def password_hash
     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|
         http.headers[:user_agent] = user_agent

lib/octokit/middleware/follow_redirects.rb

@@ -86,7 +86,10 @@ def update_env(env, request_body, response)
         original_url = env[:url]
         env[:url] += safe_escape(response["location"])
         unless same_host?(original_url, env[:url])
-          env[:request_headers].delete("Authorization")
+          # HACK: Faraday’s Authorization middlewares don’t touch the request if the `Authorization` header is set.
+          #       This is a workaround to drop authentication info.
+          #       See https://github.com/octokit/octokit.rb/pull/1359#issuecomment-925609697
+          env[:request_headers]["Authorization"] = "dummy"
         end
 
         if convert_to_get?(response)

lib/octokit/version.rb

@@ -5,7 +5,7 @@ module Octokit
 
   # Current minor release.
   # @return [Integer]
-  MINOR = 21
+  MINOR = 22
 
   # Current patch level.
   # @return [Integer]

spec/helper.rb

@@ -9,7 +9,10 @@
 require 'webmock/rspec'
 require 'base64'
 require 'jwt'
-require 'pry-byebug'
+# latest version of pry-byebug is not compatible with Ruby 3.2.0
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.2.0')
+  require 'pry-byebug'
+end
 
 WebMock.disable_net_connect!()
 

spec/octokit/client_spec.rb

@@ -599,7 +599,7 @@
 
       assert_requested original_request
       assert_requested(:get, "https://example.com/bar") { |req|
-        req.headers["Authorization"].nil?
+        req.headers["Authorization"] == "dummy"
       }
     end