gitlab-triage 1.57.0 → 1.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 624c4d1977031933b3f310f7ae5c82778ac62bcda0f86a0c2c4a375504b6e715
-  data.tar.gz: 9545979a57eea0ff733995ac553271ad310c2c2710ac4fe78645daff962449b5
+  metadata.gz: 8a6d5407a6cccbf8711ab5d9e6cfd060165831e32880681257a6d12ed2290df3
+  data.tar.gz: 30aca49b70d3c65f56fcb5cd34275d6aad83aea62f54b683d1196af54c8c312a
 SHA512:
-  metadata.gz: 1721670e0285a0d0fffd8cb076becb239e859267d1da55f4819526f39128dec62e884251f6ae28e9d1550eeca2eb29f8c5b08c1c8d6e16b480f22254bf20016c
-  data.tar.gz: 7b233404c63d41de48dfadf6e7fdacadb6412c47fe00562d417626534ef21b5dd8c4c14340b1d46f27bad1c5c2e58378d55e80b6aac5c8e0f25f12d2075c3515
+  metadata.gz: ba6a0e711a7c06f6c99f1af0471d68cd7c335dbfd53d5456f571414e79ce6c9454f6e9df0379ff89fdb57f155f8947cde33ce164ee19766f75c75f89cc8df345
+  data.tar.gz: da23490510ce31cf2abb2ece62189c9d464421ef15be0b07a44245fce4619afb0df52216674759a9dd07c2d07a7284b00fde9ef66e252c5e1a9e43fb81635c81

data/.gitlab/merge_request_templates/Default.md

@@ -8,4 +8,8 @@ that reviewers can understand your intent. Keeping the description updated is
 especially important if they didn't participate in the discussion.
 -->
 
+## Checklist
+
+- [ ] User-visible commits have a `Changelog:` trailer (see [CONTRIBUTING.md](https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage/-/blob/master/CONTRIBUTING.md#changelog)).
+
 <!-- template sourced from https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage/-/blob/master/.gitlab/merge_request_templates/Default.md -->

data/CONTRIBUTING.md

@@ -29,3 +29,25 @@ git checkout my_branch
 bundle install --path vendor/bundle
 bundle exec rake spec
 ```
+
+## Changelog
+
+Release notes are generated from `Changelog:` commit trailers using the
+[GitLab changelog API](https://docs.gitlab.com/ee/api/repositories.html#generate-changelog-data).
+The available categories are listed in `.gitlab/changelog_config.yml`:
+`added`, `fixed`, `changed`, `deprecated`, `removed`, `security`,
+`performance`, and `other`.
+
+- Add a trailer to every commit with a user-visible change
+- Dependency updates, documentation-only changes, and internal refactors
+  don't need one
+- Use `changed` when a change makes previously-loading policies fail
+
+```
+Add remove_labels action to the work_items policy type
+
+The work_items type only supported labels and assignees, so
+remove_labels was rejected at load time.
+
+Changelog: added
+```

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gitlab-triage (1.57.0)
+    gitlab-triage (1.58.0)
       activesupport (>= 5.1)
       globalid (~> 1.0, >= 1.0.1)
       graphql (>= 2.4.13, < 2.7.0)

data/README.md

@@ -188,15 +188,61 @@ resource_rules:
 
 #### Supported conditions
 
+Sent to the Work Items REST API:
+
 - `type` - match work item types by name, including custom types. Maps to the
-  `work_item_type_names` filter (case-insensitive, server-side).
-- `state` - `opened` or `closed`.
+  `work_item_type_names` filter (case-insensitive, server-side). Any work item
+  type name is accepted.
+- `state` - `opened` or `closed`, checked at load time.
 - `status` - custom work item status name (for example `In progress`).
   Enterprise Edition only.
 - `labels` / `forbidden_labels` - label names to require or exclude.
 - `assignees` - assignee usernames.
+- `milestone` - one milestone title, or one of `none`, `any`, `upcoming`,
+  `started` (case-insensitive). Maps to the `milestone_title` or
+  `milestone_wildcard_id` filter. Same shape as the
+  [milestone condition](#milestone-condition). A list of more than one
+  milestone, or a blank one, is rejected at load time. Quote titles that look
+  like numbers (`milestone: '19.10'`): YAML reads an unquoted `19.10` as
+  `19.1`, so it is rejected too.
+
+  `upcoming` and `started` follow GitLab's current milestone logic, so they
+  can match different work items than the same values on `issues`. The
+  Issues REST API keeps the logic deprecated in GitLab 17.7 to avoid a
+  breaking change
+  ([gitlab-org/gitlab#501294](https://gitlab.com/gitlab-org/gitlab/-/issues/501294)),
+  and the Work Items REST API does not:
+
+  - `upcoming`: on `issues`, the one milestone per project or group with the
+    nearest future due date, often the milestone in progress. On
+    `work_items`, every milestone that has not started yet.
+  - `started`: on `issues`, active milestones that have started, including
+    overdue ones. On `work_items`, only those whose due date has not passed.
+
+  Dry-run a rule that uses `upcoming` or `started` before moving it from
+  `issues` to `work_items`.
 - `date` - `created_at` / `updated_at` staleness (same shape as the
-  [date condition](#date-condition)).
+  [date condition](#date-condition)). `attribute`, `condition`,
+  `interval_type`, and `interval` are all required and checked at load time,
+  with or without `filter_in_ruby`, and `interval` must be a positive number.
+  A missing or unsupported value would otherwise send no date filter, so the
+  rule would match every work item, and a misspelled `condition` would select
+  the opposite work items.
+
+Run in Ruby on the fetched work items:
+
+- `author_member` - see [author member condition](#author-member-condition).
+- `assignee_member` - see [assignee member condition](#assignee-member-condition).
+- `ruby` - see [ruby condition](#ruby-condition).
+- `no_additional_labels` - see [no additional labels condition](#no-additional-labels-condition).
+- `work_item_status` - see [work item status condition](#work-item-status-condition).
+
+Any other condition key (for example `issue_type`, `weight`, or a misspelled
+key) is rejected at load time, before any resource is fetched, with an error
+listing the supported conditions. Ignoring it instead would make the rule match
+more work items than intended. `votes`, `upvotes`, and `discussions` are not
+supported yet (tracked in
+[gitlab-org/gitlab#630293](https://gitlab.com/gitlab-org/gitlab/-/work_items/630293)).
 
 #### Supported actions
 
@@ -208,20 +254,18 @@ resource_rules:
 - `assignees` - set assignees by username. If any requested username does not
   exist, the automation stops immediately rather than sending an empty
   assignee set (which would unassign everyone).
-- `comment` - **not yet supported.** The Work Items REST API does not yet
-  provide a note-create endpoint (tracked in
-  [gitlab-org/gitlab#604028](https://gitlab.com/gitlab-org/gitlab/-/work_items/604028)).
-  A `comment` action on a `work_items` policy is rejected at load time, before
-  any resource is fetched or acted on, with a clear error - so an unsupported
-  policy never runs partway through. Use the `issues` policy type if you need
-  to comment.
+- `comment` - post a comment (note) on the work item through the Work Items REST
+  API. Supports the same body templating as the `issues` type, along with
+  `mention`, `comment_type: thread`, `comment_internal`, and
+  `redact_confidential_resources`. The `{{closed_by}}` placeholder needs
+  GitLab 19.6 or later. Quick actions in the body are run by the API, but the
+  available command set follows the work item type's enabled widgets, so some
+  issue-only commands are no-ops on work items.
 
 Summaries are also supported (`summarize` and `comment_on_summary`). Any other
-action key (for example `mention`, `move`, or `status`) is
-rejected at load time with an error listing the supported actions. On the
-older policy types these keys are applied through comment quick actions, which
-work items do not support yet - rejecting them up front beats silently doing
-nothing.
+action key (for example `move` or `status`) is rejected at load time with an
+error listing the supported actions, since those actions are not wired for the
+`work_items` type yet - rejecting them up front beats silently doing nothing.
 
 Actions require a token with sufficient permissions (Planner or Reporter role
 and above). The update endpoint can return success without persisting a change
@@ -235,7 +279,15 @@ against; updates and label lookups target each work item's own namespace,
 because a group run can return work items living in different sub-projects and
 an iid is only unique within its namespace. Project-scoped resource helpers
 (for example `project_path` in templates) likewise resolve the underlying
-project from the work item's namespace.
+project from the work item's namespace. `full_resource_reference` and the
+`{{full_reference}}` placeholder render the work item's full reference (for
+example `gitlab-org/gitlab#42`), the same as on `issues`. `resource[:health_status]`
+is a string such as `on_track`, `needs_attention`, or `at_risk`, the same as on
+`issues`. It is `nil` when no health status is set, and always `nil` on GitLab
+Community Edition or a namespace without the license for health status. After a
+license downgrade, work items can keep a stored health status that the API no
+longer returns, so a rule such as `resource[:health_status] != 'at_risk'` can
+match work items that are at risk.
 
 The `api:` field is not applicable to the `work_items` type, since the type
 already fixes the transport to the Work Items REST API.
@@ -1526,6 +1578,10 @@ resource_rules:
 
 Delete the resource.
 
+When GitLab refuses a deletion, for example with 403 because the token may not
+delete the resource, a warning with the URL, the status and GitLab's message is
+printed, and the rule goes on with the next resource.
+
 Accept a boolean. Set to `true` to enable.
 
 Example :

data/lib/gitlab/triage/action/comment.rb

@@ -61,21 +61,25 @@ module Gitlab
         end
 
         def perform(resource, comment)
-          if network.options.debug
-            if policy.actions.fetch(:redact_confidential_resources, true) && resource[:confidential]
-              puts Gitlab::Triage::UI.debug "Comment action resource: (confidential)"
-            else
-              puts Gitlab::Triage::UI.debug "Comment action resource: #{resource.inspect}"
-            end
-
-            puts Gitlab::Triage::UI.debug "Comment action content: #{comment}"
-          end
+          print_debug(resource, comment)
 
           network.post_api(
             build_post_url(resource),
             post_body(comment))
         end
 
+        def print_debug(resource, comment)
+          return unless network.options.debug
+
+          if policy.actions.fetch(:redact_confidential_resources, true) && resource[:confidential]
+            puts Gitlab::Triage::UI.debug "Comment action resource: (confidential)"
+          else
+            puts Gitlab::Triage::UI.debug "Comment action resource: #{resource.inspect}"
+          end
+
+          puts Gitlab::Triage::UI.debug "Comment action content: #{comment}"
+        end
+
         def build_post_url(resource)
           url_builder_opts = {
             network_options: network.options,

data/lib/gitlab/triage/action/delete.rb

@@ -15,7 +15,7 @@ module Gitlab
           private
 
           def perform(resource)
-            puts "DELETE resource with type: #{resource[:type]} and id: #{resource_id(resource)}"
+            puts "DELETE #{build_delete_url(resource)}"
           end
         end
 
@@ -36,7 +36,8 @@ module Gitlab
         def build_delete_url(resource)
           delete_url = UrlBuilders::UrlBuilder.new(
             source: policy.source,
-            source_id: network.options.source_id,
+            # Branches carry no project_id, so they fall back to --source-id.
+            source_id: resource[policy.source_id_sym] || network.options.source_id,
             resource_type: policy.type,
             resource_id: resource_id(resource),
             network_options: network.options

data/lib/gitlab/triage/action/work_item.rb

@@ -22,9 +22,8 @@ module Gitlab
       class WorkItem < Base
         UpdateNotAppliedError = Class.new(StandardError)
 
-        # The dry run must not touch the network. It prints the requested
-        # label names and assignee usernames rather than resolving them to
-        # ids, mirroring how Comment::Dry avoids network calls.
+        # Prints the requested changes without writing them. verify! still
+        # looks the names up first, so a typo fails the dry run too.
         class Dry < WorkItem
           def act
             puts "The following work items would be updated for the rule **#{policy.name}**:\n\n"
@@ -43,6 +42,17 @@ module Gitlab
           end
         end
 
+        # Resolves every item's labels and assignees up front, so a name missing
+        # in a later item's namespace fails the run before any item is labeled.
+        def verify!
+          policy.resources.each do |resource|
+            label_ids_to_add(resource) if requested_labels.any?
+            label_ids_to_remove(resource) if requested_removed_labels.any?
+          end
+
+          assignee_ids if requested_assignees.any?
+        end
+
         def act
           return unless requested_labels.any? || requested_removed_labels.any? || requested_assignees.any?
 
@@ -126,7 +136,7 @@ module Gitlab
 
         def labels_by_name(scope)
           @labels_by_name_by_scope ||= {}
-          @labels_by_name_by_scope[scope] ||= network.query_api(labels_url(scope)).index_by { |label| label[:name] }
+          @labels_by_name_by_scope[scope] ||= network.query_api_cached(labels_url(scope)).index_by { |label| label[:name] }
         end
 
         # The Work Items REST update endpoint can return success without

data/lib/gitlab/triage/action/work_item_comment.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'comment'
+require_relative '../sources/work_items_rest_source'
+
+module Gitlab
+  module Triage
+    module Action
+      # Posts comments on work items through the Work Items REST API notes
+      # endpoint rather than the issues note/quick-action path. The comment body
+      # (templating, redaction, and mentions) is built exactly as on the issues
+      # type - only the write target differs, so this reuses Comment and
+      # overrides just where the note is sent.
+      class WorkItemComment < Comment
+        # WorkItem writes labels before this posts, so reject an unknown
+        # comment_type up front rather than after the labels are written.
+        def verify!
+          sub_resource_type
+        end
+
+        private
+
+        # Raising would also lose every later item's note, and any labels are
+        # already written. Warn and move on, as issues drop a rejected note.
+        def perform(resource, comment)
+          print_debug(resource, comment)
+          source.create_note(resource, post_body(comment), sub_resource_type: sub_resource_type)
+        rescue Sources::WorkItemsRestSource::NoteNotCreatedError => e
+          puts Gitlab::Triage::UI.warn(e.message)
+        end
+
+        def source
+          @source ||= Sources::WorkItemsRestSource.new(
+            network: network, options: network.options)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/action.rb

@@ -7,6 +7,7 @@ require_relative 'action/issue'
 require_relative 'action/delete'
 require_relative 'action/work_item_status'
 require_relative 'action/work_item'
+require_relative 'action/work_item_comment'
 require_relative 'action/update'
 
 module Gitlab
@@ -24,10 +25,9 @@ module Gitlab
         end
       end
 
-      # Comment runs before the actions that write labels, so without this a
-      # rule naming a label, user, milestone, or move destination that no
-      # longer exists posts its note and only then raises, and the next
-      # scheduled run posts it again.
+      # Without this, a rule naming a label, user, milestone, or move
+      # destination that no longer exists raises only after earlier actions
+      # wrote, such as an issues note the next scheduled run posts again.
       def self.verify!(actions, policy:, network:)
         actions.each do |action|
           action.new(policy: policy, network: network).verify!
@@ -36,13 +36,17 @@ module Gitlab
 
       # Work items are fetched and updated through the Work Items REST API,
       # which does not share the issues note/quick-action write path. Their
-      # actions (assign, label, comment) are handled by a dedicated action
-      # instead of the note-based Comment action.
+      # actions are handled by dedicated actions: WorkItem (assign, label) and
+      # WorkItemComment, which posts through the REST notes endpoint rather than
+      # the issues Comment path. Unlike issues, labels are written before the
+      # note: a failed label write then loses a note once, instead of leaving
+      # unlabeled items that get the note again on every run.
       def self.actions_for(policy)
         if policy.type == 'work_items'
           [
             [Summarize, policy.summarize?],
             [WorkItem, policy.work_item?],
+            [WorkItemComment, policy.comment?],
             [CommentOnSummary, policy.comment_on_summary?]
           ]
         else

data/lib/gitlab/triage/engine.rb

@@ -33,6 +33,7 @@ require_relative 'rest_api_network'
 require_relative 'network_adapters/httparty_adapter'
 require_relative 'network_adapters/graphql_adapter'
 require_relative 'graphql_queries/query_builder'
+require_relative 'milestone_wildcards'
 require_relative 'sources/work_items_rest_source'
 require_relative 'validators/params_validator'
 require_relative 'validators/policy_validator'
@@ -47,6 +48,8 @@ module Gitlab
       # This filter map is used to help make the filter_resource method
       # smaller. We loop through each of the keys (conditions) and map
       # that to the filters that will be used for it.
+      # A filter enabled for work_items must also be added to
+      # Validators::PolicyValidator::RUBY_WORK_ITEM_CONDITIONS.
       FILTER_MAP = {
         date: {
           'branches' => Filters::BranchDateFilter,
@@ -70,9 +73,9 @@ module Gitlab
       ALLOWED_STATE_VALUES = {
         issues: %w[opened closed],
         merge_requests: %w[opened closed merged],
-        work_items: %w[opened closed]
+        work_items: Validators::PolicyValidator::WORK_ITEM_STATES
       }.with_indifferent_access.freeze
-      MILESTONE_TIMEBOX_VALUES = %w[none any upcoming started].freeze
+      MILESTONE_TIMEBOX_VALUES = MilestoneWildcards::VALUES
       ITERATION_SELECTION_VALUES = %w[none any].freeze
       EpicsTriagingForProjectImpossibleError = Class.new(StandardError)
       MultiPolicyInInjectionModeError = Class.new(StandardError)
@@ -515,14 +518,8 @@ module Gitlab
         conditions = expanded_conditions.dup
         conditions[:iids] = options.resource_reference[1..] if options.resource_reference
 
-        # The work_items path bypasses build_get_url, so validate `state` here
-        # the same way the URL builders do for the other resource types.
-        if conditions[:state]
-          ParamsValidator.new(
-            [{ name: 'state', type: String, values: ALLOWED_STATE_VALUES[:work_items] }],
-            { 'state' => conditions[:state] }).validate!
-        end
-
+        # The work_items path bypasses build_get_url, so `state` is not checked by
+        # the URL builders. PolicyValidator checks it in #perform before any fetch.
         work_items_source.list(conditions)
       end
 
@@ -679,12 +676,8 @@ module Gitlab
         return if milestone_value.empty?
 
         # Issues API should use the `milestone_id` param for timebox values, and `milestone` for milestone title
-        args =
-          if resource_type.to_sym == :issues && MILESTONE_TIMEBOX_VALUES.include?(milestone_value.downcase)
-            ['milestone_id', milestone_value.titleize] # The API only accepts titleized values.
-          else
-            ['milestone', milestone_value]
-          end
+        wildcard = MilestoneWildcards.api_value(milestone_value) if resource_type.to_sym == :issues
+        args = wildcard ? ['milestone_id', wildcard] : ['milestone', milestone_value]
 
         APIQueryBuilders::SingleQueryParamBuilder.new(*args)
       end

data/lib/gitlab/triage/milestone_wildcards.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string/inflections'
+
+module Gitlab
+  module Triage
+    # Milestone condition values that select a group of milestones rather than one
+    # title. Kept apart from Engine so the work items source and the policy validator
+    # can share it: Engine requires both of them.
+    module MilestoneWildcards
+      VALUES = %w[none any upcoming started].freeze
+
+      # The Issues API (milestone_id) and the Work Items API (milestone_wildcard_id)
+      # only accept the capitalised form, for example Started. Returns nil for a title.
+      def self.api_value(milestone)
+        value = milestone.to_s.downcase
+
+        value.titleize if VALUES.include?(value)
+      end
+    end
+  end
+end

data/lib/gitlab/triage/network_adapters/httparty_adapter.rb

@@ -126,6 +126,7 @@ module Gitlab
           tracker&.record('DELETE', url)
 
           {
+            status: response.code,
             results: response.parsed_response,
             ratelimit_remaining: rate_limit_remaining(response.headers),
             ratelimit_reset_at: rate_limit_reset_at(response.headers)

data/lib/gitlab/triage/normalizers/work_item_normalizer.rb

@@ -27,10 +27,22 @@ module Gitlab
             confidential: resource[:confidential],
             created_at: resource[:created_at],
             updated_at: resource[:updated_at],
+            closed_at: resource[:closed_at],
             author: resource[:author],
+            closed_by: resource[:closed_by],
+            # Same shape as the Issues API, which full_resource_reference and
+            # the {{full_reference}} placeholder read.
+            references: ({ full: resource[:reference] } if resource[:reference]),
             labels: label_titles(features),
             assignees: assignees(features),
+            # The issues API's deprecated single assignee, read by {{assignee}}.
+            assignee: assignees(features).first,
             milestone: features[:milestone],
+            upvotes: features.dig(:award_emoji, :upvotes),
+            downvotes: features.dig(:award_emoji, :downvotes),
+            # Flat string, like the Issues API: ruby conditions compare
+            # resource[:health_status] with values such as 'at_risk'.
+            health_status: features.dig(:health_status, :health_status),
             work_item_type: resource.dig(:work_item_type, :name),
             work_item_status: status_name(features),
             start_date: features.dig(:start_and_due_date, :start_date),

data/lib/gitlab/triage/rest_api_network.rb

@@ -147,6 +147,7 @@ module Gitlab
 
         rate_limit_debug(response) if options.debug
         rate_limit_wait(response)
+        warn_on_failed_delete(url, response)
       end
 
       private
@@ -218,6 +219,21 @@ module Gitlab
         sleep(1) until Time.now >= reset_at
       end
 
+      # Warns rather than raises, so one refused DELETE does not stop the
+      # other deletions of the rule.
+      def warn_on_failed_delete(url, response)
+        status = response[:status]
+        return if status.nil? || (200..299).cover?(status)
+
+        results = response[:results]
+        message = results['message'] || results['error'] if results.is_a?(Hash)
+
+        warning = "DELETE #{url} failed with status #{status}"
+        warning += ": #{message}" if message
+
+        puts Gitlab::Triage::UI.warn(warning)
+      end
+
       def raise_unexpected_response(results)
         raise Errors::Network::UnexpectedResponse, "Unexpected response: #{results.inspect}"
       end

data/lib/gitlab/triage/sources/work_items_rest_source.rb

@@ -2,10 +2,12 @@
 
 require 'active_support/all'
 
+require_relative '../milestone_wildcards'
 require_relative '../url_builders/url_builder'
 require_relative '../normalizers/work_item_normalizer'
 require_relative '../errors'
 require_relative '../ui'
+require_relative '../validators/policy_validator'
 
 module Gitlab
   module Triage
@@ -19,12 +21,12 @@ module Gitlab
       #
       # The source is a self-contained peer to the engine's inline issues /
       # merge_requests / branches fetch: it owns list URL building, filter
-      # push-down, normalization, and the PATCH update path. Comment creation
-      # is not yet available on the Work Items REST API, so the `comment`
-      # action is rejected at load time by Validators::PolicyValidator.
+      # push-down, normalization, the PATCH update path, and the notes /
+      # discussions write path used by the `comment` action.
       class WorkItemsRestSource
         UnavailableError = Class.new(StandardError)
         ScopeError = Class.new(StandardError)
+        NoteNotCreatedError = Class.new(StandardError)
 
         # Base fields opted into on the list endpoint. The endpoint is sparse
         # by default (id, iid, global_id, title only); every field a filter or
@@ -38,15 +40,22 @@ module Gitlab
           author
           namespace
           work_item_type
+          reference
+          closed_at
+          closed_by
         ].freeze
 
-        # Widget payloads opted into via `features`.
+        # Widget payloads opted into via `features`. status and health_status are EE
+        # only: CE accepts them on read endpoints and leaves them out of the response,
+        # as an unlicensed EE namespace does, so their values are then nil.
         LIST_FEATURES = %w[
           labels
           assignees
           milestone
           status
           start_and_due_date
+          award_emoji
+          health_status
         ].freeze
 
         def initialize(network:, options:, per_page: 100, normalizer: Normalizers::WorkItemNormalizer.new)
@@ -68,6 +77,16 @@ module Gitlab
           @network.patch_api(work_item_url(resource), features: features)
         end
 
+        # The adapter does not raise on a 4xx. Check for an error message, not a
+        # missing id, since a quick-action-only note returns 202 with no id.
+        def create_note(resource, body, sub_resource_type: 'notes')
+          response = @network.post_api(note_url(resource, sub_resource_type), body)
+          error = response[:id].blank? && (response[:message] || response[:error])
+          return response unless error
+
+          raise NoteNotCreatedError, "The note was not posted on #{resource[:web_url] || resource[:iid]} (#{error})."
+        end
+
         # Returns [source, source_id] for the namespace the resource lives in.
         # A group run can return work items from descendant projects, and an
         # iid is only unique within its own namespace, so writes and label
@@ -168,12 +187,26 @@ module Gitlab
           ).build
         end
 
+        def note_url(resource, sub_resource_type)
+          scope, scope_id = scope_for(resource)
+
+          UrlBuilders::UrlBuilder.new(
+            network_options: @options,
+            source: scope,
+            source_id: scope_id,
+            resource_type: '-/work_items',
+            resource_id: resource[:iid],
+            sub_resource_type: sub_resource_type
+          ).build
+        end
+
         def list_params(conditions)
           params = {
             per_page: @per_page,
             fields: LIST_FIELDS.join(','),
             features: LIST_FEATURES.join(',')
           }
+          params[:include_descendants] = true if @options.source == 'groups'
 
           apply_filters(params, conditions)
 
@@ -184,6 +217,8 @@ module Gitlab
         # `type` uses `work_item_type_names`, which resolves names (including
         # custom types) case-insensitively server-side - no id resolution
         # needed.
+        # A new work_items condition must also be added to
+        # Validators::PolicyValidator::API_WORK_ITEM_CONDITIONS.
         def apply_filters(params, conditions)
           params[:iids] = Array(conditions[:iids]).join(',') if conditions[:iids].present?
           params[:work_item_type_names] = Array(conditions[:type]).join(',') if conditions[:type]
@@ -193,30 +228,39 @@ module Gitlab
           params[:assignee_usernames] = Array(conditions[:assignees]).join(',') if conditions[:assignees]
           params['status[name]'] = conditions[:status] if conditions[:status]
 
+          apply_milestone_filter(params, conditions[:milestone]) if conditions[:milestone]
           apply_date_filter(params, conditions[:date]) if conditions[:date]
         end
 
-        def apply_date_filter(params, date_condition)
-          attribute = date_condition[:attribute]
-          condition = date_condition[:condition]
-          return unless %w[created_at updated_at].include?(attribute)
+        # PolicyValidator rejects more than one value, so a list here has at most one.
+        # The Issues REST API keeps the legacy Started/Upcoming logic and this API does
+        # not, so the same wildcard can match different milestones (see README).
+        def apply_milestone_filter(params, milestone_condition)
+          milestone = Array(milestone_condition).first.to_s
+          return if milestone.empty?
+
+          wildcard = MilestoneWildcards.api_value(milestone)
 
-          boundary = date_boundary(date_condition)
-          return unless boundary
+          if wildcard
+            params[:milestone_wildcard_id] = wildcard
+          else
+            params[:milestone_title] = milestone
+          end
+        end
 
-          direction = condition == 'older_than' ? 'before' : 'after'
-          params["#{attribute.delete_suffix('_at')}_#{direction}"] = boundary.iso8601
+        # A bad date condition would otherwise send no date filter, or the opposite one,
+        # and widen the matched set, so raise even if load-time validation was skipped.
+        def apply_date_filter(params, date_condition)
+          Validators::PolicyValidator.validate_work_items_date!(date_condition)
+
+          attribute = date_condition[:attribute]
+          direction = date_condition[:condition] == 'older_than' ? 'before' : 'after'
+          params["#{attribute.delete_suffix('_at')}_#{direction}"] = date_boundary(date_condition).iso8601
         end
 
         def date_boundary(date_condition)
-          interval = date_condition[:interval]
-          interval_type = date_condition[:interval_type]
-          return unless interval && interval_type
-
-          # A malformed interval_type raises here rather than silently dropping
-          # the date bound, which would widen the matched set - dangerous in an
-          # automation tool. interval_type is also validated by the date filter.
-          interval.public_send(interval_type).ago # rubocop:disable GitlabSecurity/PublicSend -- interval_type constrained to a known set
+          # validate_work_items_date! limits interval_type to the date filter's INTERVAL_TYPES.
+          date_condition[:interval].public_send(date_condition[:interval_type]).ago # rubocop:disable GitlabSecurity/PublicSend -- interval_type constrained to a known set
         end
       end
     end

data/lib/gitlab/triage/validators/policy_validator.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative '../filters/work_item_date_conditions_filter'
+require_relative '../milestone_wildcards'
+
 module Gitlab
   module Triage
     module Validators
@@ -10,16 +13,77 @@ module Gitlab
       # where nobody sees it).
       class PolicyValidator
         UnsupportedActionError = Class.new(StandardError)
+        UnsupportedConditionError = Class.new(StandardError)
+        InvalidConditionError = Class.new(StandardError)
         ConflictingActionError = Class.new(StandardError)
 
-        COMMENT_NOT_SUPPORTED_MESSAGE =
-          'Commenting on work_items is not yet supported by the Work Items REST API ' \
-            '(blocked on https://gitlab.com/gitlab-org/gitlab/-/work_items/604028). ' \
-            'Use the issues policy type for comment actions.'
+        # Action keys Action.actions_for dispatches for work_items policies
+        # (comment, mention, comment_type, comment_internal, and
+        # redact_confidential_resources are the comment action and its options).
+        # Anything outside this list would silently do nothing, so reject it up
+        # front.
+        SUPPORTED_WORK_ITEM_ACTIONS = %i[
+          labels remove_labels assignees
+          comment mention comment_type comment_internal redact_confidential_resources
+          summarize comment_on_summary
+        ].freeze
+
+        # A summary's own actions run over the whole summary, not per item, so
+        # the per-item actions would crash there.
+        SUPPORTED_SUMMARY_ACTIONS = %i[summarize comment_on_summary].freeze
+
+        # A rule nested in a summary only feeds it: the engine reads its
+        # summarize action and runs nothing else.
+        SUPPORTED_SUMMARY_RULE_ACTIONS = %i[summarize].freeze
+
+        # Sent to the Work Items REST API as query params by WorkItemsRestSource#apply_filters.
+        API_WORK_ITEM_CONDITIONS = %i[type state status labels forbidden_labels assignees milestone date].freeze
+
+        # Applied in Ruby to the fetched work items through Engine::FILTER_MAP.
+        RUBY_WORK_ITEM_CONDITIONS = %i[author_member assignee_member ruby no_additional_labels work_item_status].freeze
+
+        # Any other key would be silently ignored and widen the matched set, so reject it up front.
+        SUPPORTED_WORK_ITEM_CONDITIONS = (API_WORK_ITEM_CONDITIONS + RUBY_WORK_ITEM_CONDITIONS).freeze
+
+        # States the Work Items REST API filters on. Engine::ALLOWED_STATE_VALUES reads
+        # this too, since the engine requires this file and not the other way round.
+        WORK_ITEM_STATES = %w[opened closed].freeze
+
+        # WorkItemsRestSource#apply_date_filter would send no date filter for a bad attribute
+        # or a missing interval, so the rule would match every item, and reads any condition
+        # other than older_than as newer_than. Check the values against the same parameters
+        # the Ruby date filter uses, so filter_in_ruby: true accepts exactly the same ones.
+        # The source calls this too, so a condition that skipped load-time validation still
+        # cannot reach the API unchecked.
+        def self.validate_work_items_date!(date_condition)
+          # Despite the name, filter_parameters returns the definitions of the date
+          # condition's keys (name, type, allowed values), not API query params.
+          date_parameters = Filters::WorkItemDateConditionsFilter.filter_parameters
+
+          unless date_condition.is_a?(Hash)
+            raise InvalidConditionError,
+              "The date condition on work_items policies takes " \
+                "#{date_parameters.pluck(:name).to_sentence}, but got #{date_condition.inspect}."
+          end
+
+          date_condition = date_condition.with_indifferent_access
+          ParamsValidator.new(date_parameters, date_condition).validate!
+          validate_date_interval!(date_condition)
+        rescue ParamsValidator::InvalidParameter => e
+          raise InvalidConditionError,
+            "Invalid date condition on work_items policies: #{e.message}, but got #{date_condition.inspect}."
+        end
 
-        # Action keys Action.actions_for dispatches for work_items policies.
-        # Anything outside this list would silently do nothing, so reject it up front.
-        SUPPORTED_WORK_ITEM_ACTIONS = %i[labels remove_labels assignees summarize comment_on_summary].freeze
+        # A zero or negative interval puts the boundary at or after now, so older_than
+        # matches every item; YAML's .inf and .nan load as Floats and raise only when
+        # the boundary is computed, partway through a run.
+        def self.validate_date_interval!(date_condition)
+          interval = date_condition[:interval]
+          return if interval.finite? && interval.positive?
+
+          raise ParamsValidator::InvalidParameter, 'interval must be a positive, finite number'
+        end
+        private_class_method :validate_date_interval!
 
         def initialize(resource_rules)
           @resource_rules = resource_rules || {}
@@ -29,16 +93,68 @@ module Gitlab
           @resource_rules.each do |resource_type, policy_definition|
             next unless resource_type.to_s == 'work_items'
 
+            validate_work_items_conditions!(policy_definition)
             validate_work_items_actions!(policy_definition)
           end
         end
 
         private
 
-        def validate_work_items_actions!(policy_definition)
-          action_sets_from(policy_definition).each do |actions|
-            raise UnsupportedActionError, COMMENT_NOT_SUPPORTED_MESSAGE if actions.key?(:comment)
+        def validate_work_items_conditions!(policy_definition)
+          condition_sets_from(policy_definition).each do |conditions|
+            unsupported = conditions.keys.map(&:to_sym) - SUPPORTED_WORK_ITEM_CONDITIONS
+            unless unsupported.none?
+              raise UnsupportedConditionError,
+                "Unsupported condition(s) for work_items policies: #{unsupported.join(', ')}. " \
+                  "Supported conditions: #{SUPPORTED_WORK_ITEM_CONDITIONS.join(', ')}."
+            end
+
+            validate_state!(conditions[:state]) if conditions.key?(:state)
+            validate_milestone!(conditions[:milestone]) if conditions.key?(:milestone)
+            self.class.validate_work_items_date!(conditions[:date]) if conditions.key?(:date)
+          end
+        end
+
+        # Checked here rather than when the rule fetches, so a typo such as `open`
+        # fails before any earlier rule has acted. `merged` is valid for merge
+        # requests but not for work items.
+        def validate_state!(state)
+          return if WORK_ITEM_STATES.include?(state)
+
+          raise InvalidConditionError,
+            "The state condition on work_items policies takes one of #{WORK_ITEM_STATES.join(', ')}, " \
+              "but got #{state.inspect}."
+        end
+
+        # The issues policy type silently uses the first of several milestones, and
+        # skips the filter for a blank one, so the rule matches every item. work_items
+        # has no old policies to stay compatible with, so it rejects both.
+        def validate_milestone!(milestone_condition)
+          milestones = Array(milestone_condition)
+          if milestones.size > 1
+            raise InvalidConditionError,
+              "The milestone condition takes one value on work_items policies, " \
+                "but got #{milestones.size}: #{milestones.join(', ')}."
+          end
+
+          milestone = milestones.first
+          return if milestone.is_a?(String) && milestone.strip.present?
+
+          raise InvalidConditionError, invalid_milestone_message(milestone)
+        end
 
+        # YAML reads an unquoted 19.10 as the number 19.1, so a version-like title
+        # must be quoted to reach the API intact.
+        def invalid_milestone_message(milestone)
+          message = "The milestone condition on work_items policies takes a milestone title " \
+            "or one of #{MilestoneWildcards::VALUES.join(', ')}, but got #{milestone.inspect}."
+          return message unless milestone.is_a?(Numeric)
+
+          "#{message} Quote titles that look like numbers, for example milestone: '19.10'."
+        end
+
+        def validate_work_items_actions!(policy_definition)
+          action_sets_from(policy_definition).each do |actions, supported, scope|
             # GitLab applies remove_label_ids after add_label_ids, so a label in
             # both lists is always removed. Catch the typo here rather than let the
             # run fail later with a misleading "token may lack permission" error.
@@ -49,25 +165,37 @@ module Gitlab
                   "A label cannot be added and removed in the same rule."
             end
 
-            unsupported = actions.keys.map(&:to_sym) - SUPPORTED_WORK_ITEM_ACTIONS
+            unsupported = actions.keys.map(&:to_sym) - supported
             next if unsupported.none?
 
             raise UnsupportedActionError,
-              "Unsupported action(s) for work_items policies: #{unsupported.join(', ')}. " \
-                "Supported actions: #{SUPPORTED_WORK_ITEM_ACTIONS.join(', ')}."
+              "Unsupported action(s) for work_items #{scope}: #{unsupported.join(', ')}. " \
+                "Supported actions: #{supported.join(', ')}."
           end
         end
 
-        # Every place a policy definition can carry actions: top-level rules,
-        # rules nested in summaries, and the summaries' own actions.
+        # Every place a policy definition can carry actions, with the actions
+        # allowed there: top-level rules, rules nested in summaries, and the
+        # summaries' own actions.
         def action_sets_from(policy_definition)
           policy_definition ||= {}
 
           summaries = Array(policy_definition[:summaries])
           summary_rules = summaries.flat_map { |summary| Array(summary[:rules]) }
 
-          (Array(policy_definition[:rules]) + summary_rules + summaries)
-            .map { |definition| definition[:actions] || {} }
+          Array(policy_definition[:rules]).map { |rule| [rule[:actions] || {}, SUPPORTED_WORK_ITEM_ACTIONS, 'policies'] } +
+            summary_rules.map { |rule| [rule[:actions] || {}, SUPPORTED_SUMMARY_RULE_ACTIONS, 'summary rules'] } +
+            summaries.map { |summary| [summary[:actions] || {}, SUPPORTED_SUMMARY_ACTIONS, 'summaries'] }
+        end
+
+        # Conditions live on top-level rules and rules nested in summaries.
+        def condition_sets_from(policy_definition)
+          policy_definition ||= {}
+
+          summary_rules = Array(policy_definition[:summaries]).flat_map { |summary| Array(summary[:rules]) }
+
+          (Array(policy_definition[:rules]) + summary_rules)
+            .map { |definition| definition[:conditions] || {} }
         end
       end
     end

data/lib/gitlab/triage/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module Triage
-    VERSION = '1.57.0'
+    VERSION = '1.58.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-triage
 version: !ruby/object:Gem::Version
-  version: 1.57.0
+  version: 1.58.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -252,6 +252,7 @@ files:
 - lib/gitlab/triage/action/summarize.rb
 - lib/gitlab/triage/action/update.rb
 - lib/gitlab/triage/action/work_item.rb
+- lib/gitlab/triage/action/work_item_comment.rb
 - lib/gitlab/triage/action/work_item_status.rb
 - lib/gitlab/triage/api_observability.rb
 - lib/gitlab/triage/api_query_builders/base_query_param_builder.rb
@@ -294,6 +295,7 @@ files:
 - lib/gitlab/triage/graphql_queries/query_param_builders/date_param_builder.rb
 - lib/gitlab/triage/limiters/base_limiter.rb
 - lib/gitlab/triage/limiters/date_field_limiter.rb
+- lib/gitlab/triage/milestone_wildcards.rb
 - lib/gitlab/triage/network.rb
 - lib/gitlab/triage/network_adapters/base_adapter.rb
 - lib/gitlab/triage/network_adapters/graphql_adapter.rb