gitlab-triage 1.52.0 → 1.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0188aec696ec4f1821f6e9d4244a2323527d464e9c51da0b7e2b54053003a2c
-  data.tar.gz: d432a7b181c290420afdd883c01a55f686a1e30d1797f736fbbf3171459f36ee
+  metadata.gz: e4b12c328cc4c5a865ceca6ccadd49a8dedc1066564fa62a28718c3b164f3a15
+  data.tar.gz: 1298d537c79ef8d74f3816e18d482a8bbee02fde1b3a1717869709795f40f547
 SHA512:
-  metadata.gz: 797365b9ad72539cf3027e7e00130cbf88172e11ec46162c7c38e25d7eebbaca39cb6d5518a033ac7b820e127c15b0ef8a3d64c8011a0dcd45f4d9ef985a13c6
-  data.tar.gz: 46c14ed3a8916402aefe35aaa6b5f80c8b6b647ee4f6e1ab7bbf138ac4c0c9fd0326a672be08abc1043bfdcc5280d74456554a71f2f390439f1b9858828401f7
+  metadata.gz: c8d68d1f8162e2324685ee874a862429569f76d4a060d138f922f1b4866b57eabfc9420f72a6da68f28f0285669542169f6b7294f785e6152c3075c36280bf40
+  data.tar.gz: aaf7e8821f7cbfc9112c2f25776566c7775276c5eeebaccd43dedcee686824cce2db97ee813648504274befd5db4696f4e816afb6bab83d72039e2cfa7e13437

data/.rubocop_todo.yml

@@ -6,13 +6,15 @@
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 78
+# Offense count: 81
 CodeReuse/ActiveRecord:
   Exclude:
+    - 'lib/gitlab/triage/action/work_item.rb'
     - 'lib/gitlab/triage/engine.rb'
     - 'lib/gitlab/triage/filters/base_conditions_filter.rb'
     - 'lib/gitlab/triage/filters/member_conditions_filter.rb'
     - 'lib/gitlab/triage/graphql_network.rb'
+    - 'lib/gitlab/triage/normalizers/work_item_normalizer.rb'
     - 'lib/gitlab/triage/validators/limiter_validator.rb'
     - 'spec/gitlab/triage/action_spec.rb'
     - 'spec/gitlab/triage/engine_spec.rb'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gitlab-triage (1.52.0)
+    gitlab-triage (1.53.0)
       activesupport (>= 5.1)
       globalid (~> 1.0, >= 1.0.1)
       graphql (< 2.1.0)

data/README.md

@@ -50,6 +50,7 @@ Select which resource to add the policy to:
 - `issues`
 - `merge_requests`
 - `branches`
+- `work_items` (see [Work items policy type](#work-items-policy-type))
 
 And create an array of `rules` to define your policies:
 
@@ -148,6 +149,107 @@ We're enforcing multiple polices with pipeline schedules at [triage-ops](
 https://gitlab.com/gitlab-org/quality/triage-ops), where we're also
 extensively utilizing the [plugins system](#can-i-customize).
 
+### Work items policy type
+
+The `work_items` policy type fetches and updates resources through the
+[Work Items REST API](https://docs.gitlab.com/api/work_items/) instead of the
+legacy issues REST API. The legacy issues API cannot see custom work item
+types; the `work_items` type can, which lets you triage work items of any type,
+including namespace-defined custom types.
+
+> **Warning:** The Work Items REST API is currently behind the
+`:work_item_rest_api` feature flag and is pre-GA. The `work_items` policy type
+only works on instances where that API is available and enabled, and its
+surface may change before GA. It is not yet a stable contract for external
+users. Treat this policy type as experimental until the API reaches GA.
+
+> **Note:** A `404` or `403` from the list endpoint (feature flag off, or
+insufficient access) raises a clear error rather than silently matching zero
+resources.
+
+Example:
+
+```yml
+resource_rules:
+  work_items:
+    rules:
+      - name: Triage new bugs
+        conditions:
+          type: Bug
+          state: opened
+          labels:
+            - needs-triage
+        actions:
+          assignees:
+            - my-username
+          labels:
+            - triaged
+```
+
+#### Supported conditions
+
+- `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`.
+- `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.
+- `date` - `created_at` / `updated_at` staleness (same shape as the
+  [date condition](#date-condition)).
+
+#### Supported actions
+
+- `labels` - add labels by name. If any requested label does not exist, the
+  automation stops immediately (matching the `labels` action on the `issues`
+  type) rather than applying nothing.
+- `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.
+
+Summaries are also supported (`summarize` and `comment_on_summary`). Any other
+action key (for example `remove_labels`, `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.
+
+Actions require a token with sufficient permissions (Planner or Reporter role
+and above). The update endpoint can return success without persisting a change
+when the token lacks permission, so after each update the applied labels and
+assignees are read back from the response and the run raises if the change was
+not reflected.
+
+The `work_items` type works against both project and group sources
+(`--source projects` or `--source groups`). Fetches use the source you run
+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.
+
+The `api:` field is not applicable to the `work_items` type, since the type
+already fixes the transport to the Work Items REST API.
+
+#### Field vocabulary
+
+The `work_items` condition names (`type`, `status`, `state`) are deliberately
+cleaner than the `issues` equivalents (`issue_type`, `work_item_status`,
+`state`). This is intentional: they are meant to become the shared vocabulary
+that `issues` converges onto over time (long term, `issues` would alias to
+`work_items` and eventually deprecate in a major version), not a throwaway
+parallel dialect. `state` (`opened` / `closed`) already means the same on both
+types; `status` is new on `work_items` and has no clean one-to-one equivalent
+on `issues` (where it is the prefixed `work_item_status`). Whether the old
+names are carried as aliases or dropped at a major bump is a future decision.
+
 ### Fields
 
 A policy consists of the following fields:

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../sources/work_items_rest_source'
+require_relative '../url_builders/url_builder'
+require_relative '../resource/label'
+
+module Gitlab
+  module Triage
+    module Action
+      # Applies work_items actions through the Work Items REST API update
+      # endpoint (PATCH) rather than the issues note/quick-action path.
+      #
+      #   - labels    -> features.labels.add_label_ids  (resolved from names)
+      #   - assignees -> features.assignees.assignee_ids (resolved from usernames)
+      #
+      # Missing labels or usernames stop the automation immediately (matching
+      # the labels action behaviour on the issues type) rather than silently
+      # applying nothing - which is especially important because clearing the
+      # assignees array would unassign everyone.
+      class WorkItem < Base
+        AssigneeDoesntExistError = Class.new(StandardError)
+        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.
+        class Dry < WorkItem
+          def act
+            puts "The following work items would be updated for the rule **#{policy.name}**:\n\n"
+
+            super
+          end
+
+          private
+
+          def perform(resource)
+            puts "# #{resource[:web_url]}"
+            puts "Would add labels: #{requested_labels.join(', ')}" if requested_labels.any?
+            puts "Would assign: #{requested_assignees.join(', ')}" if requested_assignees.any?
+            puts "\n"
+          end
+        end
+
+        def act
+          return unless requested_labels.any? || requested_assignees.any?
+
+          policy.resources.each do |resource|
+            perform(resource)
+          end
+        end
+
+        private
+
+        def perform(resource)
+          features = build_features(resource)
+          return if features.empty?
+
+          response = source.update(resource, features)
+
+          verify_applied!(resource, response)
+        end
+
+        def build_features(resource)
+          features = {}
+
+          features[:labels] = { add_label_ids: label_ids_to_add(resource) } if requested_labels.any?
+          features[:assignees] = { assignee_ids: assignee_ids } if requested_assignees.any?
+
+          features
+        end
+
+        def requested_labels
+          @requested_labels ||= Array(policy.actions[:labels])
+        end
+
+        def requested_assignees
+          @requested_assignees ||= Array(policy.actions[:assignees])
+        end
+
+        def source
+          @source ||= Sources::WorkItemsRestSource.new(
+            network: network, options: network.options)
+        end
+
+        # Label ids are namespace-specific, so resolve them against the
+        # resource's own namespace and cache per scope - a group-spanning run
+        # then makes one label lookup per distinct project/group.
+        def label_ids_to_add(resource)
+          scope = source.scope_for(resource)
+
+          @label_ids_by_scope ||= {}
+          @label_ids_by_scope[scope] ||= resolve_label_ids(requested_labels, scope)
+        end
+
+        def assignee_ids
+          @assignee_ids ||= resolve_assignee_ids(requested_assignees)
+        end
+
+        # Resolve every requested label name to an id. Any name that does not
+        # resolve raises, so the run stops instead of PATCHing a partial (or
+        # empty) label set.
+        def resolve_label_ids(names, scope)
+          return [] if names.empty?
+
+          by_name = network.query_api(labels_url(scope)).index_by { |label| label[:name] }
+
+          names.map do |name|
+            label = by_name[name]
+            raise Resource::Label::LabelDoesntExistError, "Label `#{name}` doesn't exist!" unless label
+
+            label[:id]
+          end
+        end
+
+        # Resolve every requested username to an id. A missing username raises
+        # rather than being dropped, because an empty assignee_ids array would
+        # clear all assignees on the work item.
+        def resolve_assignee_ids(usernames)
+          return [] if usernames.empty?
+
+          usernames.map do |username|
+            id = resolve_user_id(username)
+            raise AssigneeDoesntExistError, "User `#{username}` doesn't exist!" unless id
+
+            id
+          end
+        end
+
+        def resolve_user_id(username)
+          users = network.query_api(users_url(username))
+
+          users.first&.dig(:id)
+        end
+
+        # The Work Items REST update endpoint can return success without
+        # persisting a change when the token lacks permission. The response
+        # echoes the resulting widgets, so confirm the requested ids landed and
+        # raise otherwise rather than reporting a silent no-op as success.
+        def verify_applied!(resource, response)
+          verify_labels_applied!(resource, response) if requested_labels.any?
+          verify_assignees_applied!(resource, response) if requested_assignees.any?
+        end
+
+        def verify_labels_applied!(resource, response)
+          applied_ids = [*response.dig(:features, :labels, :labels)].pluck(:id)
+          missing = label_ids_to_add(resource) - applied_ids
+          return if missing.empty?
+
+          raise UpdateNotAppliedError,
+            "Labels were not applied to #{resource[:web_url]}; the token may lack permission."
+        end
+
+        def verify_assignees_applied!(resource, response)
+          applied_ids = [*response.dig(:features, :assignees)].pluck(:id)
+          missing = assignee_ids - applied_ids
+          return if missing.empty?
+
+          raise UpdateNotAppliedError,
+            "Assignees were not applied to #{resource[:web_url]}; the token may lack permission."
+        end
+
+        def labels_url(scope)
+          scope_source, scope_id = scope
+
+          UrlBuilders::UrlBuilder.new(
+            network_options: network.options,
+            source: scope_source,
+            source_id: scope_id,
+            resource_type: 'labels',
+            params: { per_page: 100 }
+          ).build
+        end
+
+        def users_url(username)
+          options = network.options
+
+          "#{options.host_url}/api/#{options.api_version}/users?username=#{CGI.escape(username)}"
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/action.rb

@@ -6,6 +6,7 @@ require_relative 'action/comment_on_summary'
 require_relative 'action/issue'
 require_relative 'action/delete'
 require_relative 'action/work_item_status'
+require_relative 'action/work_item'
 
 module Gitlab
   module Triage
@@ -13,18 +14,34 @@ module Gitlab
       def self.process(policy:, **args)
         policy.validate!
 
-        [
-          [Summarize, policy.summarize?],
-          [Comment, policy.comment?],
-          [CommentOnSummary, policy.comment_on_summary?],
-          [Issue, policy.issue?],
-          [Delete, policy.delete?],
-          [WorkItemStatus, policy.work_item_status?]
-        ].each do |action, active|
+        actions_for(policy).each do |action, active|
           act(action: action, policy: policy, **args) if active
         end
       end
 
+      # 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.
+      def self.actions_for(policy)
+        if policy.type == 'work_items'
+          [
+            [Summarize, policy.summarize?],
+            [WorkItem, policy.work_item?],
+            [CommentOnSummary, policy.comment_on_summary?]
+          ]
+        else
+          [
+            [Summarize, policy.summarize?],
+            [Comment, policy.comment?],
+            [CommentOnSummary, policy.comment_on_summary?],
+            [Issue, policy.issue?],
+            [Delete, policy.delete?],
+            [WorkItemStatus, policy.work_item_status?]
+          ]
+        end
+      end
+
       def self.act(action:, dry:, **args)
         klass =
           if dry

data/lib/gitlab/triage/engine.rb

@@ -15,6 +15,7 @@ require_relative 'filters/assignee_member_conditions_filter'
 require_relative 'filters/discussions_conditions_filter'
 require_relative 'filters/ruby_conditions_filter'
 require_relative 'filters/work_item_status_conditions_filter'
+require_relative 'filters/work_item_date_conditions_filter'
 require_relative 'limiters/date_field_limiter'
 require_relative 'action'
 require_relative 'policies/rule_policy'
@@ -31,6 +32,9 @@ 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 'sources/work_items_rest_source'
+require_relative 'validators/params_validator'
+require_relative 'validators/policy_validator'
 require_relative 'ui'
 require_relative 'api_observability'
 
@@ -46,7 +50,8 @@ module Gitlab
         date: {
           'branches' => Filters::BranchDateFilter,
           'issues' => Filters::IssueDateConditionsFilter,
-          'merge_requests' => Filters::MergeRequestDateConditionsFilter
+          'merge_requests' => Filters::MergeRequestDateConditionsFilter,
+          'work_items' => Filters::WorkItemDateConditionsFilter
         },
         protected: Filters::BranchProtectedFilter,
         assignee_member: Filters::AssigneeMemberConditionsFilter,
@@ -63,7 +68,8 @@ module Gitlab
       DEFAULT_GRAPHQL_ADAPTER = Gitlab::Triage::NetworkAdapters::GraphqlAdapter
       ALLOWED_STATE_VALUES = {
         issues: %w[opened closed],
-        merge_requests: %w[opened closed merged]
+        merge_requests: %w[opened closed merged],
+        work_items: %w[opened closed]
       }.with_indifferent_access.freeze
       MILESTONE_TIMEBOX_VALUES = %w[none any upcoming started].freeze
       ITERATION_SELECTION_VALUES = %w[none any].freeze
@@ -89,6 +95,8 @@ module Gitlab
       end
 
       def perform
+        Validators::PolicyValidator.new(resource_rules).validate!
+
         puts "Performing a dry run.\n\n" if options.dry_run
 
         unless options.quiet
@@ -125,6 +133,11 @@ module Gitlab
         @graphql_network ||= GraphqlNetwork.new(graphql_network_adapter)
       end
 
+      def work_items_source
+        @work_items_source ||= Sources::WorkItemsRestSource.new(
+          network: network, options: options, per_page: per_page)
+      end
+
       private
 
       def assert_options!
@@ -192,7 +205,7 @@ module Gitlab
         resource_reference = options.resource_reference
 
         case resource_type
-        when 'issues'
+        when 'issues', 'work_items'
           resource_reference.start_with?('#')
         when 'merge_requests'
           resource_reference.start_with?('!')
@@ -429,6 +442,8 @@ module Gitlab
       end
 
       def fetch_resources(resource_type, expanded_conditions, rule_definition)
+        return fetch_work_items(expanded_conditions) if resource_type == 'work_items'
+
         resources = []
 
         if rule_definition[:api] == 'graphql'
@@ -476,6 +491,21 @@ module Gitlab
         resources
       end
 
+      def fetch_work_items(expanded_conditions)
+        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
+
+        work_items_source.list(conditions)
+      end
+
       def attach_resource_type(resources, resource_type)
         resources.each { |resource| resource[:type] = resource_type }
       end

data/lib/gitlab/triage/filters/work_item_date_conditions_filter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'issue_date_conditions_filter'
+
+module Gitlab
+  module Triage
+    module Filters
+      class WorkItemDateConditionsFilter < IssueDateConditionsFilter
+      end
+    end
+  end
+end

data/lib/gitlab/triage/network.rb

@@ -37,6 +37,10 @@ module Gitlab
         restapi.post_api(...)
       end
 
+      def patch_api(...)
+        restapi.patch_api(...)
+      end
+
       def delete_api(...)
         restapi.delete_api(...)
       end

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

@@ -62,6 +62,30 @@ module Gitlab
           }
         end
 
+        def patch(token, url, body)
+          response = HTTParty.patch(
+            url,
+            body: body.to_json,
+            headers: {
+              'User-Agent' => USER_AGENT,
+              'Content-type' => 'application/json',
+              'PRIVATE-TOKEN' => token
+            }
+          )
+
+          raise_on_unauthorized_error!(response)
+          raise_on_internal_server_error!(response)
+          raise_on_too_many_requests!(response)
+
+          tracker&.record('PATCH', url)
+
+          {
+            results: response.parsed_response,
+            ratelimit_remaining: response.headers['ratelimit-remaining'].to_i,
+            ratelimit_reset_at: Time.at(response.headers['ratelimit-reset'].to_i)
+          }
+        end
+
         def delete(token, url)
           response = HTTParty.delete(
             url,

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+
+module Gitlab
+  module Triage
+    module Normalizers
+      # Translates a raw Work Items REST API payload into the flat,
+      # issue-shaped resource hash the rest of the gem expects (integer id,
+      # iid, state as opened/closed, labels as title strings, assignees and
+      # author as hashes). This is the single place that knows the Work Items
+      # REST wire shape: the sparse `fields` payload and the nested `features`
+      # object with its labels/assignees/status widgets.
+      class WorkItemNormalizer
+        def call(raw)
+          resource = raw.deep_transform_keys(&:underscore).with_indifferent_access
+          features = resource[:features] || {}
+
+          namespace = resource[:namespace] || {}
+
+          {
+            id: resource[:id],
+            iid: resource[:iid],
+            web_url: resource[:web_url],
+            title: resource[:title],
+            state: resource[:state],
+            confidential: resource[:confidential],
+            created_at: resource[:created_at],
+            updated_at: resource[:updated_at],
+            author: resource[:author],
+            labels: label_titles(features),
+            assignees: assignees(features),
+            milestone: features[:milestone],
+            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),
+            due_date: features.dig(:start_and_due_date, :due_date),
+            namespace: namespace.presence,
+            group_id: group_id_for(namespace),
+            type: 'work_items'
+          }.compact.with_indifferent_access
+        end
+
+        private
+
+        # The list endpoint exposes the containing namespace, not a legacy
+        # project id. For a group namespace, `namespace.id` IS the legacy group
+        # id, so we can surface `group_id` directly - that lets the resource's
+        # group-scoped helpers build `/groups/:id/...` URLs unchanged.
+        #
+        # For a project namespace, `namespace.id` is the project-namespace id,
+        # which is NOT the legacy project id and is useless for `/projects/:id`
+        # endpoints. We deliberately do NOT map it to `project_id`; the source
+        # resolves the real project id from `namespace.full_path` instead (it
+        # needs the network, so it cannot happen here).
+        def group_id_for(namespace)
+          namespace[:id] if namespace[:kind] == 'group'
+        end
+
+        def label_titles(features)
+          [*features.dig(:labels, :labels)].pluck(:title)
+        end
+
+        def assignees(features)
+          [*features[:assignees]]
+        end
+
+        def status_name(features)
+          features.dig(:status, :status, :name)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/policies/base_policy.rb

@@ -71,6 +71,10 @@ module Gitlab
           actions.key?(:work_item_status)
         end
 
+        def work_item?
+          (actions.keys.map(&:to_sym) & %i[labels assignees]).any?
+        end
+
         def build_issue
           raise NotImplementedError
         end

data/lib/gitlab/triage/resource/context.rb

@@ -7,6 +7,7 @@ require_relative 'linked_issue'
 require_relative 'merge_request'
 require_relative 'instance_version'
 require_relative 'branch'
+require_relative 'work_item'
 
 module Gitlab
   module Triage

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'shared/issuable'
+
+module Gitlab
+  module Triage
+    module Resource
+      class WorkItem < Base
+        include Shared::Issuable
+
+        DATE_FIELDS = %i[
+          start_date
+          due_date
+        ].freeze
+
+        DATE_FIELDS.each do |field|
+          define_field(field) do
+            value = resource[field]
+
+            Date.parse(value) if value
+          end
+        end
+
+        def work_item_type
+          resource[:work_item_type]
+        end
+
+        def work_item_status
+          resource[:work_item_status]
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/rest_api_network.rb

@@ -90,6 +90,28 @@ module Gitlab
         end
       end
 
+      def patch_api(url, body)
+        response = execute_with_retry(
+          exception_types: [Net::ReadTimeout, Errors::Network::InternalServerError],
+          backoff_exceptions: Errors::Network::TooManyRequests, debug: options.debug) do
+          puts Gitlab::Triage::UI.debug "patch_api: #{url}" if options.debug
+
+          @adapter.patch(token, url, body)
+        end
+
+        rate_limit_debug(response) if options.debug
+        rate_limit_wait(response)
+
+        results = response.delete(:results)
+
+        case results
+        when Hash
+          results.with_indifferent_access
+        else
+          raise_unexpected_response(results)
+        end
+      end
+
       def delete_api(url)
         response = execute_with_retry(
           exception_types: [Net::ReadTimeout, Errors::Network::InternalServerError],

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

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+
+require_relative '../url_builders/url_builder'
+require_relative '../normalizers/work_item_normalizer'
+require_relative '../errors'
+require_relative '../ui'
+
+module Gitlab
+  module Triage
+    module Sources
+      # Fetches and updates work items through the GitLab Work Items REST API.
+      #
+      # Unlike the legacy issues REST API, the Work Items REST list endpoint
+      # applies no default base-type filter, so work items of any type -
+      # including custom, namespace-defined types - are returned and can be
+      # matched by name via the `work_item_type_names` filter.
+      #
+      # 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.
+      class WorkItemsRestSource
+        UnavailableError = Class.new(StandardError)
+        ScopeError = 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
+        # template reads must be requested here or it comes back nil.
+        LIST_FIELDS = %w[
+          state
+          confidential
+          created_at
+          updated_at
+          web_url
+          author
+          namespace
+          work_item_type
+        ].freeze
+
+        # Widget payloads opted into via `features`.
+        LIST_FEATURES = %w[
+          labels
+          assignees
+          milestone
+          status
+          start_and_due_date
+        ].freeze
+
+        def initialize(network:, options:, per_page: 100, normalizer: Normalizers::WorkItemNormalizer.new)
+          @network = network
+          @options = options
+          @per_page = per_page
+          @normalizer = normalizer
+        end
+
+        def list(conditions)
+          raw = @network.query_api(build_list_url(conditions))
+
+          raise_if_unavailable!(raw)
+
+          raw.map { |item| resolve_project_id!(@normalizer.call(item)) }
+        end
+
+        def update(resource, features)
+          @network.patch_api(work_item_url(resource), features: features)
+        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
+        # lookups must target the resource's namespace, not the run-level
+        # source.
+        def scope_for(resource)
+          return ['projects', resource[:project_id]] if resource[:project_id]
+          return ['groups', resource[:group_id]] if resource[:group_id]
+
+          # A project item whose legacy project id could not be resolved must
+          # not fall back to the run-level scope: on a group run the same iid
+          # can name a different, visible work item there.
+          if resource.dig(:namespace, :kind) == 'project'
+            raise ScopeError,
+              "Cannot resolve the project for work item #{resource[:web_url] || resource[:iid]}; " \
+                'the token may lack access to its project.'
+          end
+
+          [@options.source, @options.source_id]
+        end
+
+        private
+
+        # The normalizer surfaces `group_id` directly for group-namespace items
+        # (namespace.id == legacy group id) but cannot supply a `project_id` for
+        # project-namespace items, because the list payload only carries the
+        # project-namespace id and full path, not the legacy project id that the
+        # gem's project-scoped resource helpers need. Resolve it here from the
+        # full path, cached per run, so that a group-spanning run makes at most
+        # one lookup per distinct project - and only for project items.
+        def resolve_project_id!(resource)
+          namespace = resource[:namespace]
+          return resource unless namespace && namespace[:kind] == 'project'
+
+          full_path = namespace[:full_path]
+          return resource if full_path.blank?
+
+          project_id = project_id_by_full_path(full_path)
+          resource[:project_id] = project_id if project_id
+
+          resource
+        end
+
+        def project_id_by_full_path(full_path)
+          @project_ids_by_full_path ||= {}
+          return @project_ids_by_full_path[full_path] if @project_ids_by_full_path.key?(full_path)
+
+          project = @network.query_api_cached(project_url(full_path)).first
+          @project_ids_by_full_path[full_path] = project && project[:id]
+        end
+
+        def project_url(full_path)
+          UrlBuilders::UrlBuilder.new(
+            network_options: @options,
+            source: 'projects',
+            source_id: full_path
+          ).build
+        end
+
+        # The Work Items REST API is behind the :work_item_rest_api feature
+        # flag. When it is off, or the token lacks access, or the endpoint is
+        # absent, the response is an error hash (e.g. a 403 "feature flag is
+        # disabled" or a 404). The adapter does not raise on those, so without
+        # this guard the error hash would be normalized into a bogus resource
+        # and the run would silently match nothing - which in an automation
+        # tool looks like "all clear". Raise a clear, actionable error instead.
+        def raise_if_unavailable!(raw)
+          error = raw.find { |item| item.is_a?(Hash) && item[:iid].blank? && (item[:message] || item[:error]) }
+          return unless error
+
+          message = error[:message] || error[:error]
+
+          raise UnavailableError,
+            "The Work Items REST API is not available (#{message}). " \
+              'Ensure the :work_item_rest_api feature flag is enabled and the ' \
+              'token has sufficient access.'
+        end
+
+        def build_list_url(conditions)
+          UrlBuilders::UrlBuilder.new(
+            network_options: @options,
+            source: @options.source,
+            source_id: @options.source_id,
+            resource_type: '-/work_items',
+            params: list_params(conditions)
+          ).build
+        end
+
+        def work_item_url(resource)
+          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]
+          ).build
+        end
+
+        def list_params(conditions)
+          params = {
+            per_page: @per_page,
+            fields: LIST_FIELDS.join(','),
+            features: LIST_FEATURES.join(',')
+          }
+
+          apply_filters(params, conditions)
+
+          params
+        end
+
+        # Push-down: map work_items conditions to Work Items REST query params.
+        # `type` uses `work_item_type_names`, which resolves names (including
+        # custom types) case-insensitively server-side - no id resolution
+        # needed.
+        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]
+          params[:state] = conditions[:state] if conditions[:state]
+          params[:label_name] = Array(conditions[:labels]).join(',') if conditions[:labels]
+          params['not[label_name]'] = Array(conditions[:forbidden_labels]).join(',') if conditions[:forbidden_labels]
+          params[:assignee_usernames] = Array(conditions[:assignees]).join(',') if conditions[:assignees]
+          params['status[name]'] = conditions[:status] if conditions[:status]
+
+          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)
+
+          boundary = date_boundary(date_condition)
+          return unless boundary
+
+          direction = condition == 'older_than' ? 'before' : 'after'
+          params["#{attribute.delete_suffix('_at')}_#{direction}"] = boundary.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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Triage
+    module Validators
+      # Validates policy definitions at load time, before any resource is
+      # fetched or acted on. Triage typically runs unattended and scheduled,
+      # so an unsupported policy must be rejected up front rather than raising
+      # partway through a run (which could leave a rule half-applied and fail
+      # where nobody sees it).
+      class PolicyValidator
+        UnsupportedActionError = 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.
+        # Unlike the legacy resource types, work_items have no quick-actions
+        # comment fallback for unrecognized keys, so anything outside this
+        # list would silently do nothing - reject it up front instead.
+        SUPPORTED_WORK_ITEM_ACTIONS = %i[labels assignees summarize comment_on_summary].freeze
+
+        def initialize(resource_rules)
+          @resource_rules = resource_rules || {}
+        end
+
+        def validate!
+          @resource_rules.each do |resource_type, policy_definition|
+            next unless resource_type.to_s == 'work_items'
+
+            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)
+
+            unsupported = actions.keys.map(&:to_sym) - SUPPORTED_WORK_ITEM_ACTIONS
+            next if unsupported.none?
+
+            raise UnsupportedActionError,
+              "Unsupported action(s) for work_items policies: #{unsupported.join(', ')}. " \
+                "Supported actions: #{SUPPORTED_WORK_ITEM_ACTIONS.join(', ')}."
+          end
+        end
+
+        # Every place a policy definition can carry actions: 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] || {} }
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module Triage
-    VERSION = '1.52.0'
+    VERSION = '1.53.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-triage
 version: !ruby/object:Gem::Version
-  version: 1.52.0
+  version: 1.53.0
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-14 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -239,6 +239,7 @@ files:
 - lib/gitlab/triage/action/delete.rb
 - lib/gitlab/triage/action/issue.rb
 - lib/gitlab/triage/action/summarize.rb
+- lib/gitlab/triage/action/work_item.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
@@ -275,6 +276,7 @@ files:
 - lib/gitlab/triage/filters/no_additional_labels_conditions_filter.rb
 - lib/gitlab/triage/filters/ruby_conditions_filter.rb
 - lib/gitlab/triage/filters/votes_conditions_filter.rb
+- lib/gitlab/triage/filters/work_item_date_conditions_filter.rb
 - lib/gitlab/triage/filters/work_item_status_conditions_filter.rb
 - lib/gitlab/triage/graphql_network.rb
 - lib/gitlab/triage/graphql_queries/query_builder.rb
@@ -288,6 +290,7 @@ files:
 - lib/gitlab/triage/network_adapters/graphql_adapter.rb
 - lib/gitlab/triage/network_adapters/httparty_adapter.rb
 - lib/gitlab/triage/network_adapters/test_adapter.rb
+- lib/gitlab/triage/normalizers/work_item_normalizer.rb
 - lib/gitlab/triage/option_parser.rb
 - lib/gitlab/triage/options.rb
 - lib/gitlab/triage/param_builders/date_param_builder.rb
@@ -308,13 +311,16 @@ files:
 - lib/gitlab/triage/resource/merge_request.rb
 - lib/gitlab/triage/resource/milestone.rb
 - lib/gitlab/triage/resource/shared/issuable.rb
+- lib/gitlab/triage/resource/work_item.rb
 - lib/gitlab/triage/rest_api_network.rb
 - lib/gitlab/triage/retryable.rb
+- lib/gitlab/triage/sources/work_items_rest_source.rb
 - lib/gitlab/triage/ui.rb
 - lib/gitlab/triage/url_builders/url_builder.rb
 - lib/gitlab/triage/utils.rb
 - lib/gitlab/triage/validators/limiter_validator.rb
 - lib/gitlab/triage/validators/params_validator.rb
+- lib/gitlab/triage/validators/policy_validator.rb
 - lib/gitlab/triage/version.rb
 - support/.gitlab-ci.example.yml
 - support/.triage-policies.example.yml