---
name: tracker/jira-official:issue-transition
description: Transition JIRA issue status
version: "0.5.0"
---

# Issue Transition

> **Backend:** jira-official (atlassian@claude-plugins-official)

> **Note:** Requires `atlassian@claude-plugins-official` plugin. Install: `/plugin install atlassian@claude-plugins-official`

Moves a JIRA issue to a new status by executing a workflow transition.

## Parameters

| Parameter     | Type   | Required | Description                                |
| ------------- | ------ | -------- | ------------------------------------------ |
| issue_key     | string | Yes      | JIRA issue key (e.g., `<PROJECT_KEY>-123`) |
| transition_id | string | Yes      | ID of the workflow transition to perform   |

## Implementation

Uses MCP JIRA tool: `mcp__atlassian__transitionJiraIssue`

```
mcp__atlassian__transitionJiraIssue({
  issue_key: "<issue_key>",
  transition_id: "<transition_id>"
})
```

Common transition IDs (verify against your JIRA project workflow):

**Forward flow:**

| From        | To          | Transition ID |
| ----------- | ----------- | ------------- |
| To Do       | In Progress | 21            |
| In Progress | Done        | 31            |

**Backward / exception flow:**

| From        | To        | Transition ID |
| ----------- | --------- | ------------- |
| In Progress | To Do     | 11            |
| In Progress | Blocked   | 41            |
| In Progress | Cancelled | 51            |

> Note: Direct transitions that skip states (e.g., To Do → Done) are not supported by the standard workflow. Always follow the valid transition paths above.

## Output

| Field          | Type   | Description                          |
| -------------- | ------ | ------------------------------------ |
| status         | string | New status name after the transition |
| transitionedAt | string | ISO 8601 timestamp of the transition |

## Errors

| Code | Cause                                                  | Recovery                                                                         |
| ---- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
| 404  | Issue key not found                                    | Verify the issue key and project key are correct                                 |
| 403  | Insufficient permissions to transition the issue       | Confirm the JIRA user has transition permissions                                 |
| 400  | Invalid `transition_id` for the issue's current status | Retrieve available transitions via the JIRA REST API before calling              |
| 400  | Transition requires a resolution field                 | Set the `resolution` field in the transition call                                |
| MCP  | Plugin unavailable                                     | Verify the `atlassian@claude-plugins-official` plugin is installed and connected |

## Used By

- dev-task (moving issues through the workflow as work progresses)
