octokit 4.14.0 → 4.20.0

data/lib/octokit/client/pull_requests.rb

@@ -11,7 +11,7 @@ module Octokit
       # @overload pull_requests(repo, options)
       #   @param repo [Integer, String, Hash, Repository] A GitHub repository
       #   @param options [Hash] Method options
-      #   @option options [String] :state `open` or `closed`.
+      #   @option options [String] :state `open` or `closed` or `all`.
       # @return [Array<Sawyer::Resource>] Array of pulls
       # @see https://developer.github.com/v3/pulls/#list-pull-requests
       # @example

data/lib/octokit/client/refs.rb

@@ -60,11 +60,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 +81,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_ref("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
@@ -41,11 +41,15 @@ module Octokit
       # @option options [String] :private `true` makes the repository private, and `false` makes it public.
       # @option options [String] :has_issues `true` enables issues for this repo, `false` disables issues.
       # @option options [String] :has_wiki `true` enables wiki for this repo, `false` disables wiki.
+      # @option options [Boolean] :is_template `true` makes the repository a template, `false` makes it not a template.
       # @option options [String] :has_downloads `true` enables downloads for this repo, `false` disables downloads.
       # @option options [String] :default_branch Update the default branch for this repository.
       # @return [Sawyer::Resource] Repository information
       def edit_repository(repo, options = {})
         repo = Repository.new(repo)
+        if options.include? :is_template
+          options = ensure_api_media_type(:template_repositories, options)
+        end
         options[:name] ||= repo.name
         patch "repos/#{repo}", options
       end
@@ -144,6 +148,7 @@ module Octokit
       # @option options [String] :private `true` makes the repository private, and `false` makes it public.
       # @option options [String] :has_issues `true` enables issues for this repo, `false` disables issues.
       # @option options [String] :has_wiki `true` enables wiki for this repo, `false` disables wiki.
+      # @option options [Boolean] :is_template `true` makes this repo available as a template repository, `false` to prevent it.
       # @option options [String] :has_downloads `true` enables downloads for this repo, `false` disables downloads.
       # @option options [String] :organization Short name for the org under which to create the repo.
       # @option options [Integer] :team_id The id of the team that will be granted access to this repository. This is only valid when creating a repo in an organization.
@@ -155,6 +160,9 @@ module Octokit
         opts = options.dup
         organization = opts.delete :organization
         opts.merge! :name => name
+        if opts.include? :is_template
+          opts = ensure_api_media_type(:template_repositories, opts)
+        end
 
         if organization.nil?
           post 'user/repos', opts
@@ -192,6 +200,22 @@ module Octokit
       end
       alias :transfer_repo :transfer_repository
 
+      # Create a repository for a user or organization generated from a template repository
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub template repository
+      # @param name [String] Name of the new repo
+      # @option options [String] :owner Organization or user who the new repository will belong to.
+      # @option options [String] :description Description of the repo
+      # @option options [String] :private `true` makes the repository private, and `false` makes it public.
+      # @option options [Boolean] :include_all_branches `true` copies all branches from the template repository, `false` (default) makes it only copy the master branch.
+      # @return [Sawyer::Resource] Repository info for the new repository
+      def create_repository_from_template(repo, name, options = {})
+        options.merge! :name => name
+        options = ensure_api_media_type(:template_repositories, options)
+        post "#{Repository.path repo}/generate", options
+      end
+      alias :create_repo_from_template :create_repository_from_template
+
       # Hide a public repository
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
@@ -405,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
@@ -562,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
@@ -696,6 +720,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/repository_invitations.rb

@@ -13,7 +13,7 @@ module Octokit
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
       # @param user [String] User GitHub username to add
       # @return [Sawyer::Resource] The repository invitation
-      # @see https://developer.github.com/v3/repos/invitations/#invite-a-user-to-a-repository
+      # @see https://developer.github.com/v3/repos/collaborators/#add-user-as-a-collaborator
       def invite_user_to_repository(repo, user, options = {})
         put "#{Repository.path repo}/collaborators/#{user}", options
       end

data/lib/octokit/client/reviews.rb

@@ -204,6 +204,24 @@ module Octokit
         options = options.merge(reviewers)
         delete "#{Repository.path repo}/pulls/#{id}/requested_reviewers", options
       end
+
+      # Update a review request comment
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param number [Integer] Number ID of the pull request
+      # @param review [Integer] The id of the review
+      # @param body [String] body text of the pull request review.
+      # @param options [Hash] Method options
+      # @see https://developer.github.com/v3/pulls/reviews/#update-a-pull-request-review
+      #
+      # @example
+      #   @client.update_pull_request_review('octokit/octokit.rb', 825, 6505518, 'This is close to perfect! Please address the suggested inline change. And add more about this.')
+      #
+      # @return [Sawyer::Resource] Hash representing the review comment
+      def update_pull_request_review(repo, number, review, body, options = {})
+        options[:body] = body
+        put "#{Repository.path repo}/pulls/#{number}/reviews/#{review}", options
+      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
@@ -63,6 +70,8 @@ module Octokit
         Octokit::TooManyRequests
       elsif body =~ /login attempts exceeded/i
         Octokit::TooManyLoginAttempts
+      elsif body =~ /returns blobs up to [0-9]+ MB/i
+        Octokit::TooLargeContent
       elsif body =~ /abuse/i
         Octokit::AbuseDetected
       elsif body =~ /repository access blocked/i
@@ -71,6 +80,12 @@ module Octokit
         Octokit::UnverifiedEmail
       elsif body =~ /account was suspended/i
         Octokit::AccountSuspended
+      elsif body =~ /billing issue/i
+        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
@@ -86,6 +101,16 @@ 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
+      else
+        Octokit::UnprocessableEntity
+      end
+    end
+
     # Array of validation errors
     # @return [Array<Hash>] Error info
     def errors
@@ -231,6 +256,10 @@ module Octokit
   # and body matches 'login attempts exceeded'
   class TooManyLoginAttempts < Forbidden; end
 
+  # Raised when GitHub returns a 403 HTTP status code
+  # and body matches 'returns blobs up to [0-9]+ MB'
+  class TooLargeContent < Forbidden; end
+
   # Raised when GitHub returns a 403 HTTP status code
   # and body matches 'abuse'
   class AbuseDetected < Forbidden; end
@@ -247,6 +276,18 @@ module Octokit
   # and body matches 'account was suspended'
   class AccountSuspended < Forbidden; end
 
+  # Raised when GitHub returns a 403 HTTP status code
+  # and body matches 'billing issue'
+  class BillingIssue < Forbidden; end
+
+  # Raised when GitHub returns a 403 HTTP status code
+  # 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
 
@@ -269,6 +310,10 @@ 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 451 HTTP status code
   class UnavailableForLegalReasons < ClientError; end
 
@@ -297,4 +342,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