octokit 4.14.0 → 4.21.0

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

@@ -23,7 +23,6 @@ module Octokit
       #   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
 
@@ -41,8 +40,6 @@ module Octokit
       #   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
 
@@ -63,8 +60,6 @@ module Octokit
       #   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
@@ -86,8 +81,6 @@ module Octokit
       #   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
@@ -99,8 +92,6 @@ module Octokit
       # @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
 
@@ -116,8 +107,6 @@ module Octokit
       #   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
 
@@ -132,8 +121,6 @@ module Octokit
       # @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
 
@@ -153,8 +140,6 @@ module Octokit
       #   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
@@ -172,8 +157,6 @@ module Octokit
       #   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
 
@@ -188,7 +171,6 @@ module Octokit
       #   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
@@ -201,8 +183,6 @@ module Octokit
       # @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

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

data/lib/octokit/client/contents.rb

@@ -16,6 +16,8 @@ module Octokit
       # @see https://developer.github.com/v3/repos/contents/#get-the-readme
       # @example Get the readme file for a repo
       #   Octokit.readme("octokit/octokit.rb")
+      # @example Get the readme file for a particular branch of the repo
+      #   Octokit.readme("octokit/octokit.rb", :query => {:ref => 'some-other-branch'})
       def readme(repo, options={})
         get "#{Repository.path repo}/readme", options
       end
@@ -29,6 +31,8 @@ module Octokit
       # @see https://developer.github.com/v3/repos/contents/#get-contents
       # @example List the contents of lib/octokit.rb
       #   Octokit.contents("octokit/octokit.rb", :path => 'lib/octokit.rb')
+      # @example Lists the contents of lib /octokit.rb on a particular branch
+      #   Octokit.contents("octokit/octokit.rb", :path => 'lib/octokit.rb', :query => {:ref => 'some-other-branch'})
       def contents(repo, options={})
         options = options.dup
         repo_path = options.delete :path

data/lib/octokit/client/deployments.rb

@@ -43,6 +43,16 @@ module Octokit
         post("#{Repository.path repo}/deployments", options)
       end
 
+      # Delete a Deployment
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @param deployment_id [Integer, String, Repository, Hash] A GitHub repository
+      # @return [No Content]
+      # @see https://developer.github.com/v3/repos/deployments/#delete-a-deployment
+      def delete_deployment(repo, deployment_id, options = {})
+        delete("#{Repository.path repo}/deployments/#{deployment_id}", options)
+      end
+
       # List all statuses for a Deployment
       #
       # @param deployment_url [String] A URL for a deployment resource

data/lib/octokit/client/events.rb

@@ -131,6 +131,7 @@ module Octokit
       # @example List all issues events for issue #38 on octokit/octokit.rb
       #   Octokit.issue_events("octokit/octokit.rb", 38)
       def issue_events(repo, number, options = {})
+        options = ensure_api_media_type(:project_card_events, options)
         paginate "#{Repository.path repo}/issues/#{number}/events", options
       end
 

data/lib/octokit/client/issues.rb

@@ -81,6 +81,7 @@ module Octokit
       # @param body [String] An optional concise description
       # @param options [Hash] A customizable set of options.
       # @option options [String] :assignee User login.
+      # @option options [Array<String>] :assignees User login.
       # @option options [Integer] :milestone Milestone number.
       # @option options [String] :labels List of comma separated Label names. Example: <tt>bug,ui,@high</tt>.
       # @return [Sawyer::Resource] Your newly created issue
@@ -120,6 +121,7 @@ module Octokit
       # @param number [Integer] Number ID of the issue
       # @param options [Hash] A customizable set of options.
       # @option options [String] :assignee User login.
+      # @option options [Array<String>] :assignees User login.
       # @option options [Integer] :milestone Milestone number.
       # @option options [Array<String>] :labels List of Label names. Example: <tt>['bug', 'ui', '@high']</tt>.
       # @return [Sawyer::Resource] The updated Issue
@@ -136,6 +138,7 @@ module Octokit
       # @param number [Integer] Number ID of the issue
       # @param options [Hash] A customizable set of options.
       # @option options [String] :assignee User login.
+      # @option options [Array<String>] :assignees User login.
       # @option options [Integer] :milestone Milestone number.
       # @option options [Array<String>] :labels List of Label names. Example: <tt>['bug', 'ui', '@high']</tt>.
       # @return [Sawyer::Resource] The updated Issue
@@ -179,6 +182,7 @@ module Octokit
       #   @param body [String] Updated body of the issue
       #   @param options [Hash] A customizable set of options.
       #   @option options [String] :assignee User login.
+      #   @option options [Array<String>] :assignees User login.
       #   @option options [Integer] :milestone Milestone number.
       #   @option options [String] :labels List of comma separated Label names. Example: <tt>bug,ui,@high</tt>.
       #   @option options [String] :state State of the issue. <tt>open</tt> or <tt>closed</tt>
@@ -190,6 +194,7 @@ module Octokit
       #   @option options [String] :title Updated title for the issue
       #   @option options [String] :body Updated body of the issue
       #   @option options [String] :assignee User login.
+      #   @option options [Array<String>] :assignees User login.
       #   @option options [Integer] :milestone Milestone number.
       # @option options [Array<String>] :labels List of Label names. Example: <tt>['bug', 'ui', '@high']</tt>.
       #   @option options [String] :state State of the issue. <tt>open</tt> or <tt>closed</tt>
@@ -332,7 +337,7 @@ module Octokit
       #
       # @param repo [Integer, String, Repository, Hash] A GitHub repository
       # @param number [Integer] Issue number
-      # @param assignees [Array] Assignees to be added
+      # @param assignees [Array<String>] Assignees to be added
       # @return [Sawyer::Resource] Issue
       # @see https://developer.github.com/v3/issues/assignees/#add-assignees-to-an-issue
       # @example Add assignees "pengwynn" and "joeyw" to Issue #23 on octokit/octokit.rb
@@ -345,7 +350,7 @@ module Octokit
       #
       # @param repo [Integer, String, Repository, Hash] A GitHub repository
       # @param number [Integer] Issue number
-      # @param assignees [Array] Assignees to be removed
+      # @param assignees [Array<String>] Assignees to be removed
       # @param options [Hash] Header params for request
       # @return [Sawyer::Resource] Issue
       # @see https://developer.github.com/v3/issues/assignees/#remove-assignees-from-an-issue

data/lib/octokit/client/oauth_applications.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Octokit
+  class Client
+
+    # Methods for the OauthApplications API
+    #
+    # @see https://developer.github.com/v3/apps/oauth_applications
+    module OauthApplications
+
+      # Check if a token is valid.
+      #
+      # Applications can check if a token is valid without rate limits.
+      #
+      # @param access_token [String] 40 character GitHub OAuth access token
+      #
+      # @return [Sawyer::Resource] A single authorization for the authenticated user
+      # @see https://developer.github.com/v3/apps/oauth_applications/#check-a-token
+      #
+      # @example
+      #  client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
+      #  client.check_token('deadbeef1234567890deadbeef987654321')
+      def check_token(access_token, options = {})
+        options = ensure_api_media_type(:applications_api, options.dup)
+        options[:access_token] = access_token
+
+        key    = options.delete(:client_id)     || client_id
+        secret = options.delete(:client_secret) || client_secret
+
+        as_app(key, secret) do |app_client|
+          app_client.post "applications/#{client_id}/token", options
+        end
+      end
+      alias check_application_authorization check_token
+
+      # Reset a token
+      #
+      # Applications can reset a token without requiring a user to re-authorize.
+      #
+      # @param access_token [String] 40 character GitHub OAuth access token
+      #
+      # @return [Sawyer::Resource] A single authorization for the authenticated user
+      # @see https://developer.github.com/v3/apps/oauth_applications/#reset-a-token
+      #
+      # @example
+      #  client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
+      #  client.reset_token('deadbeef1234567890deadbeef987654321')
+      def reset_token(access_token, options = {})
+        options = ensure_api_media_type(:applications_api, options.dup)
+        options[:access_token] = access_token
+
+        key    = options.delete(:client_id)     || client_id
+        secret = options.delete(:client_secret) || client_secret
+
+        as_app(key, secret) do |app_client|
+          app_client.patch "applications/#{client_id}/token", options
+        end
+      end
+      alias reset_application_authorization reset_token
+
+      # Delete an app token
+      #
+      # Applications can revoke (delete) a token
+      #
+      # @param access_token [String] 40 character GitHub OAuth access token
+      #
+      # @return [Boolean] Result
+      # @see https://developer.github.com/v3/apps/oauth_applications/#delete-an-app-token
+      #
+      # @example
+      #  client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
+      #  client.delete_token('deadbeef1234567890deadbeef987654321')
+      def delete_app_token(access_token, options = {})
+        options = ensure_api_media_type(:applications_api, options.dup)
+        options[:access_token] = access_token
+
+        key    = options.delete(:client_id)     || client_id
+        secret = options.delete(:client_secret) || client_secret
+
+        begin
+          as_app(key, secret) do |app_client|
+            app_client.delete "applications/#{client_id}/token", options
+            app_client.last_response.status == 204
+          end
+        rescue Octokit::NotFound
+          false
+        end
+      end
+      alias delete_application_authorization delete_app_token
+      alias revoke_application_authorization delete_app_token
+
+      # Delete an app authorization
+      #
+      # OAuth application owners can revoke a grant for their OAuth application and a specific user.
+      #
+      # @param access_token [String] 40 character GitHub OAuth access token
+      #
+      # @return [Boolean] Result
+      # @see https://developer.github.com/v3/apps/oauth_applications/#delete-an-app-token
+      #
+      # @example
+      #  client = Octokit::Client.new(:client_id => 'abcdefg12345', :client_secret => 'secret')
+      #  client.delete_app_authorization('deadbeef1234567890deadbeef987654321')
+      def delete_app_authorization(access_token, options = {})
+        options = ensure_api_media_type(:applications_api, options.dup)
+        options[:access_token] = access_token
+
+        key    = options.delete(:client_id)     || client_id
+        secret = options.delete(:client_secret) || client_secret
+
+        begin
+          as_app(key, secret) do |app_client|
+            app_client.delete "applications/#{client_id}/grant", options
+            app_client.last_response.status == 204
+          end
+        rescue Octokit::NotFound
+          false
+        end
+      end
+    end
+  end
+end

data/lib/octokit/client/organizations.rb

@@ -236,7 +236,7 @@ module Octokit
       # @example
       #   @client.outside_collaborators('github')
       def outside_collaborators(org, options={})
-        get "#{Organization.path org}/outside_collaborators", options
+        paginate "#{Organization.path org}/outside_collaborators", options
       end
 
       # Remove outside collaborator from an organization
@@ -324,6 +324,20 @@ module Octokit
         get "teams/#{team_id}", options
       end
 
+      # Get team by name and org
+      #
+      # Requires authenticated organization member.
+      #
+      # @param org [String, Integer] Organization GitHub login or id.
+      # @param team_slug [String] Team slug.
+      # @return [Sawyer::Resource] Hash representing team.
+      # @see https://developer.github.com/v3/teams/#get-team-by-name
+      # @example
+      #   @client.team_by_name("github", "justice-league")
+      def team_by_name(org, team_slug, options = {})
+        get "#{Organization.path(org)}/teams/#{team_slug}", options
+      end
+
       # List child teams
       #
       # Requires authenticated organization member.
@@ -676,7 +690,7 @@ module Octokit
 
       # Edit an organization membership
       #
-      # @param org [String] Organization GitHub login.
+      # @param org [String, Integer] Organization GitHub login or id.
       # @option options [String] :role  The role of the user in the organization.
       # @option options [String] :state The state that the membership should be in.
       # @option options [String] :user  The login of the user, otherwise authenticated user.
@@ -687,7 +701,7 @@ module Octokit
         options = options.dup
         if user = options.delete(:user)
           options.delete(:state)
-          put "orgs/#{org}/memberships/#{user}", options
+          put "#{Organization.path(org)}/memberships/#{user}", options
         else
           options.delete(:role)
           patch "user/memberships/orgs/#{org}", options
@@ -697,13 +711,13 @@ module Octokit
 
       # Remove an organization membership
       #
-      # @param org [String] Organization GitHub login.
+      # @param org [String, Integer] Organization GitHub login or id.
       # @return [Boolean] Success
       # @see https://developer.github.com/v3/orgs/members/#remove-organization-membership
       def remove_organization_membership(org, options = {})
         options = options.dup
         user = options.delete(:user)
-        user && boolean_from_response(:delete, "orgs/#{org}/memberships/#{user}", options)
+        user && boolean_from_response(:delete, "#{Organization.path(org)}/memberships/#{user}", options)
       end
       alias :remove_org_membership :remove_organization_membership
 
@@ -721,7 +735,7 @@ module Octokit
       def start_migration(org, repositories, options = {})
         options = ensure_api_media_type(:migrations, options)
         options[:repositories] = repositories
-        post "orgs/#{org}/migrations", options
+        post "#{Organization.path(org)}/migrations", options
       end
 
       # Lists the most recent migrations.
@@ -733,7 +747,7 @@ module Octokit
       # @see https://developer.github.com/v3/orgs/migrations/#get-a-list-of-migrations
       def migrations(org, options = {})
         options = ensure_api_media_type(:migrations, options)
-        paginate "orgs/#{org}/migrations", options
+        paginate "#{Organization.path(org)}/migrations", options
       end
 
       # Fetches the status of a migration.
@@ -745,7 +759,7 @@ module Octokit
       # @see https://developer.github.com/v3/orgs/migrations/#get-the-status-of-a-migration
       def migration_status(org, id, options = {})
         options = ensure_api_media_type(:migrations, options)
-        get "orgs/#{org}/migrations/#{id}", options
+        get "#{Organization.path(org)}/migrations/#{id}", options
       end
 
       # Fetches the URL to a migration archive.
@@ -757,7 +771,7 @@ module Octokit
       # @see https://developer.github.com/v3/orgs/migrations/#download-a-migration-archive
       def migration_archive_url(org, id, options = {})
         options = ensure_api_media_type(:migrations, options)
-        url = "orgs/#{org}/migrations/#{id}/archive"
+        url = "#{Organization.path(org)}/migrations/#{id}/archive"
 
         response = client_without_redirects(options).get(url)
         response.headers['location']
@@ -772,7 +786,7 @@ module Octokit
       # @see https://developer.github.com/v3/orgs/migrations/#delete-a-migration-archive
       def delete_migration_archive(org, id, options = {})
         options = ensure_api_media_type(:migrations, options)
-        delete "orgs/#{org}/migrations/#{id}/archive", options
+        delete "#{Organization.path(org)}/migrations/#{id}/archive", options
       end
 
       # Unlock a previous migration archive.
@@ -785,7 +799,21 @@ module Octokit
       # @see https://developer.github.com/v3/orgs/migrations/#unlock-a-repository
       def unlock_repository(org, id, repo, options = {})
         options = ensure_api_media_type(:migrations, options)
-        delete "orgs/#{org}/migrations/#{id}/repos/#{repo}/lock", options
+        delete "#{Organization.path(org)}/migrations/#{id}/repos/#{repo}/lock", options
+      end
+
+      # Get GitHub Actions billing for an organization
+      # 
+      # Requires authenticated organization owner.
+      # 
+      # @param org [String, Integer] Organization GitHub login or id.
+      # @return [Sawyer::Resource] Hash representing GitHub Actions billing for an organization.
+      # @see https://docs.github.com/en/rest/reference/billing#get-github-actions-billing-for-an-organization
+      # 
+      # @example
+      #   @client.billing_actions('github')
+      def billing_actions(org)
+        get "#{Organization.path(org)}/settings/billing/actions"
       end
     end
   end

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

@@ -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_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