octokit 4.6.0 → 4.21.0

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

@@ -31,6 +31,8 @@ module Octokit
       # @option values [String] :email Publicly visible email address.
       # @option values [String] :location Location of organization.
       # @option values [String] :name GitHub username for organization.
+      # @option values [String] :default_repository_permission The default permission members have on organization repositories.
+      # @option values [Boolean] :members_can_create_repositories Set true to allow members to create repositories on the organization.
       # @return [Sawyer::Resource] Hash representing GitHub organization.
       # @see https://developer.github.com/v3/orgs/#edit-an-organization
       # @example
@@ -96,7 +98,7 @@ module Octokit
       #
       # @return [Array<Sawyer::Resource>] List of GitHub organizations.
       def all_organizations(options = {})
-        paginate "organizations"
+        paginate "organizations", options
       end
       alias :all_orgs :all_organizations
 
@@ -140,6 +142,7 @@ module Octokit
       # @example
       #   Octokit.org_members('github')
       def organization_members(org, options = {})
+        options = options.dup
         path = "public_" if options.delete(:public)
         paginate "#{Organization.path org}/#{path}members", options
       end
@@ -207,6 +210,65 @@ module Octokit
       end
       alias :org_public_member? :organization_public_member?
 
+      # List pending organization invitations
+      #
+      # Requires authenticated organization member.
+      #
+      # @param org [String, Integer] Organization GitHub login or id.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing invitations.
+      # @see https://developer.github.com/v3/orgs/members/#list-pending-organization-invitations
+      #
+      # @example
+      #   @client.organization_invitations('github')
+      def organization_invitations(org, options = {})
+        get "#{Organization.path org}/invitations", options
+      end
+      alias :org_invitations :organization_invitations
+
+      # List outside collaborators for an organization
+      #
+      # Requires authenticated organization members.
+      #
+      # @param org [String, Integer] Organization GitHub login or id.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing users.
+      # @see https://developer.github.com/v3/orgs/outside_collaborators/#list-outside-collaborators
+      #
+      # @example
+      #   @client.outside_collaborators('github')
+      def outside_collaborators(org, options={})
+        paginate "#{Organization.path org}/outside_collaborators", options
+      end
+
+      # Remove outside collaborator from an organization
+      #
+      # Requires authenticated organization members.
+      #
+      # @param org [String, Integer] Organization GitHub login or id.
+      # @param user [String] GitHub username to be removed as outside collaborator
+      # @return [Boolean] Return true if outside collaborator removed from organization, false otherwise.
+      # @see https://developer.github.com/v3/orgs/outside-collaborators/#remove-outside-collaborator
+      #
+      # @example
+      #   @client.remove_outside_collaborator('github', 'lizzhale')
+      def remove_outside_collaborator(org, user, options={})
+        boolean_from_response :delete, "#{Organization.path org}/outside_collaborators/#{user}", options
+      end
+
+      # Converts an organization member to an outside collaborator
+      #
+      # Requires authenticated organization members.
+      #
+      # @param org [String, Integer] Organization GitHub login or id.
+      # @param user [String] GitHub username to be removed as outside collaborator
+      # @return [Boolean] Return true if outside collaborator removed from organization, false otherwise.
+      # @see https://developer.github.com/v3/orgs/outside-collaborators/#convert-member-to-outside-collaborator
+      #
+      # @example
+      #   @client.convert_to_outside_collaborator('github', 'lizzhale')
+      def convert_to_outside_collaborator(org, user, options={})
+        boolean_from_response :put, "#{Organization.path org}/outside_collaborators/#{user}", options
+      end
+
       # List teams
       #
       # Requires authenticated organization member.
@@ -230,6 +292,8 @@ module Octokit
       # @param org [String, Integer] Organization GitHub login or id.
       # @option options [String] :name Team name.
       # @option options [Array<String>] :repo_names Repositories for the team.
+      # @option options [Array<String>] :maintainers Maintainers for the team.
+      # @option options [Integer] :parent_team_id ID of a team to set as the parent team.
       # @return [Sawyer::Resource] Hash representing new team.
       # @see https://developer.github.com/v3/orgs/teams/#create-team
       # @example
@@ -241,6 +305,9 @@ module Octokit
         if options.key?(:permission)
           octokit_warn "Deprecated: Passing :permission option to #create_team. Assign team repository permission by passing :permission to #add_team_repository instead."
         end
+        if options.key?(:parent_team_id)
+          options = ensure_api_media_type(:nested_teams, options)
+        end
         post "#{Organization.path org}/teams", options
       end
 
@@ -257,6 +324,34 @@ 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.
+      #
+      # @param team_id [Integer] Team id.
+      # @return [Sawyer::Resource] Hash representing team.
+      # @see https://developer.github.com/v3/orgs/teams/#list-child-teams
+      # @example
+      #   @client.child_teams(100000, :accept => "application/vnd.github.hellcat-preview+json")
+      def child_teams(team_id, options = {})
+        options = ensure_api_media_type(:nested_teams, options)
+        paginate "teams/#{team_id}/teams", options
+      end
+
       # Update team
       #
       # Requires authenticated organization owner.
@@ -268,6 +363,7 @@ module Octokit
       #   `pull` - team members can pull, but not push to or administer these repositories.
       #   `push` - team members can pull and push, but not administer these repositories.
       #   `admin` - team members can pull, push and administer these repositories.
+      # @option options [Integer] :parent_team_id ID of a team to set as the parent team.
       # @return [Sawyer::Resource] Hash representing updated team.
       # @see https://developer.github.com/v3/orgs/teams/#edit-team
       # @example
@@ -276,6 +372,9 @@ module Octokit
       #     :permission => 'push'
       #   })
       def update_team(team_id, options = {})
+        if options.key?(:parent_team_id)
+          options = ensure_api_media_type(:nested_teams, options)
+        end
         patch "teams/#{team_id}", options
       end
 
@@ -361,12 +460,26 @@ module Octokit
       # @see https://developer.github.com/v3/orgs/teams/#get-team-member
       #
       # @example Check if a user is in your team
-      #   @client.team_member?('your_team', 'pengwynn')
+      #   @client.team_member?(100000, 'pengwynn')
       #   => false
       def team_member?(team_id, user, options = {})
         boolean_from_response :get, "teams/#{team_id}/members/#{user}", options
       end
 
+      # List pending team invitations
+      #
+      # Requires authenticated organization member.
+      #
+      # @param team_id [Integer] Team id.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing invitations.
+      # @see https://developer.github.com/v3/orgs/teams/#list-pending-team-invitations
+      #
+      # @example
+      #   @client.team_invitations('github')
+      def team_invitations(team_id, options = {})
+        get "teams/#{team_id}/invitations", options
+      end
+
       # List team repositories
       #
       # Requires authenticated organization member.
@@ -425,7 +538,7 @@ module Octokit
       # @example Add a team with admin permissions
       #   @client.add_team_repository(100000, 'github/developer.github.com', permission: 'admin')
       def add_team_repository(team_id, repo, options = {})
-        boolean_from_response :put, "teams/#{team_id}/repos/#{Repository.new(repo)}", options.merge(:name => Repository.new(repo))
+        boolean_from_response :put, "teams/#{team_id}/repos/#{Repository.new(repo)}", options
       end
       alias :add_team_repo :add_team_repository
 
@@ -529,7 +642,7 @@ module Octokit
       #
       # @return [Sawyer::Resource] Hash of team membership info
       #
-      # @see https://developer.github.com/v3/orgs/teams/#add-team-membership
+      # @see https://developer.github.com/v3/orgs/teams/#add-or-update-team-membership
       #
       # @example Check if a user has a membership for a team
       #   @client.add_team_membership(1234, 'pengwynn')
@@ -560,14 +673,15 @@ module Octokit
 
       # Get an organization membership
       #
-      # @param org [String] Organization GitHub login.
+      # @param org [Integer, String] The GitHub Organization.
       # @option options [String] :user  The login of the user, otherwise authenticated user.
       # @return [Sawyer::Resource] Hash representing the organization membership.
       # @see https://developer.github.com/v3/orgs/members/#get-your-organization-membership
       # @see https://developer.github.com/v3/orgs/members/#get-organization-membership
       def organization_membership(org, options = {})
+        options = options.dup
         if user = options.delete(:user)
-          get "orgs/#{org}/memberships/#{user}", options
+          get "#{Organization.path(org)}/memberships/#{user}", options
         else
           get "user/memberships/orgs/#{org}", options
         end
@@ -576,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.
@@ -584,9 +698,12 @@ module Octokit
       # @see https://developer.github.com/v3/orgs/members/#edit-your-organization-membership
       # @see https://developer.github.com/v3/orgs/members/#add-or-update-organization-membership
       def update_organization_membership(org, options = {})
+        options = options.dup
         if user = options.delete(:user)
-          put "orgs/#{org}/memberships/#{user}", options
+          options.delete(:state)
+          put "#{Organization.path(org)}/memberships/#{user}", options
         else
+          options.delete(:role)
           patch "user/memberships/orgs/#{org}", options
         end
       end
@@ -594,13 +711,15 @@ 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
 
       # Initiates the generation of a migration archive.
       #
@@ -616,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.
@@ -628,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.
@@ -640,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.
@@ -652,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']
@@ -667,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.
@@ -680,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/projects.rb

@@ -51,7 +51,7 @@ module Octokit
       #   @client.org_projects("octokit")
       def org_projects(org, options = {})
         opts = ensure_api_media_type(:projects, options)
-        get "orgs/#{org}/projects", opts
+        paginate "orgs/#{org}/projects", opts
       end
       alias :organization_projects :org_projects
 
@@ -81,7 +81,7 @@ module Octokit
       # @return [Sawyer::Resource] Project
       # @see https://developer.github.com/v3/projects/#get-a-project 
       # @example
-      #   Octokit.project("octokit/octokit.rb", 1)
+      #   Octokit.project(123942)
       def project(id, options = {})
         opts = ensure_api_media_type(:projects, options)
         get "projects/#{id}", opts
@@ -123,7 +123,7 @@ module Octokit
       # @return [Array<Sawyer::Resource>] List of project columns
       # @see https://developer.github.com/v3/projects/columns/#list-project-columns 
       # @example
-      #   @client.project_columns("octokit/octokit.rb", 1)
+      #   @client.project_columns(123942)
       def project_columns(id, options = {})
         opts = ensure_api_media_type(:projects, options)
         paginate "projects/#{id}/columns", opts
@@ -138,7 +138,7 @@ module Octokit
       # @return [Sawyer::Resource] Newly created column
       # @see https://developer.github.com/v3/projects/columns/#create-a-project-column 
       # @example
-      #   @client.create_project_column("octokit/octokit.rb", 1, "To Dones")
+      #   @client.create_project_column(123942, "To Dones")
       def create_project_column(id, name, options = {})
         opts = ensure_api_media_type(:projects, options)
         opts[:name] = name
@@ -151,7 +151,7 @@ module Octokit
       # @return [Sawyer::Resource] Project column
       # @see https://developer.github.com/v3/projects/columns/#get-a-project-column 
       # @example
-      #   Octokit.project_column(123940, 30)
+      #   Octokit.project_column(30294)
       def project_column(id, options = {})
         opts = ensure_api_media_type(:projects, options)
         get "projects/columns/#{id}", opts
@@ -198,7 +198,7 @@ module Octokit
       # @return [Sawyer::Resource] Result
       # @see https://developer.github.com/v3/projects/columns/#move-a-project-column
       # @example
-      #   @client.move_project_column(3049, "last")
+      #   @client.move_project_column(30294, "last")
       def move_project_column(id, position, options = {})
         opts = ensure_api_media_type(:projects, options)
         opts[:position] = position
@@ -213,7 +213,7 @@ module Octokit
       # @return [Array<Sawyer::Resource>] Cards in the column
       # @see https://developer.github.com/v3/projects/cards/#list-project-cards
       # @example
-      #   @client.column_cards(123847)
+      #   @client.column_cards(30294)
       def column_cards(id, options = {})
         opts = ensure_api_media_type(:projects, options)
         paginate "projects/columns/#{id}/cards", opts

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
@@ -27,6 +27,8 @@ module Octokit
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
       # @param number [Integer] Number of the pull request to fetch
       # @return [Sawyer::Resource] Pull request info
+      # @example
+      #   Octokit.pull_request('rails/rails', 42, :state => 'closed')      
       def pull_request(repo, number, options = {})
         get "#{Repository.path repo}/pulls/#{number}", options
       end
@@ -78,14 +80,14 @@ module Octokit
       end
 
       # Update a pull request
-      # @overload update_pull_request(repo, id, title=nil, body=nil, state=nil, options = {})
+      # @overload update_pull_request(repo, number, title=nil, body=nil, state=nil, options = {})
       #   @deprecated
       #   @param repo [Integer, String, Hash, Repository] A GitHub repository.
       #   @param number [Integer] Number of pull request to update.
       #   @param title [String] Title for the pull request.
       #   @param body [String] Body content for pull request. Supports GFM.
       #   @param state [String] State of the pull request. `open` or `closed`.
-      # @overload update_pull_request(repo, id,  options = {})
+      # @overload update_pull_request(repo, number,  options = {})
       #   @param repo [Integer, String, Hash, Repository] A GitHub repository.
       #   @param number [Integer] Number of pull request to update.
       #   @option options [String] :title Title for the pull request.
@@ -151,8 +153,8 @@ module Octokit
       #
       # @example Get review comments, sort by updated asc since a time
       #   @client.pull_requests_comments("octokit/octokit.rb", {
-      #     :sort => 'asc',
-      #     :direction => 'down',
+      #     :sort => 'updated',
+      #     :direction => 'asc',
       #     :since => '2010-05-04T23:45:02Z'
       #   })
       def pull_requests_comments(repo, options = {})

data/lib/octokit/client/rate_limit.rb

@@ -21,7 +21,7 @@ module Octokit
       # Get number of rate limted requests remaining
       #
       # @see https://developer.github.com/v3/rate_limit/#rate-limit
-      # @return [Fixnum] Number of requests remaining in this period
+      # @return [Integer] Number of requests remaining in this period
       def rate_limit_remaining(options = {})
         octokit_warn "Deprecated: Please use .rate_limit.remaining"
         rate_limit.remaining
@@ -41,7 +41,7 @@ module Octokit
       # Refresh rate limit info and get number of rate limted requests remaining
       #
       # @see https://developer.github.com/v3/rate_limit/#rate-limit
-      # @return [Fixnum] Number of requests remaining in this period
+      # @return [Integer] Number of requests remaining in this period
       def rate_limit_remaining!(options = {})
         octokit_warn "Deprecated: Please use .rate_limit!.remaining"
         rate_limit!.remaining

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

data/lib/octokit/client/releases.rb

@@ -44,6 +44,7 @@ module Octokit
       # Update a release
       #
       # @param url [String] URL for the release as returned from .releases
+      # @option options [String] :tag_name Git tag from which to create release
       # @option options [String] :target_commitish Specifies the commitish value that determines where the Git tag is created from.
       # @option options [String] :name Name for the release
       # @option options [String] :body Content for release notes