Add support for updating Jira issue status

JIRA: RHELWF-13506

Assisted-by: Opus 4.6

Author: hluk

src/retasc/jira_client.py

@@ -1,5 +1,6 @@
 import logging
 from functools import cached_property
+from unittest.mock import ANY
 
 from atlassian import Jira
 from opentelemetry import trace
@@ -132,6 +133,30 @@ def add_comment(self, issue_key: str, comment: str) -> dict:
 
         raise RuntimeError(f"Unexpected response: {data!r}")
 
+    @tracer.start_as_current_span("JiraClient.get_issue_transitions")
+    def get_issue_transitions(self, issue_key: str) -> list[dict]:
+        """
+        Get available transitions for a Jira issue.
+
+        :param issue_key: The key of the Jira issue.
+        :return: list of dicts with keys: name, id, to
+        """
+        data = self.jira.get_issue_transitions(issue_key)
+        if isinstance(data, list):
+            return data
+
+        raise RuntimeError(f"Unexpected response: {data!r}")
+
+    @tracer.start_as_current_span("JiraClient.transition_issue")
+    def transition_issue(self, issue_key: str, transition_id: str) -> None:
+        """
+        Transition a Jira issue using a transition ID.
+
+        :param issue_key: The key of the Jira issue.
+        :param transition_id: The ID of the transition to execute.
+        """
+        self.jira.set_issue_status_by_transition_id(issue_key, transition_id)
+
     @tracer.start_as_current_span("JiraClient.get_issue_comments")
     def get_issue_comments(self, issue_key: str) -> dict:
         """
@@ -162,6 +187,14 @@ def add_comment(self, issue_key: str, comment: str) -> dict:
         # Skip adding comments in dry-run mode and return dummy data.
         return {"id": "1", "body": comment}
 
+    def get_issue_transitions(self, issue_key: str) -> list[dict]:
+        # Return a catch-all transition so status updates never fail in dry-run.
+        return [{"id": "0", "name": "Dry Run", "to": ANY}]
+
+    def transition_issue(self, issue_key: str, transition_id: str) -> None:
+        # Skip transitioning issues in dry-run mode.
+        pass
+
     def get_issue_comments(self, issue_key: str) -> dict:
         # Skip fetching comments in dry-run mode and return empty list.
         return {"comments": []}

src/retasc/models/prerequisites/jira_issue.py

@@ -9,6 +9,7 @@
 from pydantic import Field
 
 from retasc.models.prerequisites.exceptions import PrerequisiteUpdateStateError
+from retasc.models.prerequisites.jira_status import update_issue_status
 from retasc.models.release_rule_state import ReleaseRuleState
 from retasc.utils import to_comma_separated
 from retasc.yaml import yaml
@@ -29,7 +30,9 @@
     ' relative to the "jira_template_path" configuration.'
 )
 FIELDS_DESCRIPTION = "Jira fields, override fields in the template"
-JIRA_REQUIRED_FIELDS = frozenset(["labels", "resolution"])
+JIRA_REQUIRED_FIELDS = frozenset(
+    ["issuetype", "labels", "project", "resolution", "status"]
+)
 
 
 def _is_resolved(issue: dict) -> bool:
@@ -219,6 +222,25 @@ class JiraIssueTemplate(PrerequisiteBase):
             "and a comment with the same text does not exist already."
         ),
     )
+    status: str | None = Field(
+        default=None,
+        description=(
+            "Optional Jinja2 template for the desired Jira issue status. "
+            "If set, the issue will be transitioned to this status."
+        ),
+    )
+    transitions: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Ordered list of intermediate statuses to try when the target"
+            " status is not directly reachable. At each step, ReTaSC first"
+            " attempts a direct transition to the target status. If that is"
+            " not available, it picks the latest (rightmost) status from the"
+            " remaining intermediates that is available as a Jira transition,"
+            " executes it, and repeats. Entries at or before the issue's"
+            " current status are skipped automatically."
+        ),
+    )
 
     def _update_issue_data(
         self,
@@ -267,6 +289,9 @@ def _update_issue(
             if self.comment is not None:
                 _add_issue_comment(issue["key"], self.comment, context)
 
+        if self.status is not None:
+            update_issue_status(issue, self.status, self.transitions, context)
+
         issue["fields"] = {
             context.config.from_jira_field_name(f): v
             for f, v in issue["fields"].items()

src/retasc/models/prerequisites/jira_status.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+import logging
+
+from retasc.models.prerequisites.exceptions import PrerequisiteUpdateStateError
+
+logger = logging.getLogger(__name__)
+
+
+def _find_transition(transitions: list[dict], status: str) -> dict | None:
+    """Find a transition targeting the given status."""
+    return next((t for t in transitions if t["to"] == status), None)
+
+
+def _find_next_transition(
+    available: list[dict],
+    desired_status: str,
+    remaining: list[str],
+) -> tuple[dict | None, list[str]]:
+    """
+    Pick the next transition to execute.
+
+    Tries the target status first; if unavailable, picks the latest
+    available intermediate from remaining (searching from the end).
+
+    Returns a (transition, new_remaining) tuple, where new_remaining is
+    the slice of the list after the chosen intermediate (or empty when
+    the target status is reached directly).  transition is None when no
+    suitable transition is available.
+    """
+    transition = _find_transition(available, desired_status)
+    if transition is not None:
+        return transition, []
+
+    for i, status in enumerate(reversed(remaining)):
+        transition = _find_transition(available, status)
+        if transition is not None:
+            return transition, remaining[len(remaining) - i :]
+
+    return None, remaining
+
+
+def update_issue_status(
+    issue: dict,
+    status_template: str,
+    transitions: list[str],
+    context,
+) -> None:
+    """
+    Transition a Jira issue to the desired status if needed.
+
+    At each step the algorithm first attempts a direct transition to the
+    target status.  If that is not available, it picks the latest
+    (rightmost) status from the remaining intermediates that is offered
+    as a Jira transition, executes it, and repeats.  Entries at or
+    before the issue's current status are skipped automatically.
+
+    :param issue: The Jira issue dict.
+    :param status_template: Jinja2 template for the desired status.
+    :param transitions: Ordered list of intermediate statuses to try
+        when the target is not directly reachable.
+    :param context: The execution context.
+    :raises PrerequisiteUpdateStateError: If the desired status is unreachable.
+    """
+    desired_status = context.template.render(status_template)
+    current_status = issue["fields"].get("status", {}).get("name", "")
+    remaining = (
+        transitions[transitions.index(current_status) + 1 :]
+        if current_status in transitions
+        else transitions
+    )
+
+    visited = [current_status]
+    while current_status != desired_status:
+        available = context.jira.get_issue_transitions(issue["key"])
+        transition, remaining = _find_next_transition(
+            available, desired_status, remaining
+        )
+        if transition is None:
+            available_names = [t["to"] for t in available]
+            raise PrerequisiteUpdateStateError(
+                f"Cannot transition issue {issue['key']} to {desired_status!r};"
+                f" available transitions: {available_names}"
+            )
+
+        current_status = transition["to"]
+        visited.append(current_status)
+        logger.info(
+            "Transitioning %r to %r via %r",
+            issue["key"],
+            current_status,
+            transition["name"],
+        )
+        context.jira.transition_issue(issue["key"], transition["id"])
+
+    context.report.set("status_transitions", visited)

tests/test_jira_client.py

@@ -170,3 +170,50 @@ def test_unexpected_response_get_issue_comments(jira_api, requests_mock):
     requests_mock.get(f"{JIRA_URL}/rest/api/2/issue/{ISSUE_KEY}/comment", json=[])
     with raises(RuntimeError, match=r"Unexpected response: \[\]"):
         jira_api.get_issue_comments(ISSUE_KEY)
+
+
+TRANSITIONS_URL = f"{JIRA_URL}/rest/api/2/issue/{ISSUE_KEY}/transitions"
+
+TRANSITIONS_RESPONSE = {
+    "transitions": [
+        {"id": "11", "name": "Start Progress", "to": {"name": "In Progress"}},
+        {"id": "21", "name": "Close", "to": {"name": "Closed"}},
+    ]
+}
+
+
+def test_get_issue_transitions(jira_api, requests_mock):
+    requests_mock.get(TRANSITIONS_URL, json=TRANSITIONS_RESPONSE)
+    result = jira_api.get_issue_transitions(ISSUE_KEY)
+    assert result == [
+        {"name": "Start Progress", "id": 11, "to": "In Progress"},
+        {"name": "Close", "id": 21, "to": "Closed"},
+    ]
+
+
+def test_get_issue_transitions_dryrun(dryrun_jira_api, requests_mock):
+    result = dryrun_jira_api.get_issue_transitions(ISSUE_KEY)
+    assert len(result) == 1
+    assert result[0]["to"] == "any status matches"
+    assert len(requests_mock.request_history) == 0
+
+
+def test_transition_issue(jira_api, requests_mock):
+    """Transition issue by transition ID."""
+    requests_mock.post(TRANSITIONS_URL, status_code=204)
+    jira_api.transition_issue(ISSUE_KEY, "21")
+    posts = [r for r in requests_mock.request_history if r.method == "POST"]
+    assert len(posts) == 1
+    # atlassian library converts string ID to int
+    assert posts[0].json() == {"transition": {"id": "21"}}
+
+
+def test_transition_issue_dryrun(dryrun_jira_api, requests_mock):
+    dryrun_jira_api.transition_issue(ISSUE_KEY, "21")
+    assert len(requests_mock.request_history) == 0
+
+
+def test_unexpected_response_get_issue_transitions(jira_api):
+    with patch.object(jira_api.jira, "get_issue_transitions", return_value="bad"):
+        with raises(RuntimeError, match=r"Unexpected response"):
+            jira_api.get_issue_transitions(ISSUE_KEY)