gitlab 3.0.0 → 4.0.0

data/lib/gitlab/client/system_hooks.rb

@@ -0,0 +1,59 @@
+class Gitlab::Client
+  # Defines methods related to system hooks.
+  # @see https://docs.gitlab.com/ce/api/system_hooks.html
+  module SystemHooks
+    # Gets a list of system hooks.
+    #
+    # @example
+    #   Gitlab.hooks
+    #   Gitlab.system_hooks
+    #
+    # @param  [Hash] options A customizable set of options.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def hooks(options={})
+      get("/hooks", query: options)
+    end
+    alias_method :system_hooks, :hooks
+
+    # Adds a new system hook.
+    #
+    # @example
+    #   Gitlab.add_hook('http://example.com/hook')
+    #   Gitlab.add_system_hook('https://api.example.net/v1/hook')
+    #
+    # @param  [String] url The hook URL.
+    # @return [Gitlab::ObjectifiedHash]
+    def add_hook(url)
+      post("/hooks", body: { url: url })
+    end
+    alias_method :add_system_hook, :add_hook
+
+    # Tests a system hook.
+    #
+    # @example
+    #   Gitlab.hook(3)
+    #   Gitlab.system_hook(12)
+    #
+    # @param  [Integer] id The ID of a system hook.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def hook(id)
+      get("/hooks/#{id}")
+    end
+    alias_method :system_hook, :hook
+
+    # Deletes a new system hook.
+    #
+    # @example
+    #   Gitlab.delete_hook(3)
+    #   Gitlab.delete_system_hook(12)
+    #
+    # @param  [Integer] id The ID of a system hook.
+    # @return [Gitlab::ObjectifiedHash]
+    def delete_hook(id)
+      delete("/hooks/#{id}")
+    end
+    alias_method :delete_system_hook, :delete_hook
+  end
+end

data/lib/gitlab/client/tags.rb

@@ -0,0 +1,96 @@
+class Gitlab::Client
+  # Defines methods related to tags.
+  # @see https://docs.gitlab.com/ce/api/tags.html
+  module Tags
+    # Gets a list of project repository tags.
+    #
+    # @example
+    #   Gitlab.tags(42)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def tags(project, options={})
+      get("/projects/#{url_encode project}/repository/tags", query: options)
+    end
+    alias_method :repo_tags, :tags
+
+    # Creates a new project repository tag.
+    #
+    # @example
+    #   Gitlab.create_tag(42, 'new_tag', 'master')
+    #   Gitlab.create_tag(42, 'v1.0', 'master', 'Release 1.0')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String]  tag_name The name of the new tag.
+    # @param  [String]  ref The ref (commit sha, branch name, or another tag) the tag will point to.
+    # @param  [String]  message Optional message for tag, creates annotated tag if specified.
+    # @param  [String]  description Optional release notes for tag.
+    # @return [Gitlab::ObjectifiedHash]
+    def create_tag(project, tag_name, ref, message='', description=nil)
+      post("/projects/#{url_encode project}/repository/tags", body: { tag_name: tag_name, ref: ref, message: message, description: description })
+    end
+    alias_method :repo_create_tag, :create_tag
+
+    # Gets information about a repository tag.
+    #
+    # @example
+    #   Gitlab.tag(3, 'api')
+    #   Gitlab.repo_tag(5, 'master')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] tag The name of the tag.
+    # @return [Gitlab::ObjectifiedHash]
+    def tag(project, tag)
+      get("/projects/#{url_encode project}/repository/tags/#{tag}")
+    end
+    alias_method :repo_tag, :tag
+
+    # Deletes a repository tag.  Requires Gitlab >= 6.8.x
+    #
+    # @example
+    #   Gitlab.delete_tag(3, 'api')
+    #   Gitlab.repo_delete_tag(5, 'master')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] tag The name of the tag to delete
+    # @return [Gitlab::ObjectifiedHash]
+    def delete_tag(project, tag)
+      delete("/projects/#{url_encode project}/repository/tags/#{tag}")
+    end
+    alias_method :repo_delete_tag, :delete_tag
+
+    # Adds release notes to an existing repository tag.  Requires Gitlab >= 8.2.0
+    #
+    # @example
+    #   Gitlab.create_release(3, '1.0.0', 'This is ready for production')
+    #   Gitlab.repo_create_release(5, '1.0.0', 'This is ready for production')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] tag The name of the new tag.
+    # @param  [String] description Release notes with markdown support
+    # @return [Gitlab::ObjectifiedHash]
+    def create_release(project, tag, description)
+      post("/projects/#{url_encode project}/repository/tags/#{tag}/release", body: { description: description })
+    end
+    alias_method :repo_create_release, :create_release
+
+    # Updates the release notes of a given release.  Requires Gitlab >= 8.2.0
+    #
+    # @example
+    #   Gitlab.update_release(3, '1.0.0', 'This is even more ready for production')
+    #   Gitlab.repo_update_release(5, '1.0.0', 'This is even more ready for production')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] tag The name of the new tag.
+    # @param  [String] description Release notes with markdown support
+    # @return [Gitlab::ObjectifiedHash]
+    def update_release(project, tag, description)
+      put("/projects/#{url_encode project}/repository/tags/#{tag}/release", body: { description: description })
+    end
+    alias_method :repo_update_release, :update_release
+
+  end
+end

data/lib/gitlab/client/users.rb

@@ -1,5 +1,7 @@
 class Gitlab::Client
   # Defines methods related to users.
+  # @see https://docs.gitlab.com/ce/api/users.html
+  # @see https://docs.gitlab.com/ce/api/session.html
   module Users
     # Gets a list of users.
     #
@@ -11,7 +13,7 @@ class Gitlab::Client
     # @option options [Integer] :per_page The number of results per page.
     # @return [Array<Gitlab::ObjectifiedHash>]
     def users(options={})
-      get("/users", :query => options)
+      get("/users", query: options)
     end
 
     # Gets information about a user.
@@ -30,18 +32,82 @@ class Gitlab::Client
     # Creates a new user.
     # Requires authentication from an admin account.
     #
+    # @example
+    #   Gitlab.create_user('joe@foo.org', 'secret', 'joe', { name: 'Joe Smith' })
+    #   or
+    #   Gitlab.create_user('joe@foo.org', 'secret')
+    #
     # @param  [String] email The email of a user.
     # @param  [String] password The password of a user.
+    # @param  [String] username The username of a user.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :name The name of a user. Defaults to email.
+    # @option options [String] :skype The skype of a user.
+    # @option options [String] :linkedin The linkedin of a user.
+    # @option options [String] :twitter The twitter of a user.
+    # @option options [Integer] :projects_limit The limit of projects for a user.
+    # @return [Gitlab::ObjectifiedHash] Information about created user.
+    def create_user(*args)
+      options = Hash === args.last ? args.pop : {}
+      if args[2]
+        body = { email: args[0], password: args[1], username: args[2] }
+      else
+        body = { email: args[0], password: args[1], name: args[0] }
+      end
+      body.merge!(options)
+      post('/users', body: body)
+    end
+
+    # Updates a user.
+    #
+    # @example
+    #   Gitlab.edit_user(15, { email: 'joe.smith@foo.org', projects_limit: 20 })
+    #
+    # @param  [Integer] id The ID of a user.
     # @param  [Hash] options A customizable set of options.
+    # @option options [String] :email The email of a user.
+    # @option options [String] :password The password of a user.
     # @option options [String] :name The name of a user. Defaults to email.
     # @option options [String] :skype The skype of a user.
     # @option options [String] :linkedin The linkedin of a user.
     # @option options [String] :twitter The twitter of a user.
     # @option options [Integer] :projects_limit The limit of projects for a user.
     # @return [Gitlab::ObjectifiedHash] Information about created user.
-    def create_user(email, password, options={})
-      body = {:email => email, :password => password, :name => email}.merge(options)
-      post("/users", :body => body)
+    def edit_user(user_id, options={})
+      put("/users/#{user_id}", body: options)
+    end
+
+    # Deletes a user.
+    #
+    # @example
+    #   Gitlab.delete_user(1)
+    #
+    # @param [Integer] id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash] Information about deleted user.
+    def delete_user(user_id)
+      delete("/users/#{user_id}")
+    end
+
+    # Blocks the specified user. Available only for admin.
+    #
+    # @example
+    #   Gitlab.block_user(15)
+    #
+    # @param [Integer] user_id The Id of user
+    # @return [Boolean] success or not
+    def block_user(user_id)
+      post("/users/#{user_id}/block")
+    end
+
+    # Unblocks the specified user. Available only for admin.
+    #
+    # @example
+    #   Gitlab.unblock_user(15)
+    #
+    # @param [Integer] user_id The Id of user
+    # @return [Boolean] success or not
+    def unblock_user(user_id)
+      post("/users/#{user_id}/unblock")
     end
 
     # Creates a new user session.
@@ -52,21 +118,29 @@ class Gitlab::Client
     # @param  [String] email The email of a user.
     # @param  [String] password The password of a user.
     # @return [Gitlab::ObjectifiedHash]
+    # @note This method doesn't require private_token to be set.
     def session(email, password)
-      post("/session", :body => {:email => email, :password => password})
+      post("/session", body: { email: email, password: password })
     end
 
     # Gets a list of user's SSH keys.
     #
     # @example
     #   Gitlab.ssh_keys
+    #   Gitlab.ssh_keys({ user_id: 2 })
     #
     # @param  [Hash] options A customizable set of options.
     # @option options [Integer] :page The page number.
     # @option options [Integer] :per_page The number of results per page.
+    # @option options [Integer] :user_id The ID of the user to retrieve the keys for.
     # @return [Array<Gitlab::ObjectifiedHash>]
     def ssh_keys(options={})
-      get("/user/keys", :query => options)
+      user_id = options.delete :user_id
+      if user_id.to_i.zero?
+        get("/user/keys", query: options)
+      else
+        get("/users/#{user_id}/keys", query: options)
+      end
     end
 
     # Gets information about SSH key.
@@ -89,7 +163,7 @@ class Gitlab::Client
     # @param  [String] key The SSH key body.
     # @return [Gitlab::ObjectifiedHash] Information about created SSH key.
     def create_ssh_key(title, key)
-      post("/user/keys", :body => {:title => title, :key => key})
+      post("/user/keys", body: { title: title, key: key })
     end
 
     # Deletes an SSH key.
@@ -102,5 +176,75 @@ class Gitlab::Client
     def delete_ssh_key(id)
       delete("/user/keys/#{id}")
     end
+
+    # Gets user emails.
+    # Will return emails an authorized user if no user ID passed.
+    #
+    # @example
+    #   Gitlab.emails
+    #   Gitlab.emails(2)
+    #
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def emails(user_id=nil)
+      url = user_id.to_i.zero? ? "/user/emails" : "/users/#{user_id}/emails"
+      get(url)
+    end
+
+    # Get a single email.
+    #
+    # @example
+    #   Gitlab.email(3)
+    #
+    # @param  [Integer] id The ID of a email.
+    # @return [Gitlab::ObjectifiedHash]
+    def email(id)
+      get("/user/emails/#{id}")
+    end
+
+    # Creates a new email
+    # Will create a new email an authorized user if no user ID passed.
+    #
+    # @example
+    #   Gitlab.add_email('email@example.com')
+    #   Gitlab.add_email('email@example.com', 2)
+    #
+    # @param  [String] email Email address
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def add_email(email, user_id=nil)
+      url = user_id.to_i.zero? ? "/user/emails" : "/users/#{user_id}/emails"
+      post(url, body: {email: email})
+    end
+
+    # Delete email
+    # Will delete a email an authorized user if no user ID passed.
+    #
+    # @example
+    #   Gitlab.delete_email(2)
+    #   Gitlab.delete_email(3, 2)
+    #
+    # @param  [Integer] id Email address ID
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Boolean]
+    def delete_email(id, user_id=nil)
+      url = user_id.to_i.zero? ? "/user/emails/#{id}" : "/users/#{user_id}/emails/#{id}"
+      delete(url)
+    end
+
+    # Search for groups by name
+    #
+    # @example
+    #   Gitlab.user_search('gitlab')
+    #
+    # @param  [String] search A string to search for in user names and paths.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :per_page Number of user to return per page
+    # @option options [String] :page The page to retrieve
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def user_search(search, options={})
+      options[:search] = search
+      get("/users", query: options)
+    end
   end
 end

data/lib/gitlab/configuration.rb

@@ -1,14 +1,17 @@
+require 'gitlab/cli_helpers'
 module Gitlab
   # Defines constants and methods related to configuration.
   module Configuration
     # An array of valid keys in the options hash when configuring a Gitlab::API.
-    VALID_OPTIONS_KEYS = [:endpoint, :private_token, :user_agent, :sudo].freeze
+    VALID_OPTIONS_KEYS = [:endpoint, :private_token, :user_agent, :sudo, :httparty].freeze
 
     # The user agent that will be sent to the API endpoint if none is set.
     DEFAULT_USER_AGENT = "Gitlab Ruby Gem #{Gitlab::VERSION}".freeze
 
     # @private
-    attr_accessor *VALID_OPTIONS_KEYS
+    attr_accessor(*VALID_OPTIONS_KEYS)
+    # @private
+    alias_method :auth_token=, :private_token=
 
     # Sets all configuration options to their default values
     # when this module is extended.
@@ -30,10 +33,23 @@ module Gitlab
 
     # Resets all configuration options to the defaults.
     def reset
-      self.endpoint       = nil
-      self.private_token  = nil
+      self.endpoint       = ENV['GITLAB_API_ENDPOINT']
+      self.private_token  = ENV['GITLAB_API_PRIVATE_TOKEN'] || ENV['GITLAB_API_AUTH_TOKEN']
+      self.httparty       = get_httparty_config(ENV['GITLAB_API_HTTPARTY_OPTIONS'])
       self.sudo           = nil
       self.user_agent     = DEFAULT_USER_AGENT
     end
+
+    private
+
+    # Allows HTTParty config to be specified in ENV using YAML hash.
+    def get_httparty_config(options)
+      return options if options.nil?
+
+      httparty = Gitlab::CLI::Helpers.yaml_load(options)
+
+      raise ArgumentError, "HTTParty config should be a Hash." unless httparty.is_a? Hash
+      Gitlab::CLI::Helpers.symbolize_keys httparty
+    end
   end
 end

data/lib/gitlab/error.rb

@@ -3,40 +3,83 @@ module Gitlab
     # Custom error class for rescuing from all Gitlab errors.
     class Error < StandardError; end
 
-    # Raise when attributes are missing.
-    class MissingAttributes < Error; end
-
     # Raised when API endpoint credentials not configured.
     class MissingCredentials < Error; end
 
     # Raised when impossible to parse response body.
     class Parsing < Error; end
 
+    # Custom error class for rescuing from HTTP response errors.
+    class ResponseError < Error
+      def initialize(response)
+        @response = response
+        super(build_error_message)
+      end
+
+      # Status code returned in the http response.
+      #
+      # @return [Integer]
+      def response_status
+        @response.code
+      end
+
+      private
+
+      # Human friendly message.
+      #
+      # @return [String]
+      def build_error_message
+        parsed_response = @response.parsed_response
+        message = parsed_response.message || parsed_response.error
+
+        "Server responded with code #{@response.code}, message: " \
+        "#{handle_message(message)}. " \
+        "Request URI: #{@response.request.base_uri}#{@response.request.path}"
+      end
+
+      # Handle error response message in case of nested hashes
+      def handle_message(message)
+        case message
+        when Gitlab::ObjectifiedHash
+          message.to_h.sort.map do |key, val|
+            "'#{key}' #{(val.is_a?(Hash) ? val.sort.map { |k, v| "(#{k}: #{v.join(' ')})" } : val).join(' ')}"
+          end.join(', ')
+        when Array
+          message.join(' ')
+        else
+          message
+        end
+      end
+    end
+
     # Raised when API endpoint returns the HTTP status code 400.
-    class BadRequest < Error; end
+    class BadRequest < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 401.
-    class Unauthorized < Error; end
+    class Unauthorized < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 403.
-    class Forbidden < Error; end
+    class Forbidden < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 404.
-    class NotFound < Error; end
+    class NotFound < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 405.
-    class MethodNotAllowed < Error; end
+    class MethodNotAllowed < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 409.
-    class Conflict < Error; end
+    class Conflict < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 422.
+    class Unprocessable < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 500.
-    class InternalServerError < Error; end
+    class InternalServerError < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 502.
-    class BadGateway < Error; end
+    class BadGateway < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 503.
-    class ServiceUnavailable < Error; end
+    class ServiceUnavailable < ResponseError; end
   end
 end