Skip to content

Jira Transition Runner

A Python CLI tool (with optional GUI) for bulk Jira issue transitions with hierarchical support and smart planning.

Features

Two-Phase Workflow

  • Phase 1 (Plan) — Generate an Excel plan with dropdown validations and smart target-status defaults
  • Phase 2 (Execute) — Execute approved transitions with parallel processing and retry logic

Version Management

  • Release and archive Jira fix versions in bulk
  • Validation before release (checks for unresolved issues)
  • Supports CLI input or Excel file; dry-run mode available

Hierarchical Issue Processing

  • Automatically discover child issues (subtasks, stories, epics, initiatives)
  • Filter by status category (exclude "Done" items)
  • Track open bugs across hierarchy levels
  • Auto-reject approval when open bugs exist

Smart Target Defaults

  • Auto-populate target_status with the highest-priority reachable status
  • Configurable priority order (e.g., Closed > Done > Cancelled)
  • BFS pathfinding for multi-step transitions
  • Visual indicators (blue bold) in the plan Excel; user can override via dropdown

Reliability

  • Rate-limit handling (respects Retry-After) and exponential backoff
  • Configurable concurrency and retry limits
  • Real-time Rich progress bars

Desktop GUI

  • Full tkinter GUI mirroring all CLI features — no terminal required

Quick Start

# 1. Install
git clone <repository-url>
cd jira-transition-runner
uv sync

# 2. Configure — edit settings.toml (Jira URL, KeePass paths)
cp .env.example .env   # picks the environment: JIRA_ENV=development|staging|production

# 3. Phase 1: generate a plan
jira-runner --project PROJ --yaml transition.yaml \
  --jql "project = PROJ AND status != Done" \
  --plan plan.xlsx --include-children

# 4. Review plan.xlsx, set approved=True for safe rows

# 5. Phase 2: dry-run first, then execute
jira-runner --project PROJ --yaml transition.yaml --execute plan.xlsx --dry-run
jira-runner --project PROJ --yaml transition.yaml --execute plan.xlsx
Section Description
Installation & Configuration Dependencies, settings.toml and environments, workflow YAML, logging
Phase 1 — Plan Generating the Excel plan
Phase 2 — Execute Executing approved transitions
Version Management Releasing and archiving fix versions
GUI Desktop graphical interface
Troubleshooting Common errors and fixes