gitlab 4.5.0 → 5.1.0

data/lib/gitlab/client/jobs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Gitlab::Client
   # Defines methods related to projects.
   # @see https://docs.gitlab.com/ee/api/jobs.html
@@ -7,10 +9,13 @@ class Gitlab::Client
     # @example
     #   Gitlab.jobs(1)
     #   Gitlab.jobs("project")
+    #   Gitlab.jobs("project", {scope: ["manual", "success"], per_page: 100 })
     #
     # @param  [Integer, String] id The ID or name of a project.
     # @param  [Hash] options A customizable set of options.
     # @option options [Array] :scope The scope of jobs to show, one or array of: created, pending, running, failed, success, canceled, skipped, manual; showing all jobs if none provided.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
     # @return [Array<Gitlab::ObjectifiedHash>]
     def jobs(project_id, options = {})
       get("/projects/#{url_encode project_id}/jobs", query: options)
@@ -31,6 +36,21 @@ class Gitlab::Client
       get("/projects/#{url_encode project_id}/pipelines/#{pipeline_id}/jobs", query: options)
     end
 
+    # Gets a list of Bridge Jobs from a pipeline
+    #
+    # @example
+    #   Gitlab.pipeline_bridges(1, 2)
+    #   Gitlab.pipeline_bridges("project", 2)
+    #
+    # @param  [Integer, String] The ID or name of a project.
+    # @param  [Integer]  the id of the pipeline
+    # @param  [Hash] options A customizable set of options.
+    # @option options [Array] :scope The scope of bridge jobs to show, one or array of: created, pending, running, failed, success, canceled, skipped, manual; showing all bridge jobs if none provided.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def pipeline_bridges(project_id, pipeline_id, options = {})
+      get("/projects/#{url_encode project_id}/pipelines/#{pipeline_id}/bridges", query: options)
+    end
+
     # Gets a single job
     #
     # @example
@@ -65,16 +85,70 @@ class Gitlab::Client
     #   Gitlab.job_artifacts_download(1, "master", "release")
     #   Gitlab.job_artifacts_download("project", "master", "release")
     #
-    # @param  [Integer, String] id, The ID or name of a project.
-    # @param  [String]  ref, Ref Name
-    # @param  [String]  job, jobname
-    # @return [Array<Gitlab::ObjectifiedHash>]
+    # @param  [Integer, String] project_id The ID or name of a project.
+    # @param  [String]  ref Ref Name
+    # @param  [String]  job jobname
+    # @return [Gitlab::FileResponse]
     def job_artifacts_download(project_id, ref_name, job_name)
-      get("/projects/#{url_encode project_id}/jobs/artifacts/#{ref_name}/download", query: { job: job_name },
-                                                                                    format: nil,
-                                                                                    headers: { Accept: 'text/plain' },
-                                                                                    parser: ::Gitlab::Request::Parser)
+      get("/projects/#{url_encode project_id}/jobs/artifacts/#{ref_name}/download",
+          query: { job: job_name },
+          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
+
+    # Download a single artifact file by job ID
+    #
+    # @example
+    #   Gitlab.download_job_artifact_file(1, 5, "some/release/file.pdf")
+    #
+    # @param  [Integer, String] project_id(required) The ID or name of a project.
+    # @param  [String]  job_id(required) The unique job identifier.
+    # @param  [String]  artifact_path(required) Path to a file inside the artifacts archive.
+    # @return [Gitlab::FileResponse]
+    def download_job_artifact_file(project_id, job_id, artifact_path)
+      get("/projects/#{url_encode project_id}/jobs/#{job_id}/artifacts/#{artifact_path}",
+          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
+
+    # Download a single artifact file from specific tag or branch
+    #
+    # @example
+    #   Gitlab.download_branch_artifact_file(1, "master", "some/release/file.pdf", 'pdf')
+    #
+    # @param  [Integer, String] project_id(required) The ID or name of a project.
+    # @param  [String]  ref_name(required) Branch or tag name in repository. HEAD or SHA references are not supported.
+    # @param  [String]  artifact_path(required) Path to a file inside the artifacts archive.
+    # @param  [String]  job(required) The name of the job.
+    # @return [Gitlab::FileResponse]
+    def download_branch_artifact_file(project_id, ref_name, artifact_path, job)
+      get("/projects/#{url_encode project_id}/jobs/artifacts/#{ref_name}/raw/#{artifact_path}",
+          query: { job: job },
+          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
+    alias download_tag_artifact_file download_branch_artifact_file
 
     # Get Job Trace
     #
@@ -158,5 +232,19 @@ class Gitlab::Client
     def job_artifacts_keep(project_id, job_id)
       post("/projects/#{url_encode project_id}/jobs/#{job_id}/artifacts/keep")
     end
+
+    # Delete Artifacts
+    # Deletes the artifacts associated with a job.
+    #
+    # @example
+    #   Gitlab.job_artifacts_delete(1,1)
+    #   Gitlab.job_artifacts_delete("project", 1)
+    #
+    # @param  [Integer, String] The ID or name of a project.
+    # @param  [Integer]  the id of the job
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def job_artifacts_delete(project_id, job_id)
+      delete("/projects/#{url_encode project_id}/jobs/#{job_id}/artifacts")
+    end
   end
 end

data/lib/gitlab/client/keys.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Gitlab::Client
   # Defines methods related to keys.
   # @see https://docs.gitlab.com/ce/api/keys.html
@@ -12,5 +14,16 @@ class Gitlab::Client
     def key(id)
       get("/keys/#{id}")
     end
+
+    # Gets information about a key by key fingerprint.
+    #
+    # @example
+    #   Gitlab.key_by_fingerprint("9f:70:33:b3:50:4d:9a:a3:ef:ea:13:9b:87:0f:7f:7e")
+    #
+    # @param  [String] fingerprint The Fingerprint of a key.
+    # @return [Gitlab::ObjectifiedHash]
+    def key_by_fingerprint(fingerprint)
+      get('/keys', query: { fingerprint: fingerprint })
+    end
   end
 end

data/lib/gitlab/client/labels.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 class Gitlab::Client
-  # Defines methods related to labels.
+  # Defines methods related to project labels.
   # @see https://docs.gitlab.com/ce/api/labels.html
   module Labels
     # Gets a list of project's labels.
@@ -9,7 +11,7 @@ class Gitlab::Client
     #
     # @param  [Integer, String] project The ID or name of a project.
     # @return [Array<Gitlab::ObjectifiedHash>]
-    def labels(project, options={})
+    def labels(project, options = {})
       get("/projects/#{url_encode project}/labels", query: options)
     end
 
@@ -43,7 +45,7 @@ class Gitlab::Client
     # @option options [String] :description The description of the label.
     # @option options [String] :priority The priority of the label. Must be greater or equal than zero or null to remove the priority.
     # @return [Gitlab::ObjectifiedHash] Information about updated label.
-    def edit_label(project, name, options={})
+    def edit_label(project, name, options = {})
       put("/projects/#{url_encode project}/labels", body: options.merge(name: name))
     end
 
@@ -56,7 +58,7 @@ class Gitlab::Client
     # @param  [String] name The name of a label.
     # @return [Gitlab::ObjectifiedHash] Information about deleted label.
     def delete_label(project, name)
-      delete("/projects/#{url_encode project}/labels", body: { name: name })
+      delete("/projects/#{url_encode project}/labels/#{name}")
     end
 
     # Subscribes the user to a label to receive notifications

data/lib/gitlab/client/lint.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class Gitlab::Client
+  # Defines methods related to lint/validations.
+  # @see https://docs.gitlab.com/ce/api/lint.html
+  module Lint
+    # Checks if your .gitlab-ci.yml file is valid.
+    #
+    # @example
+    #   Gitlab.validate_gitlab_ci_yml("{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}")
+    #
+    # @param  [String] content the .gitlab-ci.yaml content.
+    # @return <Gitlab::ObjectifiedHash> Returns information about validity of the yml.
+    def validate_gitlab_ci_yml(content)
+      body = { content: content }
+      post('/lint', body: body)
+    end
+  end
+end

data/lib/gitlab/client/markdown.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Gitlab::Client
+  # Defines methods related to markdown.
+  # @see https://docs.gitlab.com/ce/api/markdown.html
+  module Markdown
+    # Render an arbitrary Markdown document
+    #
+    # @example
+    #   Gitlab.markdown('Hello world! :tada:')
+    #   Gitlab.markdown('Hello world! :tada:', gfm: true, project: 'group_example/project_example')
+    #
+    # @param  [String] text The markdown text to render.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [Boolean] :gfm(optional) Render text using GitLab Flavored Markdown. Default is false.
+    # @option options [String] :project(optional) Use project as a context when creating references using GitLab Flavored Markdown. Authentication is required if a project is not public.
+    # @return <Gitlab::ObjectifiedHash> Returns the rendered markdown as response
+    def markdown(text, options = {})
+      body = { text: text }.merge(options)
+      post('/markdown', body: body)
+    end
+  end
+end

data/lib/gitlab/client/merge_request_approvals.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Gitlab::Client
   # Defines methods related to MR Approvals.
   # @see https://docs.gitlab.com/ee/api/merge_request_approvals.html
@@ -29,17 +31,75 @@ class Gitlab::Client
       post("/projects/#{url_encode project}/approvals", body: options)
     end
 
+    # Gets MR Approval Rules for a project
+    #
+    # @example
+    #   Gitlab.project_merge_request_approval_rules(1)
+    #
+    # @param [Integer] project The ID of a project.
+    # @return [Gitlab::ObjectifiedHash] MR approval rules for the project
+    def project_merge_request_approval_rules(project)
+      get("/projects/#{url_encode project}/approval_rules")
+    end
+
+    # Create MR Approval Rule for a project
+    #
+    # @example
+    #   Gitlab.create_project_merge_request_approval_rule(1, {name: "security", approvals_required: 1})
+    #
+    # @param [Integer] project(required) The ID of a project.
+    # @option options [String] :name(required) The name of the approval rule
+    # @option options [Integer] :approvals_required(required) The number of required approvals for this rule
+    # @option options [Array] :user_ids(optional) The ids of users as approvers
+    # @option options [Array] :group_ids(optional) The ids of groups as approvers
+    # @option options [Array] :protected_branch_ids(optional) The ids of protected branches to scope the rule by
+    # @return [Gitlab::ObjectifiedHash] New MR approval rule
+    def create_project_merge_request_approval_rule(project, options = {})
+      post("/projects/#{url_encode project}/approval_rules", body: options)
+    end
+
+    # Update MR Approval Rule for a project
+    #
+    # @example
+    #   Gitlab.update_project_merge_request_approval_rule(1, {name: "security", approvals_required: 2})
+    #
+    # @param [Integer] project(required) The ID of a project.
+    # @param [Integer] approval_rule_id(required) The ID of a project Approval Rule
+    # @option options [String] :name(required) The name of the approval rule
+    # @option options [Integer] :approvals_required(required) The number of required approvals for this rule
+    # @option options [Array] :user_ids(optional) The ids of users as approvers
+    # @option options [Array] :group_ids(optional) The ids of groups as approvers
+    # @option options [Array] :protected_branch_ids(optional) The ids of protected branches to scope the rule by
+    # @return [Gitlab::ObjectifiedHash] Updated MR approval rule
+    def update_project_merge_request_approval_rule(project, approval_rule_id, options = {})
+      put("/projects/#{url_encode project}/approval_rules/#{approval_rule_id}", body: options)
+    end
+
+    # Delete MR Approval Rule for a project
+    #
+    # @example
+    #   Gitlab.delete_project_merge_request_approval_rule(1, 1)
+    #
+    # @param [Integer] project(required) The ID of a project.
+    # @param [Integer] approval_rule_id(required) The ID of a approval rule
+    # @return [void] This API call returns an empty response body
+    def delete_project_merge_request_approval_rule(project, approval_rule_id)
+      delete("/projects/#{url_encode project}/approval_rules/#{approval_rule_id}")
+    end
+
     # Change allowed approvers and approver groups for a project
+    # @deprecated Since Gitlab 13.12 /approvers endpoints are removed!!!
+    # See Gitlab.create_project_merge_request_approval_rule
     #
     # @example
     #    Gitlab.edit_project_approvers(1, {approver_ids: [5], approver_groups: [1]})
     #
     # @param [Integer] project(required) The ID of a project.
-    # @option options [Array] :approver_ids(optional) An array of User IDs that can approve MRs
-    # @option options [Array] :approver_group_ids(optional) An array of Group IDs whose members can approve MRs
+    # @option options [Array] :approver_ids(required, nil if none) An array of User IDs that can approve MRs
+    # @option options [Array] :approver_group_ids(required, nil if none) An array of Group IDs whose members can approve MRs
     # @return [Gitlab::ObjectifiedHash] MR approval configuration information about the project
     def edit_project_approvers(project, options = {})
-      put("/projects/#{url_encode project}/approvals", body: options)
+      put("/projects/#{url_encode project}/approvers", body: options)
     end
 
     # Get Configuration for approvals on a specific Merge Request.
@@ -68,17 +128,99 @@ class Gitlab::Client
     end
 
     # Change allowed approvers and approver groups for a merge request
+    # @deprecated Since Gitlab 13.12 /approvers endpoints are removed!!!
+    # See Gitlab.create_merge_request_level_rule
     #
     # @example
     #    Gitlab.edit_merge_request_approvers(1, 5, {approver_ids: [5], approver_groups: [1]})
     #
     # @param [Integer] project(required) The ID of a project.
     # @param [Integer] merge_request(required) The IID of a merge_request.
-    # @option options [Array] :approver_ids(optional) An array of User IDs that can approve MRs
-    # @option options [Array] :approver_group_ids(optional) An array of Group IDs whose members can approve MRs
+    # @option options [Array] :approver_ids(required, nil if none) An array of User IDs that can approve MRs
+    # @option options [Array] :approver_group_ids(required, nil if none) An array of Group IDs whose members can approve MRs
     # @return [Gitlab::ObjectifiedHash] MR approval configuration information about the project
     def edit_merge_request_approvers(project, merge_request, options = {})
-      put("/projects/#{url_encode project}/merge_requests/#{merge_request}/approvals", body: options)
+      put("/projects/#{url_encode project}/merge_requests/#{merge_request}/approvers", body: options)
+    end
+
+    # Create merge request level rule
+    #
+    # @example
+    #   Gitlab.create_merge_request_level_rule(1, 2, {
+    #     name: "devs",
+    #     approvals_required: 2,
+    #     approval_project_rule_id: 99,
+    #     user_ids: [3, 4],
+    #     group_ids: [5, 6],
+    #   })
+    #
+    # Important: When approval_project_rule_id is set, the name, users and groups of project-level rule are copied.
+    # The approvals_required specified is used.
+    #
+    # @param [Integer] project(required) The ID of a project.
+    # @param [Integer] merge_request(required) The IID of a merge request.
+    # @option options [String] :name(required) The name of the approval rule
+    # @option options [Integer] :approvals_required(required) The number of required approvals for this rule
+    # @option options [Integer] :approval_project_rule_id(optional) The ID of a project-level approval rule
+    # @option options [Array] :user_ids(optional) The ids of users as approvers
+    # @option options [Array] :group_ids(optional) The ids of groups as approvers
+    # @return [Gitlab::ObjectifiedHash] New MR level approval rule
+    def create_merge_request_level_rule(project, merge_request, options = {})
+      post("/projects/#{url_encode project}/merge_requests/#{merge_request}/approval_rules", body: options)
+    end
+
+    # Get merge request level rule
+    #
+    # @example
+    #   Gitlab.merge_request_level_rule(1, 2)
+    #
+    # @param [Integer] project(required) The ID of a project.
+    # @param [Integer] merge_request(required) The IID of a merge request.
+    # @return [Gitlab::ObjectifiedHash] New MR level approval rule
+    def merge_request_level_rule(project, merge_request)
+      get("/projects/#{url_encode project}/merge_requests/#{merge_request}/approval_rules")
+    end
+
+    # Update merge request level rule
+    #
+    # @example
+    #   Gitlab.update_merge_request_level_rule(1, 2, 69, {
+    #     name: "devs",
+    #     approvals_required: 2,
+    #     user_ids: [3, 4],
+    #     group_ids: [5, 6],
+    #   })
+    #
+    # Important: Approvers and groups not in the users/groups parameters are removed
+    # Important: Updating a report_approver or code_owner rule is not allowed.
+    # These are system generated rules.
+    #
+    # @param [Integer] project(required) The ID of a project.
+    # @param [Integer] merge_request(required) The IID of a merge request.
+    # @param [Integer] appr_rule_id(required) The ID of a approval rule
+    # @option options [String] :name(required) The name of the approval rule
+    # @option options [Integer] :approvals_required(required) The number of required approvals for this rule
+    # @option options [Array] :user_ids(optional) The ids of users as approvers
+    # @option options [Array] :group_ids(optional) The ids of groups as approvers
+    # @return [Gitlab::ObjectifiedHash] Updated MR level approval rule
+    def update_merge_request_level_rule(project, merge_request, appr_rule_id, options = {})
+      put("/projects/#{url_encode project}/merge_requests/#{merge_request}/approval_rules/#{appr_rule_id}", body: options)
+    end
+
+    # Delete merge request level rule
+    #
+    # @example
+    #   Gitlab.delete_merge_request_level_rule(1, 2, 69)
+    #
+    # Important: Deleting a report_approver or code_owner rule is not allowed.
+    # These are system generated rules.
+    #
+    # @param [Integer] project(required) The ID of a project.
+    # @param [Integer] merge_request(required) The IID of a merge request.
+    # @param [Integer] appr_rule_id(required) The ID of a approval rule
+    # @return [void] This API call returns an empty response body
+    def delete_merge_request_level_rule(project, merge_request, appr_rule_id)
+      delete("/projects/#{url_encode project}/merge_requests/#{merge_request}/approval_rules/#{appr_rule_id}")
     end
 
     # Approve a merge request
@@ -102,9 +244,22 @@ class Gitlab::Client
     #
     # @param [Integer] project(required) The ID of a project.
     # @param [Integer] merge_request(required) The IID of a merge request.
+    # @option options [String] :sudo(optional) The username of the user you want to remove the approval for
     # @return [void] This API call returns an empty response body.
-    def unapprove_merge_request(project, merge_request)
-      post("/projects/#{url_encode project}/merge_requests/#{merge_request}/unapprove")
+    def unapprove_merge_request(project, merge_request, options = {})
+      post("/projects/#{url_encode project}/merge_requests/#{merge_request}/unapprove", body: options)
+    end
+
+    # Get the approval state of merge requests
+    #
+    # @example
+    #   Gitlab.merge_request_approval_state(5, 36)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a merge request.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def merge_request_approval_state(project, id)
+      get("/projects/#{url_encode project}/merge_requests/#{id}/approval_state")
     end
   end
-end
+end