---
name: tracker/gh-cli:issue-transition
description: Transition a GitHub issue's state (gh-cli implementation; GitHub has only open/closed)
version: "0.4.0"
---

# Issue Transition (GitHub)

gh-cli implementation of the abstract `tracker:issue-transition` operation. **GitHub issues have only two states — `open` and `closed`** — so workflow statuses collapse onto close/reopen:

- Terminal statuses (Done, Closed, Complete, Completed, Resolved, Deployed, Merged, Cancelled) → `gh issue close`
- Active/backlog statuses (Open, Reopen, In Progress, To Do, Backlog) → `gh issue reopen` (no-op if already open)

For finer-grained workflow status on GitHub, apply a status label via `tracker/gh-cli:issue-update` (`--add-label`). For GitHub, the abstract `id` parameter is the issue number.

## Parameters

| Parameter     | Type   | Required | Description                                                 |
| ------------- | ------ | -------- | ----------------------------------------------------------- |
| id            | string | Yes      | Issue identifier (GitHub issue number)                      |
| target_status | string | Yes      | Target status name (mapped onto GitHub's open/closed model) |

## Implementation

```bash
# GitHub only has open/closed — map the target status accordingly.
case "$(echo "{target_status}" | tr '[:upper:]' '[:lower:]')" in
  done|closed|complete|completed|resolved|deployed|merged|cancelled)
    gh issue close {id} --reason completed ;;
  *)
    gh issue reopen {id} ;;
esac
```

## Output

| Field           | Type   | Description                                      |
| --------------- | ------ | ------------------------------------------------ |
| id              | string | Issue identifier                                 |
| previous_status | string | `open` or `closed` (state before the transition) |
| new_status      | string | `open` or `closed` (state after the transition)  |

## Errors

| Code             | Cause                                            | Recovery                     |
| ---------------- | ------------------------------------------------ | ---------------------------- |
| ISSUE_NOT_FOUND  | Issue number does not exist                      | Verify issue number          |
| AUTH_FAILED      | Not authenticated with gh CLI                    | Run `gh auth login`          |
| ALREADY_IN_STATE | Issue is already in the target open/closed state | Safe no-op; no action needed |

## Used By

- deploy-tracker (transition issues after deployment)
- dev-sprint (transition epic status)
