gitlab 4.19.0 → 5.1.0

data/lib/gitlab/client/pipelines.rb

@@ -43,6 +43,18 @@ class Gitlab::Client
       get("/projects/#{url_encode project}/pipelines/#{id}/test_report")
     end
 
+    # Gets a single pipeline's variables.
+    #
+    # @example
+    #   Gitlab.pipeline_variables(5, 36)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a pipeline.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def pipeline_variables(project, id)
+      get("/projects/#{url_encode project}/pipelines/#{id}/variables")
+    end
+
     # Create a pipeline.
     #
     # @example
@@ -101,5 +113,18 @@ class Gitlab::Client
     def delete_pipeline(project, id)
       delete("/projects/#{url_encode project}/pipelines/#{id}")
     end
+
+    # Update a pipeline metadata
+    #
+    # @example
+    #   Gitlab.update_pipeline_metadata(5, 1, name: 'new name')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a pipeline.
+    # @option options [String] :name The new name of the pipeline.
+    # @return [Gitlab::ObjectifiedHash]
+    def update_pipeline_metadata(project, id, options = {})
+      put("/projects/#{url_encode project}/pipelines/#{id}/metadata", body: options)
+    end
   end
 end

data/lib/gitlab/client/project_exports.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Gitlab::Client
+  # Defines methods related to project exports.
+  # @see https://docs.gitlab.com/ce/api/project_import_export.html
+  module ProjectExports
+    # Start a new export
+    #
+    # @example
+    #   Gitlab.export_project(2)
+    #
+    # @param [Integer, String] id The ID or path of a project.
+    # @param [Hash] options A customizable set of options.
+    # @option options [String] description(optional) Overrides the project description
+    # @option options [hash] upload(optional) Hash that contains the information to upload the exported project to a web server
+    # @option options [String] upload[url] TThe URL to upload the project
+    # @option options [String] upload[http_method](optional) The HTTP method to upload the exported project. Only PUT and POST methods allowed. Default is PUT
+    # @return [Gitlab::ObjectifiedHash]
+    def export_project(id, options = {})
+      post("/projects/#{url_encode id}/export", body: options)
+    end
+
+    # Get the status of export
+    #
+    # @example
+    #   Gitlab.export_project_status(2)
+    #
+    # @param [Integer, String] id The ID or path of a project.
+    # @return [Gitlab::ObjectifiedHash]
+    def export_project_status(id)
+      get("/projects/#{url_encode id}/export")
+    end
+
+    # Download the finished export
+    #
+    # @example
+    #   Gitlab.exported_project_download(2)
+    #
+    # @param [Integer, String] id The ID or path of a project.
+    # @return [Gitlab::FileResponse]
+    def exported_project_download(id)
+      get("/projects/#{url_encode id}/export/download",
+          format: nil,
+          headers: { Accept: 'application/octet-stream' },
+          parser: proc { |body, _|
+            if body.encoding == Encoding::ASCII_8BIT # binary response
+              ::Gitlab::FileResponse.new StringIO.new(body, 'rb+')
+            else # error with json response
+              ::Gitlab::Request.parse(body)
+            end
+          })
+    end
+  end
+end

data/lib/gitlab/client/project_releases.rb

@@ -75,5 +75,16 @@ class Gitlab::Client
     def delete_project_release(project, tag_name)
       delete("/projects/#{url_encode project}/releases/#{tag_name}")
     end
+
+    # Gets Latest Release
+    #
+    # @example
+    #   Gitlab.project_latest_release(5)
+    #
+    # @param [Integer, String] project The ID or name of a project
+    # @return [Gitlab::ObjectifiedHash] Information about the release
+    def project_latest_release(project)
+      get("/projects/#{url_encode project}/releases/permalink/latest")
+    end
   end
 end

data/lib/gitlab/client/projects.rb

@@ -3,7 +3,7 @@
 class Gitlab::Client
   # Defines methods related to projects.
   # @see https://docs.gitlab.com/ce/api/projects.html
-  module Projects
+  module Projects # rubocop:disable Metrics/ModuleLength
     # Gets a list of projects owned by the authenticated user.
     #
     # @example
@@ -704,5 +704,85 @@ class Gitlab::Client
     def project_deploy_tokens(project, options = {})
       get("/projects/#{url_encode project}/deploy_tokens", query: options)
     end
+
+    # Get languages used with percentage value
+    #
+    # @example
+    #   Gitlab.project_languages(42)
+    #
+    # @param [Integer, String] id The ID or path of a project.
+    # @return [Gitlab::ObjectifiedHash]
+    def project_languages(project)
+      get("/projects/#{url_encode project}/languages")
+    end
+
+    # List all project access tokens.
+    #
+    # @example
+    #   Gitlab.project_access_tokens(42)
+    #
+    # @param [Integer, String] project The ID or path of a project.
+    # @option options [String] :state Limit by active/inactive state. Optional.
+    #
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def project_access_tokens(project, options = {})
+      get("/projects/#{url_encode project}/access_tokens", query: options)
+    end
+
+    # Get a specific project access token.
+    #
+    # @example
+    #   Gitlab.project_access_token(42, 1234)
+    #
+    # @param [Integer, String] project The ID or path of a project.
+    # @param [Integer] token_id The ID of the project access token.
+    #
+    # @return [Gitlab::ObjectifiedHash] Information about the specified project access token.
+    def project_access_token(project, token_id)
+      get("/projects/#{url_encode project}/access_tokens/#{token_id}")
+    end
+
+    # Creates a new project access token.
+    #
+    # @example
+    #   Gitlab.create_project_access_token(42, 'My Token', ['api'], '2024-12-12', access_level: 40)
+    #
+    # @param  [Integer, String] project The ID or path of a project.
+    # @param  [String] name The name of the project access token.
+    # @param  [Array] scopes List of scopes of the project access token.
+    # @param  [String] expires_at A date string in the format YYYY-MM-DD.
+    # @option options [Integer] :access_level Access level. Optional. Defaults to 40.
+    #
+    # @return [Gitlab::ObjectifiedHash] Information about the created project access token.
+    def create_project_access_token(project, name, scopes, expires_at, options = {})
+      post("/projects/#{url_encode project}/access_tokens", body: { name: name, scopes: scopes, expires_at: expires_at }.merge(options))
+    end
+
+    # Rotate a project access token.
+    #
+    # @example
+    #   Gitlab.rotate_project_access_token(42, 1234)
+    #
+    # @param [Integer, String] project The ID or path of a project.
+    # @param [Integer] token_id The ID of the project access token.
+    # @option options [String] :expires_at A date string in the format YEAR-MONTH-DAY.
+    #
+    # @return [Gitlab::ObjectifiedHash] Information about the specified project access token.
+    def rotate_project_access_token(project, token_id, options = {})
+      post("/projects/#{url_encode project}/access_tokens/#{token_id}/rotate", query: options)
+    end
+
+    # Revoke a project access token.
+    #
+    # @example
+    #   Gitlab.revoke_project_access_token(42, 1234)
+    #
+    # @param [Integer, String] project The ID or path of a project.
+    # @param [Integer] token_id The ID of the project access token.
+    #
+    # @return [Gitlab::ObjectifiedHash]
+    def revoke_project_access_token(project, token_id)
+      delete("/projects/#{url_encode project}/access_tokens/#{token_id}")
+    end
   end
 end

data/lib/gitlab/client/runners.rb

@@ -207,5 +207,72 @@ class Gitlab::Client
       body = { token: token }
       post('/runners/verify', body: body)
     end
+
+    # Creates a new group runner with the new Gitlab approach (v16.0+) and returns the id/token information
+    # https://docs.gitlab.com/ee/api/users.html#create-a-runner
+    # You must use an access token with the create_runner scope
+    #
+    # @example
+    #   Gitlab.create_group_runner(9, tag_list: ['one', 'two'])
+    #   Gitlab.create_group_runner(9, paused: false, description: 'A note', run_untagged: true)
+    #
+    # @param  [String] group(required) Group ID.
+    # @param  [Hash] options A customizable set of options.
+    # @return <Gitlab::ObjectifiedHash> Response against runner registration
+    def create_group_runner(group, options = {})
+      create_runner({ runner_type: 'group_type', group_id: group }.merge(options))
+    end
+
+    # Creates a new project runner with the new Gitlab approach (v16.0+) and returns the id/token information
+    # https://docs.gitlab.com/ee/api/users.html#create-a-runner
+    # You must use an access token with the create_runner scope
+    #
+    # @example
+    #   Gitlab.create_project_runner(12, tag_list: ['one', 'two'])
+    #   Gitlab.create_project_runner(12, paused: false, description: 'A note', run_untagged: true)
+    #
+    # @param  [String] project(required) Project ID.
+    # @param  [Hash] options A customizable set of options.
+    # @return <Gitlab::ObjectifiedHash> Response against runner registration
+    def create_project_runner(project, options = {})
+      create_runner({ runner_type: 'project_type', project_id: project }.merge(options))
+    end
+
+    # Creates a new instance runner with the new Gitlab approach (v16.0+) and returns the id/token information
+    # You must be an administrator of the GitLab instance
+    # You must use an access token with the create_runner scope
+    # https://docs.gitlab.com/ee/api/users.html#create-a-runner
+    #
+    # @example
+    #   Gitlab.create_instance_runner(tag_list: ['one', 'two'])
+    #   Gitlab.create_instance_runner(paused: false, description: 'A note', run_untagged: true)
+    #
+    # @param  [String] group(required) Project ID.
+    # @param  [Hash] options A customizable set of options.
+    # @return <Gitlab::ObjectifiedHash> Response against runner registration
+    def create_instance_runner(options = {})
+      create_runner({ runner_type: 'instance_type' }.merge(options))
+    end
+
+    private
+
+    # Creates a runner linked to the current user.
+    # You must use an access token with the create_runner scope
+    # https://docs.gitlab.com/ee/api/users.html#create-a-runner
+    #
+    # @param  [Hash] options(required) A customizable set of options.
+    # @option options [String] :description(optional) Runner description.
+    # @option options [Hash] :info(optional) Runner metadata.
+    # @option options [Boolean] :paused(optional) Whether the Runner ignores new jobs.
+    # @option options [Boolean] :locked(optional) Whether the Runner should be locked for current project.
+    # @option options [Boolean] :run_untagged(optional) Whether the Runner should handle untagged jobs.
+    # @option options [Array<String>] :tag_list(optional) List of Runner tags.
+    # @option options [String] :access_level(optional) Access level of the runner; not_protected or ref_protected.
+    # @option options [Integer] :maximum_timeout(optional) Maximum timeout set when this Runner will handle the job.
+    # @option options [String] :maintenance_note(optional) Free-form maintenance notes for the runner (1024 characters).
+    # @return <Gitlab::ObjectifiedHash> Response against runner registration {"id": 1, "token": foo "token_expires_at": null}
+    def create_runner(options)
+      post('/user/runners', body: options)
+    end
   end
 end

data/lib/gitlab/client/users.rb

@@ -58,6 +58,22 @@ class Gitlab::Client
       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
@@ -110,6 +126,28 @@ 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
@@ -276,7 +314,7 @@ class Gitlab::Client
       delete(url)
     end
 
-    # Search for groups by name
+    # Search for users by name
     #
     # @example
     #   Gitlab.user_search('gitlab')
@@ -291,6 +329,19 @@ class Gitlab::Client
       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
@@ -382,6 +433,47 @@ class Gitlab::Client
       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
@@ -393,5 +485,37 @@ class Gitlab::Client
     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.rb

@@ -37,6 +37,7 @@ module Gitlab
     include Markdown
     include MergeRequestApprovals
     include MergeRequests
+    include MergeTrains
     include Milestones
     include Namespaces
     include Notes
@@ -46,6 +47,7 @@ module Gitlab
     include Pipelines
     include ProjectBadges
     include ProjectClusters
+    include ProjectExports
     include ProjectReleaseLinks
     include ProjectReleases
     include Projects
@@ -75,7 +77,7 @@ module Gitlab
     # @return [String]
     def inspect
       inspected = super
-      inspected.sub! @private_token, only_show_last_four_chars(@private_token) if @private_token
+      inspected = redact_private_token(inspected, @private_token) if @private_token
       inspected
     end
 
@@ -89,7 +91,14 @@ module Gitlab
 
     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)
+      return '****' if token.size <= 4
+
       "#{'*' * (token.size - 4)}#{token[-4..]}"
     end
   end

data/lib/gitlab/configuration.rb

@@ -5,7 +5,7 @@ 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 = %i[endpoint private_token user_agent sudo httparty].freeze
+    VALID_OPTIONS_KEYS = %i[endpoint private_token user_agent sudo httparty pat_prefix].freeze
 
     # The user agent that will be sent to the API endpoint if none is set.
     DEFAULT_USER_AGENT = "Gitlab Ruby Gem #{Gitlab::VERSION}"
@@ -37,6 +37,7 @@ module Gitlab
     def reset
       self.endpoint       = ENV['GITLAB_API_ENDPOINT'] || ENV['CI_API_V4_URL']
       self.private_token  = ENV['GITLAB_API_PRIVATE_TOKEN'] || ENV['GITLAB_API_AUTH_TOKEN']
+      self.pat_prefix     = nil
       self.httparty       = get_httparty_config(ENV['GITLAB_API_HTTPARTY_OPTIONS'])
       self.sudo           = nil
       self.user_agent     = DEFAULT_USER_AGENT

data/lib/gitlab/headers/page_links.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Headers
+    # Parses link header.
+    #
+    # @private
+    class PageLinks
+      HEADER_LINK = 'Link'
+      DELIM_LINKS = ','
+      LINK_REGEX = /<([^>]+)>; rel="([^"]+)"/
+      METAS = %w[last next first prev].freeze
+
+      attr_accessor(*METAS)
+
+      def initialize(headers)
+        link_header = headers[HEADER_LINK]
+
+        extract_links(link_header) if link_header && link_header =~ /(next|first|last|prev)/
+      end
+
+      private
+
+      def extract_links(header)
+        header.split(DELIM_LINKS).each do |link|
+          LINK_REGEX.match(link.strip) do |match|
+            url = match[1]
+            meta = match[2]
+            next if !url || !meta || METAS.index(meta).nil?
+
+            send("#{meta}=", url)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/headers/total.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Headers
+    # Parses total header.
+    #
+    # @private
+    class Total
+      HEADER_TOTAL = 'x-total'
+      TOTAL_REGEX = /^\d+$/
+
+      attr_accessor :total
+
+      def initialize(headers)
+        header_total = headers[HEADER_TOTAL]
+
+        extract_total(header_total) if header_total
+      end
+
+      private
+
+      def extract_total(header_total)
+        TOTAL_REGEX.match(header_total.strip) do |match|
+          @total = match[0]
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/paginated_response.rb

@@ -30,7 +30,8 @@ module Gitlab
     end
 
     def parse_headers!(headers)
-      @links = PageLinks.new headers
+      @links = Headers::PageLinks.new headers
+      @total = Headers::Total.new headers
     end
 
     def each_page
@@ -58,6 +59,10 @@ module Gitlab
       lazy_paginate.take(limit).each(&block)
     end
 
+    def total
+      @total.total
+    end
+
     def last_page?
       !(@links.nil? || @links.last.nil?)
     end

data/lib/gitlab/request.rb

@@ -12,7 +12,7 @@ module Gitlab
     headers 'Accept' => 'application/json', 'Content-Type' => 'application/x-www-form-urlencoded'
     parser(proc { |body, _| parse(body) })
 
-    attr_accessor :private_token, :endpoint
+    attr_accessor :private_token, :endpoint, :pat_prefix
 
     # Converts the response body to an ObjectifiedHash.
     def self.parse(body)
@@ -38,7 +38,7 @@ module Gitlab
       raise Error::Parsing, 'The response is not a valid JSON'
     end
 
-    %w[get post put delete].each do |method|
+    %w[get post put patch delete].each do |method|
       define_method method do |path, options = {}|
         params = options.dup
 
@@ -93,10 +93,19 @@ module Gitlab
     def authorization_header
       raise Error::MissingCredentials, 'Please provide a private_token or auth_token for user' unless private_token
 
-      if private_token.size < 21
+      # The Personal Access Token prefix can be at most 20 characters, and the
+      # generated part is of length 20 characters. Personal Access Tokens, thus
+      # can have a maximum size of 40 characters. GitLab uses
+      # `Doorkeeper::OAuth::Helpers::UniqueToken.generate` for generating
+      # OAuth2 tokens, and specified `hex` as token generator method. Thus, the
+      # OAuth2 tokens are of length more than 64. If the token length is below
+      # that, it is probably a Personal Access Token or CI_JOB_TOKEN.
+      if private_token.size >= 64
+        { 'Authorization' => "Bearer #{private_token}" }
+      elsif private_token.start_with?(pat_prefix.to_s)
         { 'PRIVATE-TOKEN' => private_token }
       else
-        { 'Authorization' => "Bearer #{private_token}" }
+        { 'JOB-TOKEN' => private_token }
       end
     end
 

data/lib/gitlab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gitlab
-  VERSION = '4.19.0'
+  VERSION = '5.1.0'
 end

data/lib/gitlab.rb

@@ -4,7 +4,8 @@ require 'gitlab/version'
 require 'gitlab/objectified_hash'
 require 'gitlab/configuration'
 require 'gitlab/error'
-require 'gitlab/page_links'
+require 'gitlab/headers/page_links'
+require 'gitlab/headers/total'
 require 'gitlab/paginated_response'
 require 'gitlab/file_response'
 require 'gitlab/request'
@@ -49,8 +50,10 @@ module Gitlab
   #
   # @return [Array<Symbol>]
   def self.actions
+    # rubocop:disable Layout/LineLength
     hidden =
-      /endpoint|private_token|auth_token|user_agent|sudo|get|post|put|\Adelete\z|validate\z|request_defaults|httparty/
+      /endpoint|private_token|auth_token|user_agent|sudo|get|post|put|patch|\Adelete\z|validate\z|request_defaults|httparty/
+    # rubocop:enable Layout/LineLength
     (Gitlab::Client.instance_methods - Object.methods).reject { |e| e[hidden] }
   end
 end