octokit 4.13.0 → 4.19.0

data/lib/octokit/client/apps.rb

@@ -4,11 +4,23 @@ module Octokit
     # Methods for the Apps API
     module Apps
 
+      # Get the authenticated App
+      #
+      # @param options [Hash] A customizable set of options
+      #
+      # @see https://developer.github.com/v3/apps/#get-the-authenticated-app
+      #
+      # @return [Sawyer::Resource] App information
+      def app(options = {})
+        opts = ensure_api_media_type(:integrations, options)
+        get "app", opts
+      end
+
       # Find all installations that belong to an App
       #
       # @param options [Hash] A customizable set of options
       #
-      # @see https://developer.github.com/v3/apps/#find-installations
+      # @see https://developer.github.com/v3/apps/#list-installations
       #
       # @return [Array<Sawyer::Resource>] the total_count and an array of installations
       def find_app_installations(options = {})
@@ -31,7 +43,7 @@ module Octokit
       #
       # @param options [Hash] A customizable set of options
       #
-      # @see https://developer.github.com/v3/apps/#list-installations-for-user
+      # @see https://developer.github.com/v3/apps/installations/#list-installations-for-a-user
       #
       # @return [Sawyer::Resource] the total_count and an array of installations
       def find_user_installations(options = {})
@@ -45,7 +57,7 @@ module Octokit
       #
       # @param id [Integer] Installation id
       #
-      # @see https://developer.github.com/v3/apps/#get-a-single-installation
+      # @see https://developer.github.com/v3/apps/#get-an-installation
       #
       # @return [Sawyer::Resource] Installation information
       def installation(id, options = {})
@@ -58,7 +70,7 @@ module Octokit
       # @param installation [Integer] The id of a GitHub App Installation
       # @param options [Hash] A customizable set of options
       #
-      # @see https://developer.github.com/v3/apps/#find-installations
+      # @see https://developer.github.com/v3/apps/#create-a-new-installation-token
       #
       # @return [<Sawyer::Resource>] An installation token
       def create_app_installation_access_token(installation, options = {})
@@ -82,7 +94,7 @@ module Octokit
       # @param organization [String] Organization GitHub login
       # @param options [Hash] A customizable set of options
       #
-      # @see https://developer.github.com/v3/apps/#find-organization-installation
+      # @see https://developer.github.com/v3/apps/#get-an-organization-installation
       #
       # @return [Sawyer::Resource] Installation information
       def find_organization_installation(organization, options = {})
@@ -95,7 +107,7 @@ module Octokit
       # @param repo [String] A GitHub repository
       # @param options [Hash] A customizable set of options
       #
-      # @see https://developer.github.com/v3/apps/#find-repository-installation
+      # @see https://developer.github.com/v3/apps/#get-a-repository-installation
       #
       # @return [Sawyer::Resource] Installation information
       def find_repository_installation(repo, options = {})
@@ -108,7 +120,7 @@ module Octokit
       # @param user [String] GitHub user login
       # @param options [Hash] A customizable set of options
       #
-      # @see https://developer.github.com/v3/apps/#find-user-installation
+      # @see https://developer.github.com/v3/apps/#get-a-user-installation
       #
       # @return [Sawyer::Resource] Installation information
       def find_user_installation(user, options = {})
@@ -119,6 +131,7 @@ module Octokit
       # List repositories that are accessible to the authenticated installation
       #
       # @param options [Hash] A customizable set of options
+      #
       # @see https://developer.github.com/v3/apps/installations/#list-repositories
       #
       # @return [Sawyer::Resource] the total_count and an array of repositories
@@ -195,7 +208,7 @@ module Octokit
       # @param installation [Integer] The id of a GitHub App Installation
       # @param options [Hash] A customizable set of options
       #
-      # @see https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/identifying-users-for-github-apps/
+      # @see https://developer.github.com/v3/apps/installations/#list-repositories-accessible-to-the-user-for-an-installation
       #
       # @return [Sawyer::Resource] the total_count and an array of repositories
       def find_installation_repositories_for_user(installation, options = {})
@@ -204,6 +217,19 @@ module Octokit
           data.repositories.concat last_response.data.repositories
         end
       end
+
+      # Delete an installation and uninstall a GitHub App
+      #
+      # @param installation [Integer] The id of a GitHub App Installation
+      # @param options [Hash] A customizable set of options
+      #
+      # @see https://developer.github.com/v3/apps/#delete-an-installation
+      #
+      # @return [Boolean] Success
+      def delete_installation(installation, options = {})
+        opts = ensure_api_media_type(:uninstall_github_app, options)
+        boolean_from_response :delete, "app/installations/#{installation}", opts
+      end
     end
   end
 end

data/lib/octokit/client/authorizations.rb

@@ -59,7 +59,7 @@ module Octokit
       #  client = Octokit::Client.new(:login => 'ctshryock', :password => 'secret')
       #  client.create_authorization({:idempotent => true, :client_id => 'xxxx', :client_secret => 'yyyy', :scopes => ["user"]})
       def create_authorization(options = {})
-        # Techincally we can omit scopes as GitHub has a default, however the
+        # Technically we can omit scopes as GitHub has a default, however the
         # API will reject us if we send a POST request with an empty body.
         options = options.dup
         if options.delete :idempotent
@@ -140,74 +140,6 @@ module Octokit
           sort
       end
 
-      # Check if a token is valid.
-      #
-      # Applications can check if a token is valid without rate limits.
-      #
-      # @param token [String] 40 character GitHub OAuth access token
-      #
-      # @return [Sawyer::Resource] A single authorization for the authenticated user
-      # @see https://developer.github.com/v3/oauth_authorizations/#check-an-authorization
-      # @example
-      #  client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
-      #  client.check_application_authorization('deadbeef1234567890deadbeef987654321')
-      def check_application_authorization(token, options = {})
-        opts = options.dup
-        key    = opts.delete(:client_id)     || client_id
-        secret = opts.delete(:client_secret) || client_secret
-
-        as_app(key, secret) do |app_client|
-          app_client.get "applications/#{client_id}/tokens/#{token}", opts
-        end
-      end
-
-      # Reset a token
-      #
-      # Applications can reset a token without requiring a user to re-authorize.
-      #
-      # @param token [String] 40 character GitHub OAuth access token
-      #
-      # @return [Sawyer::Resource] A single authorization for the authenticated user
-      # @see https://developer.github.com/v3/oauth_authorizations/#reset-an-authorization
-      # @example
-      #  client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
-      #  client.reset_application_authorization('deadbeef1234567890deadbeef987654321')
-      def reset_application_authorization(token, options = {})
-        opts = options.dup
-        key    = opts.delete(:client_id)     || client_id
-        secret = opts.delete(:client_secret) || client_secret
-
-        as_app(key, secret) do |app_client|
-          app_client.post "applications/#{client_id}/tokens/#{token}", opts
-        end
-      end
-
-      # Revoke a token
-      #
-      # Applications can revoke (delete) a token
-      #
-      # @param token [String] 40 character GitHub OAuth access token
-      #
-      # @return [Boolean] Result
-      # @see https://developer.github.com/v3/oauth_authorizations/#revoke-an-authorization-for-an-application
-      # @example
-      #  client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
-      #  client.revoke_application_authorization('deadbeef1234567890deadbeef987654321')
-      def revoke_application_authorization(token, options = {})
-        opts = options.dup
-        key    = opts.delete(:client_id)     || client_id
-        secret = opts.delete(:client_secret) || client_secret
-
-        as_app(key, secret) do |app_client|
-          app_client.delete "applications/#{client_id}/tokens/#{token}", opts
-
-          app_client.last_response.status == 204
-        end
-      rescue Octokit::NotFound
-        false
-      end
-      alias :delete_application_authorization :revoke_application_authorization
-
       # Revoke all tokens for an app
       #
       # Applications can revoke all of their tokens in a single request
@@ -233,7 +165,7 @@ module Octokit
       def authorize_url(app_id = client_id, options = {})
         opts = options.dup
         if app_id.to_s.empty?
-          raise Octokit::ApplicationCredentialsRequired.new "client_id required"
+          raise Octokit::ApplicationCredentialsRequired, "client_id required"
         end
         authorize_url = opts.delete(:endpoint) || Octokit.web_endpoint
         authorize_url << "login/oauth/authorize?client_id=#{app_id}"

data/lib/octokit/client/checks.rb

@@ -0,0 +1,211 @@
+module Octokit
+  class Client
+
+    # Methods for the Checks API
+    #
+    # @see https://developer.github.com/v3/checks/
+    module Checks
+
+      # Methods for Check Runs
+      #
+      # @see https://developer.github.com/v3/checks/runs/
+
+      # Create a check run
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param name [String] The name of the check
+      # @param head_sha [String] The SHA of the commit to check
+      # @return [Sawyer::Resource] A hash representing the new check run
+      # @see https://developer.github.com/v3/checks/runs/#create-a-check-run
+      # @example Create a check run
+      #   check_run = @client.create_check_run("octocat/Hello-World", "my-check", "7638417db6d59f3c431d3e1f261cc637155684cd")
+      #   check_run.name # => "my-check"
+      #   check_run.head_sha # => "7638417db6d59f3c431d3e1f261cc637155684cd"
+      #   check_run.status # => "queued"
+      def create_check_run(repo, name, head_sha, options = {})
+        ensure_api_media_type(:checks, options)
+        options[:name] = name
+        options[:head_sha] = head_sha
+
+        post "#{Repository.path repo}/check-runs", options
+      end
+
+      # Update a check run
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param id [Integer] The ID of the check run
+      # @return [Sawyer::Resource] A hash representing the updated check run
+      # @see https://developer.github.com/v3/checks/runs/#update-a-check-run
+      # @example Update a check run
+      #   check_run = @client.update_check_run("octocat/Hello-World", 51295429, status: "in_progress")
+      #   check_run.id # => 51295429
+      #   check_run.status # => "in_progress"
+      def update_check_run(repo, id, options = {})
+        ensure_api_media_type(:checks, options)
+
+        patch "#{Repository.path repo}/check-runs/#{id}", options
+      end
+
+      # List check runs for a specific ref
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param ref [String] A SHA, branch name, or tag name
+      # @param options [Hash] A set of optional filters
+      # @option options [String] :check_name Returns check runs with the specified <tt>name</tt>
+      # @option options [String] :status Returns check runs with the specified <tt>status</tt>
+      # @option options [String] :filter Filters check runs by their <tt>completed_at</tt> timestamp
+      # @return [Sawyer::Resource] A hash representing a collection of check runs
+      # @see https://developer.github.com/v3/checks/runs/#list-check-runs-for-a-specific-ref
+      # @example List check runs for a specific ref
+      #   result = @client.check_runs_for_ref("octocat/Hello-World", "7638417db6d59f3c431d3e1f261cc637155684cd", status: "in_progress")
+      #   result.total_count # => 1
+      #   result.check_runs.count # => 1
+      #   result.check_runs[0].id # => 51295429
+      #   result.check_runs[0].status # => "in_progress"
+      def check_runs_for_ref(repo, ref, options = {})
+        ensure_api_media_type(:checks, options)
+
+        get "#{Repository.path repo}/commits/#{ref}/check-runs", options
+      end
+      alias :list_check_runs_for_ref :check_runs_for_ref
+
+      # List check runs in a check suite
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param id [Integer] The ID of the check suite
+      # @param options [Hash] A set of optional filters
+      # @option options [String] :check_name Returns check runs with the specified <tt>name</tt>
+      # @option options [String] :status Returns check runs with the specified <tt>status</tt>
+      # @option options [String] :filter Filters check runs by their <tt>completed_at</tt> timestamp
+      # @return [Sawyer::Resource] A hash representing a collection of check runs
+      # @see https://developer.github.com/v3/checks/runs/#list-check-runs-in-a-check-suite
+      # @example List check runs in a check suite
+      #   result = @client.check_runs_for_check_suite("octocat/Hello-World", 50440400, status: "in_progress")
+      #   result.total_count # => 1
+      #   result.check_runs.count # => 1
+      #   result.check_runs[0].check_suite.id # => 50440400
+      #   result.check_runs[0].status # => "in_progress"
+      def check_runs_for_check_suite(repo, id, options = {})
+        ensure_api_media_type(:checks, options)
+
+        get "#{Repository.path repo}/check-suites/#{id}/check-runs", options
+      end
+      alias :list_check_runs_for_check_suite :check_runs_for_check_suite
+
+      # Get a single check run
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param id [Integer] The ID of the check run
+      # @return [Sawyer::Resource] A hash representing the check run
+      # @see https://developer.github.com/v3/checks/runs/#get-a-single-check-run
+      def check_run(repo, id, options = {})
+        ensure_api_media_type(:checks, options)
+
+        get "#{Repository.path repo}/check-runs/#{id}", options
+      end
+
+      # List annotations for a check run
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param id [Integer] The ID of the check run
+      # @return [Array<Sawyer::Resource>] An array of hashes representing check run annotations
+      # @see https://developer.github.com/v3/checks/runs/#list-annotations-for-a-check-run
+      # @example List annotations for a check run
+      #   annotations = @client.check_run_annotations("octocat/Hello-World", 51295429)
+      #   annotations.count # => 1
+      #   annotations[0].path # => "README.md"
+      #   annotations[0].message # => "Looks good!"
+      def check_run_annotations(repo, id, options = {})
+        ensure_api_media_type(:checks, options)
+
+        get "#{Repository.path repo}/check-runs/#{id}/annotations", options
+      end
+
+      # Methods for Check Suites
+      #
+      # @see https://developer.github.com/v3/checks/suites/
+
+      # Get a single check suite
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param id [Integer] The ID of the check suite
+      # @return [Sawyer::Resource] A hash representing the check suite
+      # @see https://developer.github.com/v3/checks/suites/#get-a-single-check-suite
+      def check_suite(repo, id, options = {})
+        ensure_api_media_type(:checks, options)
+
+        get "#{Repository.path repo}/check-suites/#{id}", options
+      end
+
+      # List check suites for a specific ref
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param ref [String] A SHA, branch name, or tag name
+      # @param options [Hash] A set of optional filters
+      # @option options [Integer] :app_id Filters check suites by GitHub App <tt>id</tt>
+      # @option options [String] :check_name Filters checks suites by the <tt>name</tt> of the check run
+      # @return [Sawyer::Resource] A hash representing a collection of check suites
+      # @see https://developer.github.com/v3/checks/suites/#list-check-suites-for-a-specific-ref
+      # @example List check suites for a specific ref
+      #   result = @client.check_suites_for_ref("octocat/Hello-World", "7638417db6d59f3c431d3e1f261cc637155684cd", app_id: 76765)
+      #   result.total_count # => 1
+      #   result.check_suites.count # => 1
+      #   result.check_suites[0].id # => 50440400
+      #   result.check_suites[0].app.id # => 76765
+      def check_suites_for_ref(repo, ref, options = {})
+        ensure_api_media_type(:checks, options)
+
+        get "#{Repository.path repo}/commits/#{ref}/check-suites", options
+      end
+      alias :list_check_suites_for_ref :check_suites_for_ref
+
+      # Set preferences for check suites on a repository
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param options [Hash] Preferences to set
+      # @return [Sawyer::Resource] A hash representing the repository's check suite preferences
+      # @see https://developer.github.com/v3/checks/suites/#set-preferences-for-check-suites-on-a-repository
+      # @example Set preferences for check suites on a repository
+      #   result = @client.set_check_suite_preferences("octocat/Hello-World", auto_trigger_checks: [{ app_id: 76765, setting: false }])
+      #   result.preferences.auto_trigger_checks.count # => 1
+      #   result.preferences.auto_trigger_checks[0].app_id # => 76765
+      #   result.preferences.auto_trigger_checks[0].setting # => false
+      #   result.repository.full_name # => "octocat/Hello-World"
+      def set_check_suite_preferences(repo, options = {})
+        ensure_api_media_type(:checks, options)
+
+        patch "#{Repository.path repo}/check-suites/preferences", options
+      end
+
+      # Create a check suite
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param head_sha [String] The SHA of the commit to check
+      # @return [Sawyer::Resource] A hash representing the new check suite
+      # @see https://developer.github.com/v3/checks/suites/#create-a-check-suite
+      # @example Create a check suite
+      #   check_suite = @client.create_check_suite("octocat/Hello-World", "7638417db6d59f3c431d3e1f261cc637155684cd")
+      #   check_suite.head_sha # => "7638417db6d59f3c431d3e1f261cc637155684cd"
+      #   check_suite.status # => "queued"
+      def create_check_suite(repo, head_sha, options = {})
+        ensure_api_media_type(:checks, options)
+        options[:head_sha] = head_sha
+
+        post "#{Repository.path repo}/check-suites", options
+      end
+
+      # Rerequest check suite
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param id [Integer] The ID of the check suite
+      # @return [Boolean] True if successful, raises an error otherwise
+      # @see https://developer.github.com/v3/checks/suites/#rerequest-check-suite
+      def rerequest_check_suite(repo, id, options = {})
+        ensure_api_media_type(:checks, options)
+
+        post "#{Repository.path repo}/check-suites/#{id}/rerequest", options
+        true
+      end
+    end
+  end
+end

data/lib/octokit/client/commit_branches.rb

@@ -0,0 +1,20 @@
+module Octokit
+  class Client
+
+    # Methods for the Branches for HEAD API
+    #
+    # @see https://developer.github.com/v3/repos/commits/
+    module CommitBranches
+
+      # List branches for a single HEAD commit
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param sha [String] The SHA of the commit whose branches will be fetched
+      # @return [Array]  List of branches
+      # @see https://developer.github.com/v3/repos/commits/#list-branches-for-head-commit
+      def commit_branches(repo, sha, options = {})
+        paginate "#{Repository.path repo}/commits/#{sha}/branches-where-head", options
+      end
+    end
+  end
+end

data/lib/octokit/client/commit_pulls.rb

@@ -0,0 +1,20 @@
+module Octokit
+  class Client
+
+    # Methods for the Commit Pulls API
+    #
+    # @see https://developer.github.com/v3/repos/comments/
+    module CommitPulls
+
+      # List pulls for a single commit
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @param sha [String] The SHA of the commit whose pulls will be fetched
+      # @return [Array]  List of commit pulls
+      # @see https://developer.github.com/v3/repos/commits/#list-pull-requests-associated-with-commit
+      def commit_pulls(repo, sha, options = {})
+        paginate "#{Repository.path repo}/commits/#{sha}/pulls", options
+      end
+    end
+  end
+end