gitlab-customer-support-operations_gitlab 1.0.0

data/lib/support_ops_gitlab/gitlab/markdown.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module GitLab
+  module GitLab
+    ##
+    # Defines the class Markdown within the module {SupportOps::GitLab}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Array] allowed_email_domains_list Comma-separated list of email address domains to allow group access
+    class Markdown < SupportOps::GitLab::Base
+      define_attributes :html
+      readonly_attributes :html
+
+      ##
+      # Renders text using Markdown
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param text [String] The text to render
+      # @param gfm [Boolean optional] If this should render as GitLab Flavored Markdown or not (defaults to false)
+      # @param project [String optiona] The project slug to use as a template (defaults to gitlab-org/gitlab)
+      # @see
+      #   https://docs.gitlab.com/ee/api/markdown.html#render-an-arbitrary-markdown-document
+      #   GitLab API > Markdown > Render an arbitrary Markdown document
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   markdown = SupportOps::GitLab::Markdown.convert('This is a test')
+      #   pp markdown.html
+      #   # => "<p data-sourcepos=\"1:1-1:14\">This is a test</p>"
+      def self.render(text, gfm = false, project = 'gitlab-org/gitlab')
+        data = {
+          text: text,
+          gfm: gfm,
+          project: project
+        }.to_json
+        response = client.connection.post('markdown', data)
+        body = Oj.load(response.body)
+        raise "Unable to render markdown => #{body}" unless response.status == 201
+        Markdown.new(body)
+      end
+
+      private
+    end
+  end
+end

data/lib/support_ops_gitlab/gitlab/merge_requests.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module GitLab
+  module GitLab
+    ##
+    # Defines the class MergeRequests within the module {SupportOps::GitLab}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Boolean] allow_collaboration Allow commits from members who can merge to the target branch
+    # @attr [Boolean] allow_maintainer_to_push Alias of allow_collaboration
+    # @attr [Hash] assignee Information on the first merge request assignee
+    # @attr [Array] assignees An array of users assigned to the merge request
+    # @attr [Hash] author The author of the merge request
+    # @attr [String] closed_at The timestamp the merge request was closed at
+    # @attr [Hash] closed_by The user who closed the merge request
+    # @attr [String] created_at The timestamp of when the ismerge requestsue was created
+    # @attr [String] description The merge request's description
+    # @attr [String] detailed_merge_status Detailed merge status of the merge request
+    # @attr [Boolean] discussion_locked If discussion on the merge request is locked or not
+    # @attr [Integer] downvotes The number of downvotes the merge request has
+    # @attr [Boolean] draft If the merge request is in draft mode or not
+    # @attr [Boolean] force_remove_source_branch Indicates if the project settings lead to source branch deletion after merge
+    # @attr [Integer] id The global ID or URL-encoded path of the project
+    # @attr [Integer] iid The internal ID of a project’s merge request
+    # @attr [Boolean] imported If the merge request was imported or not
+    # @attr [String] imported_from
+    # @attr [Array] labels Comma-separated list of label names
+    # @attr [String] merge_after Date after which the merge request can be merged
+    # @attr [String] merge_commit_sha SHA of the merge request commit; returns null until merged
+    # @attr [String] merged_at The timestamp the merge request was merged
+    # @attr [String] merge_status Status of the merge request; can be unchecked, checking, can_be_merged, cannot_be_merged, or cannot_be_merged_recheck. Affects the has_conflicts property
+    # @attr [String] merge_user The user who merged this merge request, the user who set it to auto-merge, or null
+    # @attr [Boolean] merge_when_pipeline_succeeds Indicates if the merge is set to merge when its pipeline succeeds
+    # @attr [Hash] milestone The milestone the merge request is attached to
+    # @attr [String] prepared_at Timestamp of when the merge request was prepared; this field populates one time, only after all the preparation steps complete, and is not updated if more changes are added
+    # @attr [Integer] project_id The ID of the project the merge request is within
+    # @attr [Hash] references Reference tags for the merge request
+    # @attr [Array] reviewers Reviewers of the merge request
+    # @attr [String] sha Diff head SHA of the merge request
+    # @attr [Boolean] should_remove_source_branch Indicates if the source branch of the merge request should be deleted after merge
+    # @attr [String] source_branch Source branch of the merge request
+    # @attr [Integer] source_project_id ID of the merge request source project
+    # @attr [Boolean] squash Indicates if squash on merge is enabled
+    # @attr [String] squash_commit_sha SHA of the squash commit; empty until merged.
+    # @attr [String] state The current state of the merge request
+    # @attr [String] target_branch Target branch of the merge request
+    # @attr [Integer] target_project_id ID of the merge request target project
+    # @attr [Hash] task_completion_status Information on the task status of a merge request
+    # @attr [Hash] time_stats Information on the time spent on the merge request
+    # @attr [String] title The mnerge request title
+    # @attr [String] updated_at The timestamp of when the merge request was last updated
+    # @attr [Integer] upvotes The number of upvotes on a merge request
+    # @attr [Integer] user_notes_count The number of notes on the merge request
+    # @attr [String] web_url The URL of the merge request
+    # @todo Populate readonly_attributes
+    # @todo A lot of things listed at https://docs.gitlab.com/api/merge_requests
+    # @todo A lot of things listed at https://docs.gitlab.com/api/merge_request_approvals/
+    # @todo A lot of things listed at https://docs.gitlab.com/api/merge_request_approval_settings/
+    # @todo A lot of things listed at https://docs.gitlab.com/api/merge_request_context_commits/
+    # @todo List issues related to the merge request => https://docs.gitlab.com/api/merge_requests/#list-issues-related-to-the-merge-request
+    class MergeRequests < SupportOps::GitLab::Base
+      # @!parse
+      #   # Subscribe to a merge request
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::GitLab::MergeRequests}
+      #   # @note This is inherited from {SupportOps::GitLab::Base#subscribe!}
+      #   # @see
+      #   #   https://docs.gitlab.com/api/merge_requests/#subscribe-to-a-merge-request
+      #   #   GitLab API > Merge requests > Subscribe to a merge request
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   existing_mr = SupportOps::GitLab::MergeRequests.get(iid: 28, project_id: 123456)
+      #   #   existing_mr.subscribe!
+      #   def subscribe!; end
+      # @!parse
+      #   # Unsubscribe to a merge request
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::GitLab::MergeRequests}
+      #   # @note This is inherited from {SupportOps::GitLab::Base#unsubscribe!}
+      #   # @see
+      #   #   https://docs.gitlab.com/api/merge_requests/#unsubscribe-to-a-merge-request
+      #   #   GitLab API > Merge requests > Unsubscribe to a merge request
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   existing_mr = SupportOps::GitLab::MergeRequests.get(iid: 28, project_id: 123456)
+      #   #   existing_mr.unsubscribe!
+      #   def unsubscribe!; end
+      # @!parse
+      #   # List notes on a merge request
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::GitLab::Base#notes}
+      #   # @see
+      #   #   https://docs.gitlab.com/api/notes/#list-all-merge-request-notes
+      #   #   GitLab API > Notes (comments) > List all merge request notes
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   existing_mr = SupportOps::GitLab::MergeRequests.get(iid: 28, project_id: 123456)
+      #   #   notes = existing_mr.notes
+      #   #   pp notes.count
+      #   #   # => 7
+      #   def notes; end
+      define_attributes :allow_collaboration, :allow_maintainer_to_push,
+                        :assignee, :assignees, :author, :closed_at, :closed_by,
+                        :created_at, :description, :detailed_merge_status,
+                        :discussion_locked, :downvotes, :draft,
+                        :force_remove_source_branch, :id, :iid, :imported,
+                        :imported_from, :labels, :merge_after,
+                        :merge_commit_sha, :merged_at, :merge_status,
+                        :merge_user, :merge_when_pipeline_succeeds, :milestone,
+                        :prepared_at, :project_id, :references, :reviewers,
+                        :sha, :should_remove_source_branch, :source_branch,
+                        :source_project_id, :squash, :squash_commit_sha, :state,
+                        :target_branch, :target_project_id,
+                        :task_completion_status, :time_stats, :title,
+                        :updated_at, :upvotes, :user_notes_count, :web_url
+      readonly_attributes :id
+
+      ##
+      # Lists issues
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param approved [String optional] Filters merge requests by their approved status; 'yes' returns only approved merge requests; 'no' returns only non-approved merge requests; requires the mr_approved_filter feature flag, disabled by default
+      #   @param approved_by_ids [Array optional] Returns the merge requests approved by all the users with the given id, up to 5 users; 'None' returns merge requests with no approvals; 'Any' returns merge requests with an approval
+      #   @param approved_by_usernames [Array optional] Returns the merge requests approved by all the users with the given username, up to 5 users; 'None' returns merge requests with no approvals; 'Any' returns merge requests with an approval
+      #   @param approver_ids [Array optional] Returns merge requests which have specified all the users with the given id as individual approvers; 'None' returns merge requests without approvers; 'Any' returns merge requests with an approver
+      #   @param assignee_id [Integer optional] Returns merge requests assigned to the given user id; 'None' returns unassigned merge requests; 'Any' returns merge requests with an assignee
+      #   @param author_id [Integer optional] Returns merge requests created by the given user id; mutually exclusive with author_username
+      #   @param author_username [String optional] Returns merge requests created by the given username; mutually exclusive with author_id
+      #   @param created_after [String optional] Returns merge requests created on or after the given time; expected in ISO 8601 format (2019-03-15T08:00:00Z)
+      #   @param created_before [String optional] Returns merge requests created on or before the given time; expected in ISO 8601 format (2019-03-15T08:00:00Z)
+      #   @param labels [String optional] Returns merge requests matching a comma-separated list of labels; 'None' lists all merge requests with no labels; 'Any' lists all merge requests with at least one label; predefined names are case-insensitive
+      #   @param merge_user_id [Integer optional] Returns merge requests merged by the user with the given user id; mutually exclusive with merge_user_username
+      #   @param merge_user_username [String optional] Returns merge requests merged by the user with the given username; mutually exclusive with merge_user_id
+      #   @param milestone [String optional] Returns merge requests for a specific milestone; 'None' returns merge requests with no milestone; 'Any' returns merge requests that have an assigned milestone
+      #   @param my_reaction_emoji [String optional] Returns merge requests reacted by the authenticated user by the given emoji; 'None' returns issues not given a reaction; 'Any' returns issues given at least one reaction
+      #   @param non_archived [Boolean optional] Returns merge requests from non archived projects only
+      #   @param order_by [String optional] Returns merge requests ordered by created_at, title or updated_at fields
+      #   @param project_id [Integer optional] The project to scope the list to (not providing it scopes it to the whole instance)
+      #   @param reviewer_id [Integer optional] Returns merge requests which have the user as a reviewer with the given user id; 'None' returns merge requests with no reviewers; 'Any' returns merge requests with any reviewer; mutually exclusive with reviewer_username
+      #   @param reviewer_username [String optional] Returns merge requests which have the user as a reviewer with the given username; 'None' returns merge requests with no reviewers; 'Any' returns merge requests with any reviewer; mutually exclusive with reviewer_id
+      #   @param scope [String optional] Returns merge requests for the given scope: created_by_me, assigned_to_me or all
+      #   @param search [String optional] Search merge requests against their title and description
+      #   @param sort [String optional] Returns merge requests sorted in asc or desc order
+      #   @param source_branch [String optional] Returns merge requests with the given source branch
+      #   @param state [String optional] Returns all merge requests (all) or just those that are opened, closed, locked, or merged
+      #   @param target_branch [String optional] Returns merge requests with the given target branch
+      #   @param updated_after [String optional] Returns merge requests updated on or after the given time; expected in ISO 8601 format (2019-03-15T08:00:00Z)
+      #   @param updated_before [String optional] Returns merge requests updated on or before the given time; expected in ISO 8601 format (2019-03-15T08:00:00Z)
+      #   @param limit [Integer optional] The limit to the number of users
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://docs.gitlab.com/api/merge_requests/#list-merge-requests
+      #   GitLab API > Merge requests > List merge requests
+      # @see SupportOps::GitLab::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.example.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   mrs = SupportOps::GitLab::MergeRequests.list(project_id: 123456)
+      #   pp mrs.count
+      #   # => 30
+      #   pp mrs.last.due_date
+      #   # => "2018-07-31"
+      def self.list(**args)
+        args[:approved] = nil unless args[:approved]
+        args[:approved_by_ids] = nil unless args[:approved_by_ids]
+        args[:approved_by_usernames] = nil unless args[:approved_by_usernames]
+        args[:approver_ids] = nil unless args[:approver_ids]
+        args[:assignee_id] = nil unless args[:assignee_id]
+        args[:author_id] = nil unless args[:author_id]
+        args[:author_username] = nil unless args[:author_username]
+        args[:created_after] = nil unless args[:created_after]
+        args[:created_before] = nil unless args[:created_before]
+        args[:labels] = nil unless args[:labels]
+        args[:merge_user_id] = nil unless args[:merge_user_id]
+        args[:merge_user_username] = nil unless args[:merge_user_username]
+        args[:milestone] = nil unless args[:milestone]
+        args[:my_reaction_emoji] = nil unless args[:my_reaction_emoji]
+        args[:non_archived] = nil unless args[:non_archived]
+        args[:order_by] = nil unless args[:order_by]
+        args[:project_id] = nil unless args[:project_id]
+        args[:reviewer_id] = nil unless args[:reviewer_id]
+        args[:reviewer_username] = nil unless args[:reviewer_username]
+        args[:scope] = nil unless args[:scope]
+        args[:search] = nil unless args[:search]
+        args[:sort] = nil unless args[:sort]
+        args[:source_branch] = nil unless args[:source_branch]
+        args[:state] = nil unless args[:state]
+        args[:target_branch] = nil unless args[:target_branch]
+        args[:updated_after] = nil unless args[:updated_after]
+        args[:updated_before] = nil unless args[:updated_before]
+        args[:limit] = 0 unless args[:limit]
+        params = ''
+        params += "approved=#{args[:approved]}&" unless args[:approved].nil?
+        params += "approved_by_ids=#{args[:approved_by_ids]}&" unless args[:approved_by_ids].nil?
+        params += "approved_by_usernames=#{args[:approved_by_usernames]}&" unless args[:approved_by_usernames].nil?
+        params += "approver_ids=#{args[:approver_ids]}&" unless args[:approver_ids].nil?
+        params += "assignee_id=#{args[:assignee_id]}&" unless args[:assignee_id].nil?
+        params += "author_id=#{args[:author_id]}&" unless args[:author_id].nil?
+        params += "author_username=#{args[:author_username]}&" unless args[:author_username].nil?
+        params += "created_after=#{args[:created_after]}&" unless args[:created_after].nil?
+        params += "created_before=#{args[:created_before]}&" unless args[:created_before].nil?
+        params += "labels=#{args[:labels]}&" unless args[:labels].nil?
+        params += "merge_user_id=#{args[:merge_user_id]}&" unless args[:merge_user_id].nil?
+        params += "merge_user_username=#{args[:merge_user_username]}&" unless args[:merge_user_username].nil?
+        params += "milestone=#{args[:milestone]}&" unless args[:milestone].nil?
+        params += "my_reaction_emoji=#{args[:my_reaction_emoji]}&" unless args[:my_reaction_emoji].nil?
+        params += "non_archived=#{args[:non_archived]}&" unless args[:non_archived].nil?
+        params += "order_by=#{args[:order_by]}&" unless args[:order_by].nil?
+        params += "project_id=#{args[:project_id]}&" unless args[:project_id].nil?
+        params += "reviewer_id=#{args[:reviewer_id]}&" unless args[:reviewer_id].nil?
+        params += "reviewer_username=#{args[:reviewer_username]}&" unless args[:reviewer_username].nil?
+        params += "scope=#{args[:scope]}&" unless args[:scope].nil?
+        params += "search=#{args[:search]}&" unless args[:search].nil?
+        params += "sort=#{args[:sort]}&" unless args[:sort].nil?
+        params += "source_branch=#{args[:source_branch]}&" unless args[:source_branch].nil?
+        params += "state=#{args[:state]}&" unless args[:state].nil?
+        params += "target_branch=#{args[:target_branch]}&" unless args[:target_branch].nil?
+        params += "updated_after=#{args[:updated_after]}&" unless args[:updated_after].nil?
+        params += "updated_before=#{args[:updated_before]}&" unless args[:updated_before].nil?
+        array = []
+        page = 1
+        base_url = if args[:project_id].nil?
+                     "merge_requests"
+                   else
+                    "projects/#{args[:project_id]}/merge_requests"
+                   end
+        loop do
+          response = client.connection.get("#{base_url}?#{params}&page=#{page}&per_page=100")
+          body = Oj.load(response.body)
+          array += body.map { |m| MergeRequests.new(m) }
+          break if args[:limit].to_i.positive? && array.count >= args[:limit].to_i
+          break if body.count < 100
+
+          page += 1
+        end
+        return array if args[:limit].to_i.zero?
+        
+        array.first(args[:limit].to_i)
+      end
+
+      ##
+      # Locates a specific merge request in the GitLab system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://docs.gitlab.com/api/merge_requests/#get-single-mr
+      #   GitLab API > Merge requests > Get single MR
+      # @see SupportOps::GitLab::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   mr = SupportOps::GitLab::MergeRequests.get(987654)
+      #   pp mr.title
+      #   # => "Awesome merge request"
+      #   pp mr.id
+      #   # => 28
+      #   pp mr.project_id
+      #   # => 123456
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   mr = SupportOps::GitLab::MergeRequests.get(iid: 28, project_id: 123456)
+      #   pp mr.title
+      #   # => "Awesome merge request"
+      #   pp mr.id
+      #   # => 987654
+      def self.get(object)
+        if object.is_a? MergeRequests
+          MergeRequests.new(id: id).find
+        elsif object.is_a? Hash
+          MergeRequests.new({ id: object[:id], iid: object[:iid], project_id: object[:project_id] }).find
+        else
+          MergeRequests.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific merge request in the GitLab system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://docs.gitlab.com/api/merge_requests/#get-single-mr
+      #   GitLab API > Merge requests > Get single MR
+      # @see SupportOps::GitLab::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   mr = SupportOps::GitLab::MergeRequests.get!(987654)
+      #   pp mr.title
+      #   # => "Awesome merge request"
+      #   pp mr.id
+      #   # => 28
+      #   pp mr.project_id
+      #   # => 123456
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   mr = SupportOps::GitLab::MergeRequests.get!(iid: 28, project_id: 123456)
+      #   pp mr.title
+      #   # => "Awesome merge request"
+      #   pp mr.id
+      #   # => 987654
+      def self.get!(object)
+        if object.is_a? MergeRequests
+          MergeRequests.new(id: id).find!
+        elsif object.is_a? Hash
+          MergeRequests.new({ id: object[:id], iid: object[:iid], project_id: object[:project_id] }).find!
+        else
+          MergeRequests.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        raise "Cannot locate merge request based off provided info" if self.id.nil? && (self.iid.nil? || self.project_id.nil?)
+        base_url = if self.id.nil?
+                     "projects/#{self.project_id}/merge_requests/#{self.iid}"
+                   else
+                    "merge_requests/#{self.id}"
+                   end
+        response = self.client.connection.get(base_url)
+        return nil if response.status != 200
+
+        Oj.load(response.body)
+      end
+
+      ##
+      # @private
+      def subscribe_record
+        response = self.client.connection.post("projects/#{self.project_id}/merge_requests/#{self.iid}/subscribe")
+        raise "Unable to subscribe to issue #{self.id} => #{body}" unless [201, 304].include? response.status
+        true
+      end
+
+      ##
+      # @private
+      def unsubscribe_record
+        response = self.client.connection.post("projects/#{self.project_id}/merge_requests/#{self.iid}/unsubscribe")
+        raise "Unable to unsubscribe to issue #{self.id} => #{body}" unless [201, 304].include? response.status
+        true
+      end
+
+      ##
+      # @private
+      def notes_record
+        Notes.list(type: 'MergeRequest', type_id: self.iid, project_id: self.project_id)
+      end
+    end
+  end
+end

data/lib/support_ops_gitlab/gitlab/milestones.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module GitLab
+  module GitLab
+    ##
+    # Defines the class Milestones within the module {SupportOps::GitLab}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Array] add_labels Comma-separated label names to add to an issue
+    # @attr [String] created_at The date the milestone was created at
+    # @attr [String] description The description of the milestone
+    # @attr [String] due_date The date the milestone is due
+    # @attr [Boolean] expired If the milestone is expired or not
+    # @attr [Integer] group_id the ID of the group the milestone is in
+    # @attr [Integer] id The ID of the group milestone
+    # @attr [Integer] iid The internal ID of the milestone
+    # @attr [String] state The current state of the milestone
+    # @attr [String] state_event The state event of the milestone, close or activate (used for updated only)
+    # @attr [String] start_date The date the milestone starts on
+    # @attr [String] title The title of the milestone
+    # @attr [String] updated_at The date the milestone was last updated
+    # @attr [String] web_url The URL of the milestone
+    # @todo Get single milestone => https://docs.gitlab.com/api/group_milestones/#get-single-milestone
+    # @todo Get all burndown chart events for a single milestone => https://docs.gitlab.com/api/group_milestones/#get-all-burndown-chart-events-for-a-single-milestone
+    # @todo Document #save! (create/update)
+    # @todo Document #delete!
+    # @todo Document issues
+    # @todo Document merge_requests
+    class Milestones < SupportOps::GitLab::Base
+      define_attributes :created_at, :description, :due_date, :expired,
+                        :group_id, :id, :iid, :state, :start_date, :title,
+                        :updated_at, :web_url
+      readonly_attributes :created_at, :expired, :group_id, :id, :iid, :state,
+                          :updated_at, :web_url
+
+      ##
+      # Lists all milestones for a group
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param group_id [Integer required] The group to look within
+      #   @param end_date [String optional] Return only milestones where
+      #     start_date <= the provided end_date
+      #   @param containing_date [String optional] Return only milestones where
+      #     start_date <= containing_date <= due_date
+      #   @param iids [Array optional] Return only the milestones having the
+      #     given iid
+      #   @param include_ancestors [xxx optional] Include milestones for all
+      #     parent groups
+      #   @param include_descendants [xxx optional] Include milestones for group
+      #     and its descendants
+      #   @param search [String optional] Return only milestones with a title or
+      #     description matching the provided string (case-insensitive)
+      #   @param search_title [xxx optional] Return only milestones with a title
+      #     matching the provided string (case-insensitive); multiple terms can
+      #     be provided, separated by an escaped space, either + or %20, and
+      #     will be ANDed together; example: 17.4+17.5 will match substrings
+      #     17.4 and 17.5 (in any order)
+      #   @param start_date [String optional] Return only milestones where
+      #     due_date >= the provided start_date
+      #   @param state [String optional] Return only active or closed milestones
+      #   @param title [String optional] Return only the milestones having the
+      #     given title (case-sensitive)
+      #   @param updated_after [String optional] Return only milestones updated
+      #     after the given datetime
+      #   @param updated_before [String optional] Return only milestones updated
+      #     before the given datetime
+      # @return [Array]
+      # @see
+      #   https://docs.gitlab.com/api/group_milestones/#list-group-milestones
+      #   GitLab API > Milestones > List group milestones
+      # @see SupportOps::GitLab::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.example.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   milestones = SupportOps::GitLab::Milestones.list(group_id: 123456)
+      #   pp milestones.count
+      #   # => 30
+      #   pp milestones.last.due_date
+      #   # => "2018-07-31"
+      def self.list(**args)
+        args[:group_id] = nil unless args[:group_id]
+        raise 'You have to provide a group_id' if args[:group_id].nil?
+        args[:group_id] = nil unless args[:group_id]
+        args[:end_date] = nil unless args[:end_date]
+        args[:containing_date] = nil unless args[:containing_date]
+        args[:iids] = nil unless args[:iids]
+        args[:include_ancestors] = nil unless args[:include_ancestors]
+        args[:include_descendants] = nil unless args[:include_descendants]
+        args[:search] = nil unless args[:search]
+        args[:search_title] = nil unless args[:search_title]
+        args[:start_date] = nil unless args[:start_date]
+        args[:state] = nil unless args[:state]
+        args[:title] = nil unless args[:title]
+        args[:updated_after] = nil unless args[:updated_after]
+        args[:updated_before] = nil unless args[:updated_before]
+        params = ''
+        params += "end_date=#{args[:end_date]}&" unless args[:end_date].nil?
+        params += "containing_date=#{args[:containing_date]}&" unless args[:containing_date].nil?
+        params += "iids=#{args[:iids]}&" unless args[:iids].nil?
+        params += "include_ancestors=#{args[:include_ancestors]}&" unless args[:include_ancestors].nil?
+        params += "include_descendants=#{args[:include_descendants]}&" unless args[:include_descendants].nil?
+        params += "search=#{args[:search]}&" unless args[:search].nil?
+        params += "search_title=#{args[:search_title]}&" unless args[:search_title].nil?
+        params += "start_date=#{args[:start_date]}&" unless args[:start_date].nil?
+        params += "state=#{args[:state]}&" unless args[:state].nil?
+        params += "title=#{args[:title]}&" unless args[:title].nil?
+        params += "updated_after=#{args[:updated_after]}&" unless args[:updated_after].nil?
+        params += "updated_before=#{args[:updated_before]}&" unless args[:updated_before].nil?
+        array = []
+        page = 1
+        loop do
+          response = client.connection.get("groups/#{args[:group_id]}/milestones?#{params}&page=#{page}&per_page=100")
+          body = Oj.load(response.body)
+          array += body.map { |m| Milestones.new(m) }
+          break if body.count < 100
+
+          page += 1
+        end
+        array
+      end
+
+      private
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("groups/#{self.group_id}/milestones", attributes_for_save.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create milestone => #{body}" if response.status != 201
+        body
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update milestone => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("groups/#{self.group_id}/milestones/#{self.iid}", attributes_for_save.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update milestone #{self.id} => #{body}" if response.status != 200
+        body
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("groups/#{self.group_id}/milestones/#{self.iid}")
+        body = Oj.load(response.body)
+        raise "Failed to delete milestone #{self.id} => #{body}" unless response.status == 204
+        true
+      end
+
+      ##
+      # @private
+      def issues_record
+        array = []
+        page = 1
+        loop do
+          response = client.connection.get("groups/#{self.group_id}/milestones/#{self.id}/issues?page=#{page}&per_page=100")
+          body = Oj.load(response.body)
+          array += body.map { |i| Issues.new(i) }
+          break if body.count < 100
+
+          page += 1
+        end
+        array
+      end
+
+      ##
+      # @private
+      def merge_requests_record
+        array = []
+        page = 1
+        loop do
+          response = self.client.connection.get("groups/#{self.group_id}/milestones/#{self.id}/merge_requests?page=#{page}&per_page=100")
+          body = Oj.load(response.body)
+          array += body.map { |m| MergeRequests.new(m) }
+          break if body.count < 100
+
+          page += 1
+        end
+        array
+      end
+    end
+  end
+end