gitlab 3.0.0 → 4.0.0

data/lib/gitlab/client/repositories.rb

@@ -1,65 +1,59 @@
 class Gitlab::Client
   # Defines methods related to repositories.
+  # @see https://docs.gitlab.com/ce/api/repositories.html
   module Repositories
-    # Gets a list of project repository tags.
+    # Get file tree project (root level).
     #
     # @example
-    #   Gitlab.tags(42)
+    #   Gitlab.tree(42)
+    #   Gitlab.tree(42, { path: 'Gemfile' })
     #
-    # @param  [Integer] project The ID of a project.
+    # @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/#{project}/repository/tags", :query => options)
+    # @option options [String] :path The path inside repository.
+    # @option options [String] :ref_name The name of a repository branch or tag.
+    # @return [Gitlab::ObjectifiedHash]
+    def tree(project, options={})
+      get("/projects/#{url_encode project}/repository/tree", query: options)
     end
-    alias_method :repo_tags, :tags
+    alias_method :repo_tree, :tree
 
-    # Gets a list of project repositiory branches.
+    # Get project repository archive
     #
     # @example
-    #   Gitlab.branches(42)
-    #
-    # @param  [Integer] project The ID 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/#{project}/repository/branches", :query => options)
+    #   Gitlab.repo_archive(42)
+    #   Gitlab.repo_archive(42, 'deadbeef')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] ref The commit sha, branch, or tag to download.
+    # @return [Gitlab::FileResponse]
+    def repo_archive(project, ref = 'master')
+      get("/projects/#{url_encode project}/repository/archive",
+          format: nil,
+          headers: { Accept: 'application/octet-stream' },
+          query: { sha: ref },
+          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_method :repo_branches, :branches
 
-    # Gets information about a repository branch.
+    # Compares branches, tags or commits.
     #
     # @example
-    #   Gitlab.branch(3, 'api')
-    #   Gitlab.repo_branch(5, 'master')
+    #   Gitlab.compare(42, 'master', 'feature/branch')
+    #   Gitlab.repo_compare(42, 'master', 'feature/branch')
     #
-    # @param  [Integer] project The ID of a project.
-    # @param  [String] branch The name of the branch.
+    # @param [Integer] project The ID of a project.
+    # @param [String] from The commit SHA or branch name of from branch.
+    # @param [String] to The commit SHA or branch name of to branch.
     # @return [Gitlab::ObjectifiedHash]
-    def branch(project, branch)
-      get("/projects/#{project}/repository/branches/#{branch}")
-    end
-    alias_method :repo_branch, :branch
-
-    # Gets a list of project commits.
-    #
-    # @example
-    #   Gitlab.commits('viking')
-    #   Gitlab.repo_commits('gitlab', :ref_name => 'api')
-    #
-    # @param  [Integer] project The ID 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/#{project}/repository/commits", :query => options)
+    def compare(project, from, to)
+      get("/projects/#{url_encode project}/repository/compare", query: { from: from, to: to })
     end
-    alias_method :repo_commits, :commits
+    alias_method :repo_compare, :compare
   end
 end

data/lib/gitlab/client/repository_files.rb

@@ -0,0 +1,107 @@
+require 'base64'
+
+class Gitlab::Client
+  # Defines methods related to repository files.
+  # @see https://docs.gitlab.com/ce/api/repository_files.html
+  module RepositoryFiles
+    # Get the contents of a file
+    #
+    # @example
+    #   Gitlab.file_contents(42, 'Gemfile')
+    #   Gitlab.repo_file_contents(3, 'Gemfile', 'ed899a2f4b50b4370feeea94676502b42383c746')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] filepath The relative path of the file in the repository
+    # @param  [String] ref The name of a repository branch or tag or if not given the default branch.
+    # @return [String]
+    def file_contents(project, filepath, ref='master')
+      ref = URI.encode(ref, /\W/)
+      get "/projects/#{url_encode project}/repository/files/#{url_encode filepath}/raw",
+          query: { ref: ref},
+          format: nil,
+          headers: { Accept: 'text/plain' },
+          parser: ::Gitlab::Request::Parser
+    end
+    alias_method :repo_file_contents, :file_contents
+
+    # Gets a repository file.
+    #
+    # @example
+    #   Gitlab.get_file(42, "README.md", "master")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] file_path The full path of the file.
+    # @param  [String] ref The name of branch, tag or commit.
+    # @return [Gitlab::ObjectifiedHash]
+    def get_file(project, file_path, ref)
+      get("/projects/#{url_encode project}/repository/files/#{url_encode file_path}", query: {
+            ref: ref
+          })
+    end
+
+    # Creates a new repository file.
+    #
+    # @example
+    #   Gitlab.create_file(42, "path", "branch", "content", "commit message")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] full path to new file.
+    # @param  [String] the name of the branch.
+    # @param  [String] file content.
+    # @param  [String] commit message.
+    # @return [Gitlab::ObjectifiedHash]
+    def create_file(project, path, branch, content, commit_message)
+      post("/projects/#{url_encode project}/repository/files", body: {
+        file_path: path,
+        branch_name: branch,
+        commit_message: commit_message
+      }.merge(encoded_content_attributes(content)))
+    end
+
+    # Edits an existing repository file.
+    #
+    # @example
+    #   Gitlab.edit_file(42, "path", "branch", "content", "commit message")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] full path to new file.
+    # @param  [String] the name of the branch.
+    # @param  [String] file content.
+    # @param  [String] commit message.
+    # @return [Gitlab::ObjectifiedHash]
+    def edit_file(project, path, branch, content, commit_message)
+      put("/projects/#{url_encode project}/repository/files", body: {
+        file_path: path,
+        branch_name: branch,
+        commit_message: commit_message
+      }.merge(encoded_content_attributes(content)))
+    end
+
+    # Removes an existing repository file.
+    #
+    # @example
+    #   Gitlab.remove_file(42, "path", "branch", "commit message")
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] full path to new file.
+    # @param  [String] the name of the branch.
+    # @param  [String] commit message.
+    # @return [Gitlab::ObjectifiedHash]
+    def remove_file(project, path, branch, commit_message)
+      delete("/projects/#{url_encode project}/repository/files", body: {
+               file_path: path,
+               branch_name: branch,
+               commit_message: commit_message
+             })
+    end
+
+    private
+
+    def encoded_content_attributes(content)
+      {
+        encoding: 'base64',
+        content: Base64.encode64(content)
+      }
+    end
+  end
+end

data/lib/gitlab/client/runners.rb

@@ -0,0 +1,115 @@
+class Gitlab::Client
+  # Defines methods related to runners.
+  # @see https://docs.gitlab.com/ce/api/runners.html
+  module Runners
+
+    # Get a list of specific runners available to the user.
+    # @see https://docs.gitlab.com/ce/api/runners.html#list-owned-runners
+    #
+    # @example
+    #   Gitlab.runners
+    #   Gitlab.runners(:active)
+    #   Gitlab.runners(:paused)
+    #
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :scope The scope of specific runners to show, one of: active, paused, online; showing all runners if none provided
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def runners(options = {})
+      get("/runners", query: options)
+    end
+
+    # Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with admin privileges.
+    # @see https://docs.gitlab.com/ce/api/runners.html#list-all-runners
+    #
+    # @example
+    #   Gitlab.all_runners
+    #
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :scope The scope of runners to show, one of: specific, shared, active, paused, online; showing all runners if none provided
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def all_runners(options = {})
+      get("/runners/all", query: options)
+    end
+
+    # Get details of a runner..
+    # @see https://docs.gitlab.com/ce/api/runners.html#get-runners-details
+    #
+    # @example
+    #   Gitlab.runner(42)
+    #
+    # @param  [Integer, String] id The ID of a runner
+    # @return <Gitlab::ObjectifiedHash>
+    def runner(id)
+      get("/runners/#{id}")
+    end
+
+    # Update details of a runner.
+    # @see https://docs.gitlab.com/ce/api/runners.html#update-runners-details
+    #
+    # @example
+    #   Gitlab.update_runner(42, { description: 'Awesome runner' })
+    #   Gitlab.update_runner(42, { active: false })
+    #   Gitlab.update_runner(42, { tag_list: [ 'awesome', 'runner' ] })
+    #
+    # @param  [Integer, String] id The ID of a runner
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :active The state of a runner; can be set to true or false.
+    # @option options [String] :tag_list The list of tags for a runner; put array of tags, that should be finally assigned to a runner
+    # @return <Gitlab::ObjectifiedHash>
+    def update_runner(id, options={})
+      put("/runners/#{id}", query: options)
+    end
+
+    # Remove a runner.
+    # @see https://docs.gitlab.com/ce/api/runners.html#remove-a-runner
+    #
+    # @example
+    #   Gitlab.delete_runner(42)
+    #
+    # @param  [Integer, String] id The ID of a runner
+    # @return <Gitlab::ObjectifiedHash>
+    def delete_runner(id)
+      delete("/runners/#{id}")
+    end
+
+    # List all runners (specific and shared) available in the project. Shared runners are listed if at least one shared runner is defined and shared runners usage is enabled in the project's settings.
+    # @see https://docs.gitlab.com/ce/api/runners.html#list-projects-runners
+    #
+    # @example
+    #   Gitlab.project_runners(42)
+    #
+    # @param  [Integer, String] id The ID or name of a project.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def project_runners(project_id)
+      get("/projects/#{url_encode project_id}/runners")
+    end
+
+    # Enable an available specific runner in the project.
+    # @see https://docs.gitlab.com/ce/api/runners.html#enable-a-runner-in-project
+    #
+    # @example
+    #   Gitlab.project_enable_runner(2, 42)
+    #
+    # @param  [Integer, String] id The ID or name of a project.
+    # @param  [Integer, String] id The ID of a runner.
+    # @return <Gitlab::ObjectifiedHash>
+    def project_enable_runner(project_id, id)
+      body = { runner_id: id }
+      post("/projects/#{url_encode project_id}/runners", body: body)
+    end
+
+    # Disable a specific runner from the project. It works only if the project isn't the only project associated with the specified runner.
+    # @see https://docs.gitlab.com/ce/api/runners.html#disable-a-runner-from-project
+    #
+    # @example
+    #   Gitlab.project_disable_runner(2, 42)
+    #
+    # @param  [Integer, String] id The ID or name of a project.
+    # @param  [Integer, String] runner_id The ID of a runner.
+    # @return <Gitlab::ObjectifiedHash>
+    def project_disable_runner(id, runner_id)
+      delete("/projects/#{url_encode id}/runners/#{runner_id}")
+    end
+
+  end
+end

data/lib/gitlab/client/services.rb

@@ -0,0 +1,50 @@
+class Gitlab::Client
+  # Third party services connected to a project.
+  # @see https://docs.gitlab.com/ce/api/services.html
+  module Services
+    # Create/Edit service
+    # Full service params documentation: https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/services.md
+    #
+    # @example
+    #   Gitlab.change_service(42, :redmine, { new_issue_url: 'https://example.com/projects/test_project/issues/new',
+    #                                         project_url: 'https://example.com/projects/test_project/issues',
+    #                                         issues_url: 'https://example.com/issues/:id' })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] service A service code name.
+    # @param  [Hash] params A service parameters.
+    # @return [Boolean]
+    def change_service(project, service, params)
+      put("/projects/#{url_encode project}/services/#{correct_service_name(service)}", body: params)
+    end
+
+    # Delete service
+    #
+    # @example
+    #   Gitlab.delete_service(42, :redmine)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] service A service code name.
+    # @return [Boolean]
+    def delete_service(project, service)
+      delete("/projects/#{url_encode project}/services/#{correct_service_name(service)}")
+    end
+
+    # Get service
+    #
+    # @example
+    #   Gitlab.service(42, :redmine)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] service A service code name.
+    # @return [Gitlab::ObjectifiedHash]
+    def service(project, service)
+      get("/projects/#{url_encode project}/services/#{correct_service_name(service)}")
+    end
+
+    private
+    def correct_service_name(service)
+      service.to_s.gsub('_', '-')
+    end
+  end
+end

data/lib/gitlab/client/snippets.rb

@@ -1,18 +1,19 @@
 class Gitlab::Client
   # Defines methods related to snippets.
+  # @see https://docs.gitlab.com/ce/api/project_snippets.html
   module Snippets
     # Gets a list of project's snippets.
     #
     # @example
     #   Gitlab.snippets(42)
     #
-    # @param  [Integer] project The ID of a project.
+    # @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 [Gitlab::ObjectifiedHash]
     def snippets(project, options={})
-      get("/projects/#{project}/snippets", :query => options)
+      get("/projects/#{url_encode project}/snippets", query: options)
     end
 
     # Gets information about a snippet.
@@ -20,19 +21,19 @@ class Gitlab::Client
     # @example
     #   Gitlab.snippet(2, 14)
     #
-    # @param  [Integer] project The ID of a project.
+    # @param  [Integer, String] project The ID or name of a project.
     # @param  [Integer] id The ID of a snippet.
     # @return [Gitlab::ObjectifiedHash]
     def snippet(project, id)
-      get("/projects/#{project}/snippets/#{id}")
+      get("/projects/#{url_encode project}/snippets/#{id}")
     end
 
     # Creates a new snippet.
     #
     # @example
-    #   Gitlab.create_snippet(42, {:title => 'REST', :file_name => 'api.rb', :code => 'some code'})
+    #   Gitlab.create_snippet(42, { title: 'REST', file_name: 'api.rb', code: 'some code' })
     #
-    # @param  [Integer] project The ID of a project.
+    # @param  [Integer, String] project The ID or name of a project.
     # @param  [Hash] options A customizable set of options.
     # @option options [String] :title (required) The title of a snippet.
     # @option options [String] :file_name (required) The name of a snippet file.
@@ -40,16 +41,15 @@ class Gitlab::Client
     # @option options [String] :lifetime (optional) The expiration date of a snippet.
     # @return [Gitlab::ObjectifiedHash] Information about created snippet.
     def create_snippet(project, options={})
-      check_attributes!(options, [:title, :file_name, :code])
-      post("/projects/#{project}/snippets", :body => options)
+      post("/projects/#{url_encode project}/snippets", body: options)
     end
 
     # Updates a snippet.
     #
     # @example
-    #   Gitlab.edit_snippet(42, 34, :file_name => 'README.txt')
+    #   Gitlab.edit_snippet(42, 34, { file_name: 'README.txt' })
     #
-    # @param  [Integer] project The ID of a project.
+    # @param  [Integer, String] project The ID or name of a project.
     # @param  [Integer] id The ID of a snippet.
     # @param  [Hash] options A customizable set of options.
     # @option options [String] :title The title of a snippet.
@@ -58,7 +58,7 @@ class Gitlab::Client
     # @option options [String] :lifetime The expiration date of a snippet.
     # @return [Gitlab::ObjectifiedHash] Information about updated snippet.
     def edit_snippet(project, id, options={})
-      put("/projects/#{project}/snippets/#{id}", :body => options)
+      put("/projects/#{url_encode project}/snippets/#{id}", body: options)
     end
 
     # Deletes a snippet.
@@ -66,21 +66,26 @@ class Gitlab::Client
     # @example
     #   Gitlab.delete_snippet(2, 14)
     #
-    # @param  [Integer] project The ID of a project.
+    # @param  [Integer, String] project The ID or name of a project.
     # @param  [Integer] id The ID of a snippet.
     # @return [Gitlab::ObjectifiedHash] Information about deleted snippet.
     def delete_snippet(project, id)
-      delete("/projects/#{project}/snippets/#{id}")
+      delete("/projects/#{url_encode project}/snippets/#{id}")
     end
 
-    private
-
-    def check_attributes!(options, attrs)
-      attrs.each do |attr|
-        unless options.has_key?(attr) || options.has_key?(attr.to_s)
-          raise Gitlab::Error::MissingAttributes.new("Missing '#{attr}' parameter")
-        end
-      end
+    # Returns raw project snippet content as plain text.
+    #
+    # @example
+    #   Gitlab.snippet_content(2, 14)
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Integer] id The ID of a snippet.
+    # @return [Gitlab::ObjectifiedHash] Information about deleted snippet.
+    def snippet_content(project, id)
+      get("/projects/#{url_encode project}/snippets/#{id}/raw",
+          format: nil,
+          headers: { Accept: 'text/plain' },
+          parser: ::Gitlab::Request::Parser)
     end
   end
 end