gitlab 4.5.0 → 5.1.0

data/lib/gitlab/client/users.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Gitlab::Client
   # Defines methods related to users.
   # @see https://docs.gitlab.com/ce/api/users.html
@@ -12,8 +14,8 @@ class Gitlab::Client
     # @option options [Integer] :page The page number.
     # @option options [Integer] :per_page The number of results per page.
     # @return [Array<Gitlab::ObjectifiedHash>]
-    def users(options={})
-      get("/users", query: options)
+    def users(options = {})
+      get('/users', query: options)
     end
 
     # Gets information about a user.
@@ -25,8 +27,8 @@ class Gitlab::Client
     #
     # @param  [Integer] id The ID of a user.
     # @return [Gitlab::ObjectifiedHash]
-    def user(id=nil)
-      id.to_i.zero? ? get("/user") : get("/users/#{id}")
+    def user(id = nil)
+      id.to_i.zero? ? get('/user') : get("/users/#{id}")
     end
 
     # Creates a new user.
@@ -35,11 +37,11 @@ class Gitlab::Client
     # @example
     #   Gitlab.create_user('joe@foo.org', 'secret', 'joe', { name: 'Joe Smith' })
     #   or
-    #   Gitlab.create_user('joe@foo.org', 'secret')
+    #   Gitlab.create_user('joe@foo.org', 'secret', 'joe')
     #
-    # @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  [String] email(required) The email of a user.
+    # @param  [String] password(required) The password of a user.
+    # @param  [String] username(required) 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.
@@ -48,16 +50,30 @@ class Gitlab::Client
     # @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 : {}
-      body = if args[2]
-               { email: args[0], password: args[1], username: args[2] }
-             else
-               { email: args[0], password: args[1], name: args[0] }
-             end
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      raise ArgumentError, 'Missing required parameters' unless args[2]
+
+      body = { email: args[0], password: args[1], username: args[2], name: args[0] }
       body.merge!(options)
       post('/users', body: body)
     end
 
+    # Creates a service account.
+    # Requires authentication from an admin account.
+    #
+    # @example
+    #   Gitlab.create_service_account('service_account_6018816a18e515214e0c34c2b33523fc', 'Service account user')
+    #
+    # @param  [String] name (required) The email of the service account.
+    # @param  [String] username (required) The username of the service account.
+    # @return [Gitlab::ObjectifiedHash] Information about created service account.
+    def create_service_account(*args)
+      raise ArgumentError, 'Missing required parameters' unless args[1]
+
+      body = { name: args[0], username: args[1] }
+      post('/service_accounts', body: body)
+    end
+
     # Updates a user.
     #
     # @example
@@ -73,7 +89,7 @@ class Gitlab::Client
     # @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 edit_user(user_id, options={})
+    def edit_user(user_id, options = {})
       put("/users/#{user_id}", body: options)
     end
 
@@ -110,6 +126,39 @@ class Gitlab::Client
       post("/users/#{user_id}/unblock")
     end
 
+    # Deactivates the specified user. Available only for admin.
+    #
+    # @example
+    #   Gitlab.deactivate_user(15)
+    #
+    # @param [Integer] user_id The Id of user
+    # @return [Boolean] success or not
+    def deactivate_user(user_id)
+      post("/users/#{user_id}/deactivate")
+    end
+
+    # Activate the specified user. Available only for admin.
+    #
+    # @example
+    #   Gitlab.activate_user(15)
+    #
+    # @param [Integer] user_id The Id of user
+    # @return [Boolean] success or not
+    def activate_user(user_id)
+      post("/users/#{user_id}/activate")
+    end
+
+    # Approves the specified user. Available only for admin.
+    #
+    # @example
+    #   Gitlab.approve_user(15)
+    #
+    # @param [Integer] user_id The Id of user
+    # @return [Boolean] success or not
+    def approve_user(user_id)
+      post("/users/#{user_id}/approve")
+    end
+
     # Creates a new user session.
     #
     # @example
@@ -120,7 +169,21 @@ class Gitlab::Client
     # @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 }, unauthenticated: true)
+      post('/session', body: { email: email, password: password }, unauthenticated: true)
+    end
+
+    # Gets a list of user activities (for admin access only).
+    #
+    # @example
+    #   Gitlab.activities
+    #
+    # @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 [String] :from The start date for paginated results.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def activities(options = {})
+      get('/user/activities', query: options)
     end
 
     # Gets a list of user's SSH keys.
@@ -134,10 +197,10 @@ class Gitlab::Client
     # @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={})
+    def ssh_keys(options = {})
       user_id = options.delete :user_id
       if user_id.to_i.zero?
-        get("/user/keys", query: options)
+        get('/user/keys', query: options)
       else
         get("/users/#{user_id}/keys", query: options)
       end
@@ -161,9 +224,16 @@ class Gitlab::Client
     #
     # @param  [String] title The title of an SSH key.
     # @param  [String] key The SSH key body.
+    # @param  [Hash] options A customizable set of options.
+    # @option options  [Integer] :user_id id of the user to associate the key with
     # @return [Gitlab::ObjectifiedHash] Information about created SSH key.
-    def create_ssh_key(title, key)
-      post("/user/keys", body: { title: title, key: key })
+    def create_ssh_key(title, key, options = {})
+      user_id = options.delete :user_id
+      if user_id.to_i.zero?
+        post('/user/keys', body: { title: title, key: key })
+      else
+        post("/users/#{user_id}/keys", body: { title: title, key: key })
+      end
     end
 
     # Deletes an SSH key.
@@ -172,9 +242,16 @@ class Gitlab::Client
     #   Gitlab.delete_ssh_key(1)
     #
     # @param  [Integer] id The ID of a user's SSH key.
+    # @param  [Hash] options A customizable set of options.
+    # @option options  [Integer] :user_id id of the user to associate the key with
     # @return [Gitlab::ObjectifiedHash] Information about deleted SSH key.
-    def delete_ssh_key(id)
-      delete("/user/keys/#{id}")
+    def delete_ssh_key(id, options = {})
+      user_id = options.delete :user_id
+      if user_id.to_i.zero?
+        delete("/user/keys/#{id}")
+      else
+        delete("/users/#{user_id}/keys/#{id}")
+      end
     end
 
     # Gets user emails.
@@ -186,8 +263,8 @@ class Gitlab::Client
     #
     # @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"
+    def emails(user_id = nil)
+      url = user_id.to_i.zero? ? '/user/emails' : "/users/#{user_id}/emails"
       get(url)
     end
 
@@ -211,10 +288,15 @@ class Gitlab::Client
     #
     # @param  [String] email Email address
     # @param  [Integer] user_id The ID of a user.
+    # @param  [Boolean] skip_confirmation     Skip confirmation and assume e-mail is verified
     # @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})
+    def add_email(email, user_id = nil, skip_confirmation = nil)
+      url = user_id.to_i.zero? ? '/user/emails' : "/users/#{user_id}/emails"
+      if skip_confirmation.nil?
+        post(url, body: { email: email })
+      else
+        post(url, body: { email: email, skip_confirmation: skip_confirmation })
+      end
     end
 
     # Delete email
@@ -227,12 +309,12 @@ class Gitlab::Client
     # @param  [Integer] id Email address ID
     # @param  [Integer] user_id The ID of a user.
     # @return [Boolean]
-    def delete_email(id, user_id=nil)
+    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
+    # Search for users by name
     #
     # @example
     #   Gitlab.user_search('gitlab')
@@ -242,9 +324,198 @@ class Gitlab::Client
     # @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={})
+    def user_search(search, options = {})
       options[:search] = search
-      get("/users", query: options)
+      get('/users', query: options)
+    end
+
+    # Get user by username
+    #
+    # @example
+    #   Gitlab.user_by_username('gitlab')
+    #
+    # @param  [String] username A username to get.
+    # @param  [Hash] options A customizable set of options.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def user_by_username(username, options = {})
+      options[:username] = username
+      get('/users', query: options)
+    end
+
+    # Gets user custom_attributes.
+    #
+    # @example
+    #   Gitlab.user_custom_attributes(2)
+    #
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def user_custom_attributes(user_id)
+      get("/users/#{user_id}/custom_attributes")
+    end
+
+    # Gets single user custom_attribute.
+    #
+    # @example
+    #   Gitlab.user_custom_attribute(key, 2)
+    #
+    # @param  [String] key The custom_attributes key
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def user_custom_attribute(key, user_id)
+      get("/users/#{user_id}/custom_attributes/#{key}")
+    end
+
+    # Creates a new custom_attribute
+    #
+    # @example
+    #   Gitlab.add_custom_attribute('some_new_key', 'some_new_value', 2)
+    #
+    # @param  [String] key The custom_attributes key
+    # @param  [String] value The custom_attributes value
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def add_user_custom_attribute(key, value, user_id)
+      url = "/users/#{user_id}/custom_attributes/#{key}"
+      put(url, body: { value: value })
+    end
+
+    # Delete custom_attribute
+    # Will delete a custom_attribute
+    #
+    # @example
+    #   Gitlab.delete_user_custom_attribute('somekey', 2)
+    #
+    # @param  [String] key The custom_attribute key to delete
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Boolean]
+    def delete_user_custom_attribute(key, user_id)
+      delete("/users/#{user_id}/custom_attributes/#{key}")
+    end
+
+    # Get all impersonation tokens for a user
+    #
+    # @example
+    #   Gitlab.user_impersonation_tokens(1)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [String] state Filter impersonation tokens by state {}
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def user_impersonation_tokens(user_id)
+      get("/users/#{user_id}/impersonation_tokens")
+    end
+
+    # Get impersonation token information
+    #
+    # @example
+    #   Gitlab.user_impersonation_token(1, 1)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [Integer] impersonation_token_id ID of the impersonation token.
+    # @return [Gitlab::ObjectifiedHash]
+    def user_impersonation_token(user_id, impersonation_token_id)
+      get("/users/#{user_id}/impersonation_tokens/#{impersonation_token_id}")
+    end
+
+    # Create impersonation token
+    #
+    # @example
+    #   Gitlab.create_user_impersonation_token(2, "token", ["api", "read_user"])
+    #   Gitlab.create_user_impersonation_token(2, "token", ["api", "read_user"], "1970-01-01")
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [String] name Name for impersonation token.
+    # @param  [Array<String>] scopes Array of scopes for the impersonation token
+    # @param  [String] expires_at Date for impersonation token expiration in ISO format.
+    # @return [Gitlab::ObjectifiedHash]
+    def create_user_impersonation_token(user_id, name, scopes, expires_at = nil)
+      body = { name: name, scopes: scopes }
+      body[:expires_at] = expires_at if expires_at
+      post("/users/#{user_id}/impersonation_tokens", body: body)
+    end
+
+    # Get all personal access tokens for a user
+    #
+    # @example
+    #   Gitlab.user_personal_access_tokens(1)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def user_personal_access_tokens(user_id)
+      get("/personal_access_tokens?user_id=#{user_id}")
+    end
+
+    # Create personal access token
+    #
+    # @example
+    #   Gitlab.create_personal_access_token(2, "token", ["api", "read_user"])
+    #   Gitlab.create_personal_access_token(2, "token", ["api", "read_user"], "1970-01-01")
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [String] name Name of the personal access token.
+    # @param  [Array<String>] scopes Array of scopes for the impersonation token
+    # @param  [String] expires_at Date for impersonation token expiration in ISO format.
+    # @return [Gitlab::ObjectifiedHash]
+    def create_personal_access_token(user_id, name, scopes, expires_at = nil)
+      body = { name: name, scopes: scopes }
+      body[:expires_at] = expires_at if expires_at
+      post("/users/#{user_id}/personal_access_tokens", body: body)
+    end
+
+    # Rotate a personal access token
+    #
+    # @example
+    #   Gitlab.rotate_personal_access_token(1)
+    #
+    # @param  [Integer] personal_access_token_id ID of the personal access token.
+    # @return [Gitlab::ObjectifiedHash]
+    def rotate_personal_access_token(personal_access_token_id, expires_at = nil)
+      body = {}
+      body[:expires_at] = expires_at if expires_at
+      post("/personal_access_tokens/#{personal_access_token_id}/rotate", body: body)
+    end
+
+    # Revoke an impersonation token
+    #
+    # @example
+    #   Gitlab.revoke_user_impersonation_token(1, 1)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [Integer] impersonation_token_id ID of the impersonation token.
+    # @return [Gitlab::ObjectifiedHash]
+    def revoke_user_impersonation_token(user_id, impersonation_token_id)
+      delete("/users/#{user_id}/impersonation_tokens/#{impersonation_token_id}")
+    end
+
+    # Lists all projects and groups a user is a member of
+    #
+    # @example
+    #   Gitlab.memberships(2)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    def memberships(user_id)
+      get("/users/#{user_id}/memberships")
+    end
+
+    # Revoke a personal access token
+    #
+    # @example
+    #   Gitlab.revoke_personal_access_token(1)
+    #
+    # @param  [Integer] personal_access_token_id ID of the personal access token.
+    # @return [Gitlab::ObjectifiedHash]
+    def revoke_personal_access_token(personal_access_token_id)
+      delete("/personal_access_tokens/#{personal_access_token_id}")
+    end
+
+    # Disables two factor authentication (2FA) for the specified user.
+    #
+    # @example
+    #   Gitlab.disable_two_factor(1)
+    #
+    # @param [Integer] id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def disable_two_factor(user_id)
+      patch("/users/#{user_id}/disable_two_factor")
     end
   end
 end

data/lib/gitlab/client/versions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Gitlab::Client
+  # Defines methods related to version
+  # @see https://docs.gitlab.com/ce/api/version.html
+  module Versions
+    # Returns server version.
+    # @see https://docs.gitlab.com/ce/api/version.html
+    #
+    # @example
+    #   Gitlab.version
+    #
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def version
+      get('/version')
+    end
+  end
+end

data/lib/gitlab/client/wikis.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+class Gitlab::Client
+  # Defines methods related to wikis.
+  # @see https://docs.gitlab.com/ce/api/wikis.html
+  module Wikis
+    # Get all wiki pages for a given project.
+    #
+    # @example
+    #   Gitlab.wikis(3)
+    #   Gitlab.wikis(3, {with_content: 'Some wiki content'})
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] with_content(optional) Include pages content
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def wikis(project, options = {})
+      get("/projects/#{url_encode project}/wikis", query: options)
+    end
+
+    # Get a wiki page for a given project.
+    #
+    # @example
+    #   Gitlab.wiki(3, 'home')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] slug The slug (a unique string) of the wiki page
+    # @return [Gitlab::ObjectifiedHash]
+    def wiki(project, slug)
+      get("/projects/#{url_encode project}/wikis/#{slug}")
+    end
+
+    # Creates a new wiki page for the given repository with the given title, slug, and content.
+    #
+    # @example
+    #   Gitlab.create_wiki(3, 'Some Title', 'Some Content')
+    #   Gitlab.create_wiki(3, 'Some Title', 'Some Content', { format: 'rdoc' })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] content The content of the wiki page.
+    # @param  [String] title The title of the wiki page.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] format (optional) The format of the wiki page. Available formats are: markdown (default), rdoc, and asciidoc.
+    # @return [Gitlab::ObjectifiedHash] Information about created wiki page.
+    def create_wiki(project, title, content, options = {})
+      body = { content: content, title: title }.merge(options)
+      post("/projects/#{url_encode project}/wikis", body: body)
+    end
+
+    # Updates an existing wiki page. At least one parameter is required to update the wiki page.
+    #
+    # @example
+    #   Gitlab.update_wiki(6, 'home', { title: 'New title' })
+    #   Gitlab.update_wiki(6, 'home', { title: 'New title', content: 'New Message', format: 'rdoc' })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] slug The slug (a unique string) of the wiki page.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] content The content of the wiki page.
+    # @option options [String] title The title of the wiki page.
+    # @option options [String] format (optional) The format of the wiki page. Available formats are: markdown (default), rdoc, and asciidoc.
+    # @return [Gitlab::ObjectifiedHash] Information about updated wiki page.
+    def update_wiki(project, slug, options = {})
+      put("/projects/#{url_encode project}/wikis/#{slug}", body: options)
+    end
+
+    # Deletes a wiki page with a given slug.
+    #
+    # @example
+    #   Gitlab.delete_wiki(42, 'foo')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] slug The slug (a unique string) of the wiki page.
+    # @return [Gitlab::ObjectifiedHash] An empty objectified hash
+    def delete_wiki(project, slug)
+      delete("/projects/#{url_encode project}/wikis/#{slug}")
+    end
+  end
+end

data/lib/gitlab/client.rb

@@ -1,66 +1,105 @@
+# frozen_string_literal: true
+
 module Gitlab
   # Wrapper for the Gitlab REST API.
   class Client < API
-    Dir[File.expand_path('../client/*.rb', __FILE__)].each { |f| require f }
+    Dir[File.expand_path('client/*.rb', __dir__)].each { |f| require f }
 
     # Please keep in alphabetical order
     include AccessRequests
+    include ApplicationSettings
+    include Avatar
     include AwardEmojis
     include Boards
     include Branches
+    include BroadcastMessages
     include BuildVariables
     include Builds
     include Commits
+    include ContainerRegistry
     include Deployments
     include Environments
+    include EpicIssues
+    include Epics
     include Events
+    include Features
+    include GroupBadges
+    include GroupBoards
+    include GroupLabels
     include GroupMilestones
     include Groups
+    include IssueLinks
     include Issues
     include Jobs
     include Keys
     include Labels
+    include Lint
+    include Markdown
     include MergeRequestApprovals
     include MergeRequests
+    include MergeTrains
     include Milestones
     include Namespaces
     include Notes
+    include Packages
     include PipelineSchedules
     include PipelineTriggers
     include Pipelines
+    include ProjectBadges
+    include ProjectClusters
+    include ProjectExports
+    include ProjectReleaseLinks
+    include ProjectReleases
     include Projects
+    include ProtectedTags
+    include RemoteMirrors
     include Repositories
     include RepositoryFiles
+    include RepositorySubmodules
+    include ResourceLabelEvents
+    include ResourceStateEvents
     include Runners
+    include Search
     include Services
     include Sidekiq
     include Snippets
     include SystemHooks
     include Tags
+    include Templates
     include Todos
     include Users
+    include UserSnippets
+    include Versions
+    include Wikis
 
     # Text representation of the client, masking private token.
     #
     # @return [String]
     def inspect
       inspected = super
-
-      if @private_token
-        inspected = inspected.sub! @private_token, only_show_last_four_chars(@private_token)
-      end
-
+      inspected = redact_private_token(inspected, @private_token) if @private_token
       inspected
     end
 
-    def url_encode(s)
-      URI.encode(s.to_s, /\W/)
+    # Utility method for URL encoding of a string.
+    # Copied from https://ruby-doc.org/stdlib-2.7.0/libdoc/erb/rdoc/ERB/Util.html
+    #
+    # @return [String]
+    def url_encode(url)
+      url.to_s.b.gsub(/[^a-zA-Z0-9_\-.~]/n) { |m| sprintf('%%%02X', m.unpack1('C')) } # rubocop:disable Style/FormatString
     end
 
     private
 
+    def redact_private_token(inspected, private_token)
+      redacted = only_show_last_four_chars(private_token)
+      inspected.sub %(@private_token="#{private_token}"), %(@private_token="#{redacted}")
+    end
+
     def only_show_last_four_chars(token)
-      "#{'*' * (token.size - 4)}#{token[-4..-1]}"
+      return '****' if token.size <= 4
+
+      "#{'*' * (token.size - 4)}#{token[-4..]}"
     end
   end
 end