octokit 4.15.0 → 4.21.0

data/lib/octokit/client/refs.rb

@@ -23,6 +23,18 @@ module Octokit
       alias :references :refs
       alias :list_references :refs
 
+      # Fetch matching refs
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @param ref [String] The ref, e.g. <tt>tags/v0.0.3</tt> or <tt>heads/rails-3</tt>
+      # @return [Array<Sawyer::Resource>] The reference matching the given repo and the ref id
+      # @see https://developer.github.com/v3/git/refs/#list-matching-references
+      # @example Fetch refs matching  tags/v2 for sferik/rails_admin
+      #   Octokit.ref("sferik/rails_admin","tags/v2")
+      def matching_refs(repo, ref, options = {})
+        paginate "#{Repository.path repo}/git/matching-refs/#{ref}", options
+      end
+
       # Fetch a given reference
       #
       # @param repo [Integer, String, Repository, Hash] A GitHub repository
@@ -60,11 +72,13 @@ module Octokit
       # @param repo [Integer, String, Repository, Hash] A GitHub repository
       # @param ref [String] The ref, e.g. <tt>tags/v0.0.3</tt>
       # @param sha [String] A SHA, e.g. <tt>827efc6d56897b048c772eb4087f854f46256132</tt>
-      # @param force [Boolean] A flag indicating one wants to force the update to make sure the update is a fast-forward update.
+      # @param force [Boolean] A flag indicating whether to force the update or to make sure the update is a fast-forward update.
       # @return [Array<Sawyer::Resource>] The list of references updated
       # @see https://developer.github.com/v3/git/refs/#update-a-reference
       # @example Force update heads/sc/featureA for octocat/Hello-World with sha aa218f56b14c9653891f9e74264a383fa43fefbd
       #   Octokit.update_ref("octocat/Hello-World", "heads/sc/featureA", "aa218f56b14c9653891f9e74264a383fa43fefbd")
+      # @example Fast-forward update heads/sc/featureA for octocat/Hello-World with sha aa218f56b14c9653891f9e74264a383fa43fefbd
+      #   Octokit.update_ref("octocat/Hello-World", "heads/sc/featureA", "aa218f56b14c9653891f9e74264a383fa43fefbd", false)
       def update_ref(repo, ref, sha, force = true, options = {})
         parameters = {
           :sha  => sha,
@@ -79,11 +93,13 @@ module Octokit
       # @param repo [Integer, String, Repository, Hash] A GitHub repository
       # @param branch [String] The ref, e.g. <tt>feature/new-shiny</tt>
       # @param sha [String] A SHA, e.g. <tt>827efc6d56897b048c772eb4087f854f46256132</tt>
-      # @param force [Boolean] A flag indicating one wants to force the update to make sure the update is a fast-forward update.
+      # @param force [Boolean] A flag indicating whether to force the update or to make sure the update is a fast-forward update.
       # @return [Array<Sawyer::Resource>] The list of references updated
       # @see https://developer.github.com/v3/git/refs/#update-a-reference
       # @example Force update heads/sc/featureA for octocat/Hello-World with sha aa218f56b14c9653891f9e74264a383fa43fefbd
-      #   Octokit.update_branch("octocat/Hello-World","sc/featureA", "aa218f56b14c9653891f9e74264a383fa43fefbd")
+      #   Octokit.update_branch("octocat/Hello-World", "sc/featureA", "aa218f56b14c9653891f9e74264a383fa43fefbd")
+      # @example Fast-forward update heads/sc/featureA for octocat/Hello-World with sha aa218f56b14c9653891f9e74264a383fa43fefbd
+      #   Octokit.update_branch("octocat/Hello-World", "sc/featureA", "aa218f56b14c9653891f9e74264a383fa43fefbd", false)
       def update_branch(repo, branch, sha, force = true, options = {})
         update_ref repo, "heads/#{branch}", sha, force, options
       end

data/lib/octokit/client/repositories.rb

@@ -32,7 +32,7 @@ module Octokit
 
       # Edit a repository
       #
-      # @see https://developer.github.com/v3/repos/#edit
+      # @see https://developer.github.com/v3/repos/#update-a-repository
       # @param repo [String, Hash, Repository] A GitHub repository
       # @param options [Hash] Repository information to update
       # @option options [String] :name Name of the repo
@@ -429,7 +429,7 @@ module Octokit
       # @example List topics for octokit/octokit.rb
       #   Octokit.topics('octokit/octokit.rb')
       # @example List topics for octokit/octokit.rb
-      #   client.topics('octokit/octokit.rb')      
+      #   client.topics('octokit/octokit.rb')
       def topics(repo, options = {})
         opts = ensure_api_media_type(:topics, options)
         paginate "#{Repository.path repo}/topics", opts
@@ -586,14 +586,14 @@ module Octokit
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository.
       # @param branch [String] Branch name
-      # @option options [Hash] :required_status_checks If not null, the following keys are required:  
-      #   <tt>:enforce_admins [boolean] Enforce required status checks for repository administrators.</tt>  
-      #   <tt>:strict [boolean] Require branches to be up to date before merging.</tt>  
-      #   <tt>:contexts [Array] The list of status checks to require in order to merge into this branch</tt>  
+      # @option options [Hash] :required_status_checks If not null, the following keys are required:
+      #   <tt>:enforce_admins [boolean] Enforce required status checks for repository administrators.</tt>
+      #   <tt>:strict [boolean] Require branches to be up to date before merging.</tt>
+      #   <tt>:contexts [Array] The list of status checks to require in order to merge into this branch</tt>
       #
       # @option options [Hash] :restrictions If not null, the following keys are required:
-      #   <tt>:users [Array] The list of user logins with push access</tt>  
-      #   <tt>:teams [Array] The list of team slugs with push access</tt>.  
+      #   <tt>:users [Array] The list of user logins with push access</tt>
+      #   <tt>:teams [Array] The list of team slugs with push access</tt>.
       #
       #   Teams and users restrictions are only available for organization-owned repositories.
       # @return [Sawyer::Resource] The protected branch
@@ -640,6 +640,24 @@ module Octokit
         boolean_from_response :delete, "#{Repository.path repo}/branches/#{branch}/protection", opts
       end
 
+      # Rename a single branch from a repository
+      #
+      # Requires authenticated client
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @param branch [String] Current branch name
+      # @param new_name [String] New branch name
+      # @return [Sawyer::Resource] The renamed branch
+      # @see https://developer.github.com/v3/repos/#rename-a-branch
+      # @example
+      #   @client.rename_branch('octokit/octokit.rb', 'master', 'main')
+      def rename_branch(repo, branch, new_name, options = {})
+        params = {
+          new_name: new_name,
+        }
+        post "#{Repository.path repo}/branches/#{branch}/rename", params.merge(options)
+      end
+
       # List users available for assigning to issues.
       #
       # Requires authenticated client for private repos.
@@ -720,6 +738,62 @@ module Octokit
       def delete_subscription(repo, options = {})
         boolean_from_response :delete, "#{Repository.path repo}/subscription", options
       end
+
+      # Create a repository dispatch event
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @param event_type [String] A custom webhook event name.
+      # @option options [Hash] :client_payload payload with extra information
+      #   about the webhook event that your action or worklow may use.
+      #
+      # @return [Boolean] True if event was dispatched, false otherwise.
+      # @see https://developer.github.com/v3/repos/#create-a-repository-dispatch-event
+      def dispatch_event(repo, event_type, options = {})
+        boolean_from_response :post, "#{Repository.path repo}/dispatches", options.merge({ event_type: event_type })
+      end
+
+      # Check to see if vulnerability alerts are enabled for a repository
+      #
+      # The authenticated user must have admin access to the repository.
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @return [Boolean] True if vulnerability alerts are enabled, false otherwise.
+      # @see https://docs.github.com/en/rest/reference/repos#check-if-vulnerability-alerts-are-enabled-for-a-repository
+      #
+      # @example
+      #   @client.vulnerability_alerts_enabled?("octokit/octokit.rb")
+      def vulnerability_alerts_enabled?(repo, options = {})
+        opts = ensure_api_media_type(:vulnerability_alerts, options)
+        boolean_from_response(:get, "#{Repository.path repo}/vulnerability-alerts", opts)
+      end
+
+      # Enable vulnerability alerts for a repository
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @param options [Hash]
+      #
+      # @return [Boolean] True if vulnerability alerts enabled, false otherwise.
+      # @see https://docs.github.com/en/rest/reference/repos#enable-vulnerability-alerts
+      # @example Enable vulnerability alerts for a repository
+      #   @client.enable_vulnerability_alerts("octokit/octokit.rb")
+      def enable_vulnerability_alerts(repo, options = {})
+        opts = ensure_api_media_type(:vulnerability_alerts, options)
+        boolean_from_response(:put, "#{Repository.path repo}/vulnerability-alerts", opts)
+      end
+
+      # Disable vulnerability alerts for a repository
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @param options [Hash]
+      #
+      # @return [Boolean] True if vulnerability alerts disabled, false otherwise.
+      # @see https://docs.github.com/en/rest/reference/repos#disable-vulnerability-alerts
+      # @example Disable vulnerability alerts for a repository
+      #   @client.disable_vulnerability_alerts("octokit/octokit.rb")
+      def disable_vulnerability_alerts(repo, options = {})
+        opts = ensure_api_media_type(:vulnerability_alerts, options)
+        boolean_from_response(:delete, "#{Repository.path repo}/vulnerability-alerts", opts)
+      end
     end
   end
 end

data/lib/octokit/client/search.rb

@@ -44,7 +44,7 @@ module Octokit
       # @option options [Integer] :page Page of paginated results
       # @option options [Integer] :per_page Number of items per page
       # @return [Sawyer::Resource] Search results object
-      # @see https://developer.github.com/v3/search/#search-issues
+      # @see https://developer.github.com/v3/search/#search-issues-and-pull-requests
       def search_issues(query, options = {})
         search "search/issues", query, options
       end

data/lib/octokit/client/users.rb

@@ -340,6 +340,92 @@ module Octokit
       end
       alias :watched :subscriptions
 
+      # Initiates the generation of a migration archive.
+      #
+      # Requires authenticated user.
+      #
+      # @param repositories [Array<String>] :repositories Repositories for the organization.
+      # @option options [Boolean, optional] :lock_repositories Indicates whether repositories should be locked during migration
+      # @option options [Boolean, optional] :exclude_attachments Exclude attachments fro the migration data
+      # @return [Sawyer::Resource] Hash representing the new migration.
+      # @example
+      #   @client.start_migration(['octocat/hello-world'])
+      # @see https://docs.github.com/en/rest/reference/migrations#start-a-user-migration
+      def start_user_migration(repositories, options = {})
+        options = ensure_api_media_type(:migrations, options)
+        options[:repositories] = repositories
+        post "user/migrations", options
+      end
+
+      # Lists the most recent migrations.
+      #
+      # Requires authenticated user.
+      #
+      # @return [Array<Sawyer::Resource>] Array of migration resources.
+      # @see https://docs.github.com/en/rest/reference/migrations#list-user-migrations
+      def user_migrations(options = {})
+        options = ensure_api_media_type(:migrations, options)
+        paginate "user/migrations", options
+      end
+
+      # Fetches the status of a migration.
+      #
+      # Requires authenticated user.
+      #
+      # @param id [Integer] ID number of the migration.
+      # @see https://docs.github.com/en/rest/reference/migrations#get-a-user-migration-status
+      def user_migration_status(id, options = {})
+        options = ensure_api_media_type(:migrations, options)
+        get "user/migrations/#{id}", options
+      end
+
+      # Fetches the URL to a migration archive.
+      #
+      # Requires authenticated user.
+      #
+      # @param id [Integer] ID number of the migration.
+      # @see https://docs.github.com/en/rest/reference/migrations#download-a-user-migration-archive
+      def user_migration_archive_url(id, options = {})
+        options = ensure_api_media_type(:migrations, options)
+        url = "user/migrations/#{id}/archive"
+
+        response = client_without_redirects(options).get(url)
+        response.headers['location']
+      end
+
+      # Deletes a previous migration archive.
+      #
+      # Requires authenticated user.
+      #
+      # @param id [Integer] ID number of the migration.
+      # @see https://docs.github.com/en/rest/reference/migrations#delete-a-user-migration-archive
+      def delete_user_migration_archive(id, options = {})
+        options = ensure_api_media_type(:migrations, options)
+        delete "user/migrations/#{id}/archive", options
+      end
+
+      # List repositories for a user migration.
+      #
+      # Requires authenticated user.
+      #
+      # @param id [Integer] ID number of the migration.
+      # @see https://docs.github.com/en/rest/reference/migrations#list-repositories-for-a-user-migration
+      def user_migration_repositories(id, options = {})
+        options = ensure_api_media_type(:migrations, options)
+        get "user/migrations/#{id}/repositories", options
+      end
+
+      # Unlock a user repository which has been locked by a migration.
+      #
+      # Requires authenticated user.
+      #
+      # @param id [Integer] ID number of the migration.
+      # @param repo [String] Name of the repository.
+      # @see https://docs.github.com/en/rest/reference/migrations#unlock-a-user-repository
+      def unlock_user_repository(id, repo, options = {})
+        options = ensure_api_media_type(:migrations, options)
+        delete "user/migrations/#{id}/repos/#{repo}/lock", options
+      end
     end
 
     private

data/lib/octokit/connection.rb

@@ -113,7 +113,7 @@ module Octokit
         elsif bearer_authenticated?
           http.authorization 'Bearer', @bearer_token
         elsif application_authenticated?
-          http.params = http.params.merge application_authentication
+          http.basic_auth(@client_id, @client_secret)
         end
       end
     end
@@ -155,6 +155,9 @@ module Octokit
 
       @last_response = response = agent.call(method, Addressable::URI.parse(path.to_s).normalize.to_s, data, options)
       response.data
+    rescue Octokit::Error => error
+      @last_response = nil
+      raise error
     end
 
     # Executes the request, checking if it was successful
@@ -162,7 +165,7 @@ module Octokit
     # @return [Boolean] True on success, false otherwise
     def boolean_from_response(method, path, options = {})
       request(method, path, options)
-      @last_response.status == 204
+      [201, 202, 204].include? @last_response.status
     rescue Octokit::NotFound
       false
     end
@@ -177,12 +180,12 @@ module Octokit
       conn_opts[:proxy] = @proxy if @proxy
       if conn_opts[:ssl].nil?
         conn_opts[:ssl] = { :verify_mode => @ssl_verify_mode } if @ssl_verify_mode
-      else 
-        if @connection_options[:ssl][:verify] == false
-          conn_opts[:ssl] = { :verify_mode => 0}
-        else
-          conn_opts[:ssl] = { :verify_mode => @ssl_verify_mode }
-        end
+      else
+        verify = @connection_options[:ssl][:verify]
+        conn_opts[:ssl] = {
+          :verify => verify,
+          :verify_mode => verify == false ? 0 : @ssl_verify_mode
+        }
       end
       opts[:faraday] = Faraday.new(conn_opts)
 

data/lib/octokit/error.rb

@@ -1,7 +1,7 @@
 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
     #
@@ -21,7 +21,7 @@ module Octokit
                   when 406      then Octokit::NotAcceptable
                   when 409      then Octokit::Conflict
                   when 415      then Octokit::UnsupportedMediaType
-                  when 422      then Octokit::UnprocessableEntity
+                  when 422      then error_for_422(body)
                   when 451      then Octokit::UnavailableForLegalReasons
                   when 400..499 then Octokit::ClientError
                   when 500      then Octokit::InternalServerError
@@ -34,9 +34,16 @@ module Octokit
       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)
       @response = response
       super(build_error_message)
+      build_error_context
     end
 
     # Documentation URL returned by the API for some errors
@@ -77,6 +84,8 @@ module Octokit
         Octokit::BillingIssue
       elsif body =~ /Resource protected by organization SAML enforcement/i
         Octokit::SAMLProtected
+      elsif body =~ /suspended your access|This installation has been suspended/i
+        Octokit::InstallationSuspended
       else
         Octokit::Forbidden
       end
@@ -92,6 +101,18 @@ module Octokit
       end
     end
 
+    # Return most appropriate error for 422 HTTP status code
+    # @private
+    def self.error_for_422(body)
+      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
+        Octokit::PathDiffTooLarge
+      else
+        Octokit::UnprocessableEntity
+      end
+    end
+
     # Array of validation errors
     # @return [Array<Hash>] Error info
     def errors
@@ -265,6 +286,10 @@ module Octokit
   # and body matches 'Resource protected by organization SAML enforcement'
   class SAMLProtected < Forbidden; end
 
+  # Raised when GitHub returns a 403 HTTP status code
+  # and body matches 'suspended your access'
+  class InstallationSuspended < Forbidden; end
+
   # Raised when GitHub returns a 404 HTTP status code
   class NotFound < ClientError; end
 
@@ -287,6 +312,14 @@ module Octokit
   # Raised when GitHub returns a 422 HTTP status code
   class UnprocessableEntity < ClientError; end
 
+  # Raised when GitHub returns a 422 HTTP status code
+  # and body matches 'PullRequestReviewComment' and 'commit_id (or end_commit_oid) is not part of the pull request'
+  class CommitIsNotPartOfPullRequest < UnprocessableEntity; end
+
+  # Raised when GitHub returns a 422 HTTP status code and body matches 'Path diff too large'.
+  # It could occur when attempting to post review comments on a "too large" file.
+  class PathDiffTooLarge < UnprocessableEntity; end
+
   # Raised when GitHub returns a 451 HTTP status code
   class UnavailableForLegalReasons < ClientError; end
 
@@ -315,4 +348,5 @@ module Octokit
   # Raised when a repository is created with an invalid format
   class InvalidRepository < ArgumentError; end
 
+  RATE_LIMITED_ERRORS = [Octokit::TooManyRequests, Octokit::AbuseDetected]
 end

data/lib/octokit/preview.rb

@@ -4,10 +4,11 @@ module Octokit
   module Preview
 
     PREVIEW_TYPES = {
+      :applications_api       => 'application/vnd.github.doctor-strange-preview+json'.freeze,
       :branch_protection      => 'application/vnd.github.luke-cage-preview+json'.freeze,
-      :checks                 => 'application/vnd.github.antiope-preview+json'.freeze,
       :commit_search          => 'application/vnd.github.cloak-preview+json'.freeze,
       :commit_pulls           => 'application/vnd.github.groot-preview+json'.freeze,
+      :commit_branches        => 'application/vnd.github.groot-preview+json'.freeze,
       :migrations             => 'application/vnd.github.wyandotte-preview+json'.freeze,
       :licenses               => 'application/vnd.github.drax-preview+json'.freeze,
       :source_imports         => 'application/vnd.github.barred-rock-preview'.freeze,
@@ -18,13 +19,12 @@ module Octokit
       :pages                  => 'application/vnd.github.mister-fantastic-preview+json'.freeze,
       :projects               => 'application/vnd.github.inertia-preview+json'.freeze,
       :traffic                => 'application/vnd.github.spiderman-preview'.freeze,
-      :integrations           => 'application/vnd.github.machine-man-preview+json'.freeze,
       :topics                 => 'application/vnd.github.mercy-preview+json'.freeze,
       :community_profile      => 'application/vnd.github.black-panther-preview+json'.freeze,
       :strict_validation      => 'application/vnd.github.speedy-preview+json'.freeze,
-      :drafts                 => 'application/vnd.github.shadow-cat-preview'.freeze,
       :template_repositories  => 'application/vnd.github.baptiste-preview+json'.freeze,
-      :uninstall_github_app   => 'application/vnd.github.gambit-preview+json'.freeze,
+      :project_card_events    => 'application/vnd.github.starfox-preview+json'.freeze,
+      :vulnerability_alerts   => 'application/vnd.github.dorian-preview+json'.freeze,
     }
 
     def ensure_api_media_type(type, options)

data/lib/octokit/rate_limit.rb

@@ -20,7 +20,7 @@ module Octokit
     # @return [RateLimit]
     def self.from_response(response)
       info = new
-      if response && !response.headers.nil?
+      if response && response.respond_to?(:headers) && !response.headers.nil?
         info.limit = (response.headers['X-RateLimit-Limit'] || 1).to_i
         info.remaining = (response.headers['X-RateLimit-Remaining'] || 1).to_i
         info.resets_at = Time.at((response.headers['X-RateLimit-Reset'] || Time.now).to_i)