octokit 4.13.0 → 4.19.0

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

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

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

@@ -10,7 +10,7 @@ module Octokit
       #
       # @see https://developer.github.com/v3/repos/#get
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
-      # @return [Sawyer::Resource] if a repository exists, false otherwise
+      # @return [Boolean]
       def repository?(repo, options = {})
         !!repository(repo, options)
       rescue Octokit::InvalidRepository
@@ -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
@@ -293,7 +317,7 @@ module Octokit
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository.
       # @option options [String] :affiliation Filters the return array by affiliation.
-      #   Can be one of: <tt>outside</tt> or <tt>all</tt>.
+      #   Can be one of: <tt>outside</tt>, <tt>direct</tt>, or <tt>all</tt>.
       #   If not specified, defaults to <tt>all</tt>
       # @return [Array<Sawyer::Resource>] Array of hashes representing collaborating users.
       # @see https://developer.github.com/v3/repos/collaborators/#list-collaborators
@@ -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,19 @@ 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
     end
   end
 end