gitlab 3.0.0 → 4.0.0

data/lib/gitlab/client.rb

@@ -1,16 +1,52 @@
 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', __FILE__)].each { |f| require f }
 
-    include Users
+    include Branches
+    include Builds
+    include BuildTriggers
+    include BuildVariables
+    include Commits
+    include Groups
     include Issues
-    include Notes
+    include Labels
+    include MergeRequests
     include Milestones
-    include Snippets
+    include Namespaces
+    include Notes
+    include Pipelines
     include Projects
     include Repositories
-    include MergeRequests
-    include Groups
+    include RepositoryFiles
+    include Runners
+    include Services
+    include Snippets
+    include SystemHooks
+    include Tags
+    include Users
+
+    # 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
+    end
+
+    def url_encode(s)
+      ERB::Util.url_encode(s)
+    end
+
+    private
+
+    def only_show_last_four_chars(token)
+      "#{'*'*(token.size - 4)}#{token[-4..-1]}"
+    end
   end
 end

data/lib/gitlab/client/branches.rb

@@ -0,0 +1,91 @@
+class Gitlab::Client
+  # Defines methods related to repositories.
+  # @see https://docs.gitlab.com/ce/api/branches.html
+  module Branches
+    # Gets a list of project repositiory branches.
+    #
+    # @example
+    #   Gitlab.branches(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 branches(project, options={})
+      get("/projects/#{url_encode project}/repository/branches", query: options)
+    end
+    alias_method :repo_branches, :branches
+
+    # Gets information about a repository branch.
+    #
+    # @example
+    #   Gitlab.branch(3, 'api')
+    #   Gitlab.repo_branch(5, 'master')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] branch The name of the branch.
+    # @return [Gitlab::ObjectifiedHash]
+    def branch(project, branch)
+      get("/projects/#{url_encode project}/repository/branches/#{branch}")
+    end
+    alias_method :repo_branch, :branch
+
+    # Protects a repository branch.
+    #
+    # @example
+    #   Gitlab.protect_branch(3, 'api')
+    #   Gitlab.repo_protect_branch(5, 'master')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] branch The name of the branch.
+    # @return [Gitlab::ObjectifiedHash]
+    def protect_branch(project, branch)
+      put("/projects/#{url_encode project}/repository/branches/#{branch}/protect")
+    end
+    alias_method :repo_protect_branch, :protect_branch
+
+    # Unprotects a repository branch.
+    #
+    # @example
+    #   Gitlab.unprotect_branch(3, 'api')
+    #   Gitlab.repo_unprotect_branch(5, 'master')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] branch The name of the branch.
+    # @return [Gitlab::ObjectifiedHash]
+    def unprotect_branch(project, branch)
+      put("/projects/#{url_encode project}/repository/branches/#{branch}/unprotect")
+    end
+    alias_method :repo_unprotect_branch, :unprotect_branch
+
+    # Creates a repository branch.  Requires Gitlab >= 6.8.x
+    #
+    # @example
+    #   Gitlab.create_branch(3, 'api')
+    #   Gitlab.repo_create_branch(5, 'master')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] branch The name of the new branch.
+    # @param  [String] ref Create branch from commit sha or existing branch
+    # @return [Gitlab::ObjectifiedHash]
+    def create_branch(project, branch, ref)
+      post("/projects/#{url_encode project}/repository/branches", body: { branch_name: branch, ref: ref })
+    end
+    alias_method :repo_create_branch, :create_branch
+
+    # Deletes a repository branch.  Requires Gitlab >= 6.8.x
+    #
+    # @example
+    #   Gitlab.delete_branch(3, 'api')
+    #   Gitlab.repo_delete_branch(5, 'master')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] branch The name of the branch to delete
+    # @return [Gitlab::ObjectifiedHash]
+    def delete_branch(project, branch)
+      delete("/projects/#{url_encode project}/repository/branches/#{branch}")
+    end
+    alias_method :repo_delete_branch, :delete_branch
+  end
+end

data/lib/gitlab/client/build_triggers.rb

@@ -0,0 +1,51 @@
+class Gitlab::Client
+  # Defines methods related to builds.
+  # @see https://docs.gitlab.com/ce/api/build_triggers.html
+  module BuildTriggers
+    # Gets a list of the project's build triggers
+    #
+    # @example
+    #   Gitlab.triggers(5)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @return [Array<Gitlab::ObjectifiedHash>] The list of triggers.
+    def triggers(project)
+      get("/projects/#{url_encode project}/triggers")
+    end
+
+    # Gets details of project's build trigger.
+    #
+    # @example
+    #   Gitlab.trigger(5, '7b9148c158980bbd9bcea92c17522d')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] token The token of a trigger.
+    # @return [Gitlab::ObjectifiedHash] The trigger.
+    def trigger(project, token)
+      get("/projects/#{url_encode project}/triggers/#{token}")
+    end
+
+    # Create a build trigger for a project.
+    #
+    # @example
+    #   Gitlab.create_trigger(5)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @return [Gitlab::ObjectifiedHash] The trigger.
+    def create_trigger(project)
+      post("/projects/#{url_encode project}/triggers")
+    end
+
+    # Remove a project's build trigger.
+    #
+    # @example
+    #   Gitlab.remove_trigger(5, '7b9148c158980bbd9bcea92c17522d')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] token The token of a trigger.
+    # @return [Gitlab::ObjectifiedHash] The trigger.
+    def remove_trigger(project, token)
+      delete("/projects/#{url_encode project}/triggers/#{token}")
+    end
+  end
+end

data/lib/gitlab/client/build_variables.rb

@@ -0,0 +1,66 @@
+class Gitlab::Client
+  # Defines methods related to builds.
+  # @see https://docs.gitlab.com/ce/api/build_variables.html
+  module BuildVariables
+    # Gets a list of the project's build variables
+    #
+    # @example
+    #   Gitlab.variables(5)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @return [Array<Gitlab::ObjectifiedHash>] The list of variables.
+    def variables(project)
+      get("/projects/#{url_encode project}/variables")
+    end
+
+    # Gets details of a project's specific build variable.
+    #
+    # @example
+    #   Gitlab.build(5, "TEST_VARIABLE_1")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] key The key of a variable.
+    # @return [Gitlab::ObjectifiedHash] The variable.
+    def variable(project, key)
+      get("/projects/#{url_encode project}/variables/#{key}")
+    end
+
+    # Create a build variable for a project.
+    #
+    # @example
+    #   Gitlab.create_variable(5, "NEW_VARIABLE", "new value")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] key The key of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9` and `_` are allowed
+    # @param  [String] value The value of a variable
+    # @return [Gitlab::ObjectifiedHash] The variable.
+    def create_variable(project, key, value)
+      post("/projects/#{url_encode project}/variables", body: { key: key, value: value })
+    end
+
+    # Update a project's build variable.
+    #
+    # @example
+    #   Gitlab.create_variable(5, "NEW_VARIABLE", "updated value")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] key The key of a variable
+    # @param  [String] value The value of a variable
+    # @return [Gitlab::ObjectifiedHash] The variable.
+    def update_variable(project, key, value)
+      put("/projects/#{url_encode project}/variables/#{key}", body: { value: value })
+    end
+
+    # Remove a project's build variable.
+    #
+    # @example
+    #   Gitlab.remove_variable(5, "VARIABLE_1")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] key The key of a variable.
+    # @return [Gitlab::ObjectifiedHash] The variable.
+    def remove_variable(project, key)
+      delete("/projects/#{url_encode project}/variables/#{key}")
+    end
+  end
+end

data/lib/gitlab/client/builds.rb

@@ -0,0 +1,106 @@
+class Gitlab::Client
+  # Defines methods related to builds.
+  # @see https://docs.gitlab.com/ce/api/builds.html
+  module Builds
+    # Gets a list of project builds.
+    #
+    # @example
+    #   Gitlab.builds(5)
+    #   Gitlab.builds(5, { per_page: 10, page:  2 })
+    #
+    # @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.
+    # @param  [Integer, String] project The ID or name of a project.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def builds(project, options={})
+      get("/projects/#{url_encode project}/builds", query: options)
+    end
+
+    # Gets a single build.
+    #
+    # @example
+    #   Gitlab.build(5, 36)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a build.
+    # @return [Gitlab::ObjectifiedHash]
+    def build(project, id)
+      get("/projects/#{url_encode project}/builds/#{id}")
+    end
+
+    # Gets build artifacts.
+    #
+    # @example
+    #   Gitlab.build_artifacts(1, 8)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a build.
+    # @return [Gitlab::FileResponse]
+    def build_artifacts(project, id)
+      get("/projects/#{url_encode project}/builds/#{id}/artifacts",
+           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
+
+    # Gets a list of builds for specific commit in a project.
+    #
+    # @example
+    #   Gitlab.commit_builds(5, 'asdf')
+    #   Gitlab.commit_builds(5, 'asdf', { per_page: 10, page: 2 })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] sha The SHA checksum of a commit.
+    # @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>] The list of builds.
+    def commit_builds(project, sha, options={})
+      get("/projects/#{url_encode project}/repository/commits/#{sha}/builds", query: options)
+    end
+
+    # Cancels a build.
+    #
+    # @example
+    #   Gitlab.build_cancel(5, 1)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a build.
+    # @return [Gitlab::ObjectifiedHash] The builds changes.
+    def build_cancel(project, id)
+      post("/projects/#{url_encode project}/builds/#{id}/cancel")
+    end
+
+    # Retry a build.
+    #
+    # @example
+    #   Gitlab.build_retry(5, 1)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a build.
+    # @return [Array<Gitlab::ObjectifiedHash>] The builds changes.
+    def build_retry(project, id)
+      post("/projects/#{url_encode project}/builds/#{id}/retry")
+    end
+
+    # Erase a single build of a project (remove build artifacts and a build trace)
+    #
+    # @example
+    #   Gitlab.build_erase(5, 1)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a build.
+    # @return [Gitlab::ObjectifiedHash] The build's changes.
+    def build_erase(project, id)
+      post("/projects/#{url_encode project}/builds/#{id}/erase")
+    end
+  end
+end

data/lib/gitlab/client/commits.rb

@@ -0,0 +1,146 @@
+class Gitlab::Client
+  # Defines methods related to repository commits.
+  # @see https://docs.gitlab.com/ce/api/commits.html
+  module Commits
+    # Gets a list of project commits.
+    #
+    # @example
+    #   Gitlab.commits('viking')
+    #   Gitlab.repo_commits('gitlab', { ref_name: 'api' })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :ref_name The branch or tag name of a project repository.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def commits(project, options={})
+      get("/projects/#{url_encode project}/repository/commits", query: options)
+    end
+    alias_method :repo_commits, :commits
+
+    # Gets a specific commit identified by the commit hash or name of a branch or tag.
+    #
+    # @example
+    #   Gitlab.commit(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6')
+    #   Gitlab.repo_commit(3, 'ed899a2f4b50b4370feeea94676502b42383c746')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] sha The commit hash or name of a repository branch or tag
+    # @return [Gitlab::ObjectifiedHash]
+    def commit(project, sha)
+      get("/projects/#{url_encode project}/repository/commits/#{sha}")
+    end
+    alias_method :repo_commit, :commit
+
+    # Get the diff of a commit in a project.
+    #
+    # @example
+    #   Gitlab.commit_diff(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6')
+    #   Gitlab.repo_commit_diff(3, 'ed899a2f4b50b4370feeea94676502b42383c746')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] sha The name of a repository branch or tag or if not given the default branch.
+    # @return [Gitlab::ObjectifiedHash]
+    def commit_diff(project, sha)
+      get("/projects/#{url_encode project}/repository/commits/#{sha}/diff")
+    end
+    alias_method :repo_commit_diff, :commit_diff
+
+    # Gets a list of comments for a commit.
+    #
+    # @example
+    #   Gitlab.commit_comments(5, 'c9f9662a9b1116c838b523ed64c6abdb4aae4b8b')
+    #
+    # @param [Integer] project The ID of a project.
+    # @param [String] sha The commit hash or name of a repository branch or tag.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def commit_comments(project, commit, options={})
+      get("/projects/#{url_encode project}/repository/commits/#{commit}/comments", query: options)
+    end
+    alias_method :repo_commit_comments, :commit_comments
+
+    # Creates a new comment for a commit.
+    #
+    # @example
+    #   Gitlab.create_commit_comment(5, 'c9f9662a9b1116c838b523ed64c6abdb4aae4b8b', 'Nice work on this commit!')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] sha The commit hash or name of a repository branch or tag.
+    # @param  [String] note The text of a comment.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :path The file path.
+    # @option options [Integer] :line The line number.
+    # @option options [String] :line_type The line type (new or old).
+    # @return [Gitlab::ObjectifiedHash] Information about created comment.
+    def create_commit_comment(project, commit, note, options={})
+      post("/projects/#{url_encode project}/repository/commits/#{commit}/comments", body: options.merge(note: note))
+    end
+    alias_method :repo_create_commit_comment, :create_commit_comment
+
+    # Get the status of a commit
+    #
+    # @example
+    #   Gitlab.commit_status(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6')
+    #   Gitlab.commit_status(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6', { name: 'jenkins' })
+    #   Gitlab.commit_status(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6', { name: 'jenkins', all: true })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] sha The commit hash
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :ref Filter by ref name, it can be branch or tag
+    # @option options [String] :stage Filter by stage
+    # @option options [String] :name Filter by status name, eg. jenkins
+    # @option options [Boolean] :all The flag to return all statuses, not only latest ones
+    def commit_status(id, sha, options={})
+      get("/projects/#{id}/repository/commits/#{sha}/statuses", query: options)
+    end
+    alias_method :repo_commit_status, :commit_status
+
+    # Adds or updates a status of a commit.
+    #
+    # @example
+    #   Gitlab.update_commit_status(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6', 'success')
+    #   Gitlab.update_commit_status(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6', 'failed', { name: 'jenkins' })
+    #   Gitlab.update_commit_status(42, '6104942438c14ec7bd21c6cd5bd995272b3faff6', 'canceled', { name: 'jenkins', target_url: 'http://example.com/builds/1' })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] sha The commit hash
+    # @param  [String] state of the status. Can be: pending, running, success, failed, canceled
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :ref The ref (branch or tag) to which the status refers
+    # @option options [String] :name Filter by status name, eg. jenkins
+    # @option options [String] :target_url The target URL to associate with this status
+    def update_commit_status(id, sha, state, options={})
+      post("/projects/#{id}/statuses/#{sha}", query: options.merge(state: state))
+    end
+    alias_method :repo_update_commit_status, :update_commit_status
+
+    # Creates a single commit with one or more changes
+    #
+    # @see https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
+    # Introduced in Gitlab 8.13
+    #
+    # @example
+    # Gitlab.create_commit(2726132, 'master', 'refactors everything', [{action: 'create', file_path: '/foo.txt', content: 'bar'}])
+    # Gitlab.create_commit(2726132, 'master', 'refactors everything', [{action: 'delete', file_path: '/foo.txt'}])
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param [String] branch the branch name you wish to commit to
+    # @param [String] message the commit message
+    # @param [Array[Hash]] An array of action hashes to commit as a batch. See the next table for what attributes it can take.
+    # @option options [String] :author_email the email address of the author
+    # @option options [String] :author_name the name of the author
+    # @return [Gitlab::ObjectifiedHash] hash of commit related data
+    def create_commit(project, branch, message, actions, options={})
+      payload = {
+          branch_name: branch,
+          commit_message: message,
+          actions: actions,
+      }.merge(options)
+      post("/projects/#{url_encode project}/repository/commits", query: payload)
+    end
+  end
+end