jps-jira-utils 0.11.0

Collection of Python scripts for interacting with Jira tickets.

jps-jira-utils

A clean, modular, production-grade toolkit for Jira power users
Built with Typer, rich logging, and full test coverage.

Features

• Unified CLI — jps-jira-utils command with subcommands for all operations
• Create Issues — create_issue.py — Create new Jira issues with all required fields
  • Interactive prompts for issue type, summary, and description
  • Automatic reporter field handling (uses authenticated user)
  • Support for all required fields: Space (project), Work Type, Reporter, Title
  • Full validation and confirmation before creation
• Update Issues — update_issue.py — Bulk update issue fields from YAML configuration
  • Update custom fields (Software Component, PROGRAM, TICKET TYPE, Project Label, Team)
  • Smart sprint assignment (latest sprint matching project key)
  • Automatic date calculations (Due Date, Dev Complete, QA Complete, UAT Start)
  • Business day calculations with configurable defaults
  • Only updates empty fields (preserves existing values)
  • Dry-run mode for validation
• Add Comments — add_comment.py — Add rich comments (with optional file attachments) to any Jira issue
  • Interactive multiline input (ends on two blank lines)
  • Load comment from file (--comment-file)
  • Attach files with pre-canned or custom notes (STDOUT, STDERR, log file, README, etc.)
  • Final confirmation table before posting
  • Full logging with structured output
  • Optional custom config file (--config-file)
• Secure credential loading via ~/.config/jps-jira-utils/.jira.env (never in code or CLI)
• Clean, maintainable, fully tested codebase using modern Python best practices
• Zero external runtime dependencies beyond requests, typer, and python-dotenv

Installation

From source (recommended for development)

git clone https://github.com/jai-python3/jps-jira-utils.git
cd jps-jira-utils
make install    # creates .venv and installs in editable mode

From PyPI (coming soon)

pip install jps-jira-utils

Configuration

Setting up credentials

The tool requires Jira Cloud credentials to authenticate API requests. By default, credentials are loaded from:

~/.config/jps-jira-utils/.jira.env

Auto-create the configuration file

You can automatically create the configuration directory and file with placeholder values:

mkdir -p ~/.config/jps-jira-utils
cat > ~/.config/jps-jira-utils/.jira.env << 'EOF'
JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=[e-mail]
JIRA_API_TOKEN=your_api_token_here
EOF

Then edit the file with your actual credentials:

nano ~/.config/jps-jira-utils/.jira.env
# or use your preferred editor

Manual configuration

Create the configuration directory and file manually:

mkdir -p ~/.config/jps-jira-utils

Then create ~/.config/jps-jira-utils/.jira.env with your Jira Cloud credentials:

JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=[e-mail]
JIRA_API_TOKEN=your_api_token_here

Generate your API token at: https://id.atlassian.com/manage-profile/security/api-tokens

Using a custom config file

If you need to use a different location for your configuration file, you can specify it with the --config-file option:

jps-add-comment JPS-1234 --config-file /path/to/custom/.jira.env

Prerequisites

Python 3.11 or higher is required.

Usage

Unified CLI

View all available commands:

jps-jira-utils --help

Create a new issue

Create an issue interactively:

jps-jira-utils create-issue JPS

Or using the standalone command:

jps-jira-utils-create-issue JPS

Create with all details provided:

jps-jira-utils create-issue JPS \
  --summary "Fix login bug" \
  --issue-type Bug \
  --description "Users cannot log in with SSO"

Required fields for issue creation:

• Space (Project key): e.g., JPS
• Work Type (Issue type): e.g., Task, Bug, Story
• Reporter: Automatically set to authenticated user's email
• Title (Summary): Brief description of the issue

Update issue fields

Update an issue with values from config file:

jps-jira-utils update-issue BISD-1234

Or using the standalone command:

jps-jira-utils-update-issue BISD-1234

With custom config file:

jps-jira-utils update-issue BISD-1234 --config-file ~/my-config.yaml

Dry run to preview changes:

jps-jira-utils update-issue BISD-1234 --dry-run

Configuration file (~/.config/jps-jira-utils/config.yaml):

# Project settings
project_key: "BISD"
board_id: 123

# Custom field values
software_component: "MyComponent"
program: "MyProgram"
ticket_type: "Development"
project_label: "MyProject"
team: "Engineering Team"

# Date calculation settings (in business days)
default_due_date_business_days: 10
default_dev_complete_due_date_business_days: 5
default_qa_complete_due_date_business_days: 2
default_uat_start_date_business_days: 1

What gets updated:

• Software Component (custom field)
• Sprint (latest sprint matching project key)
• PROGRAM, TICKET TYPE, Project Label, Team (custom fields)
• Due Date (Friday after N business days)
• Dev Complete Due Date (Friday after N business days)
• QA Complete Due Date (N business days after Dev Complete)
• UAT Start Date (N business days after QA Complete)
• Assignee (current user)

Note: Only updates fields that are currently empty.

Add a comment to an issue

Add a comment interactively:

jps-jira-utils add-comment JPS-1234

Or using the standalone command:

jps-jira-utils-add-comment JPS-1234

Add a comment from a file + attach a log:

jps-jira-utils add-comment JPS-1234 \
  --comment-file results.txt \
  --attach-file test-run.log

Get help

Full help for any command:

jps-jira-utils --help
jps-jira-utils create-issue --help
jps-jira-utils update-issue --help
jps-jira-utils add-comment --help

Development

# Format, lint, and fix everything
make fix
make format
make lint

Run tests with coverage

make test

Run pre-commit hooks (recommended)

pre-commit run --all-files

Project Structure

src/jps_jira_utils/
├── cli.py                # Main CLI entry point with subcommands
├── create_issue.py       # Create new Jira issues
├── update_issue.py       # Update issue fields from YAML config
├── add_comment.py        # Add comments to Jira issues
├── jira_helper.py        # Credential loading
├── logging_helper.py     # Structured logging setup
└── prompt_helper.py      # Interactive input utilities

tests/                    # Full test coverage with pytest
├── test_cli.py           # CLI tests
├── test_create_issue.py  # Issue creation tests
├── test_update_issue.py  # Issue update tests
├── test_add_comment.py   # Comment addition tests
└── ...

config.yaml.example       # Example YAML configuration file

├── test_add_comment.py # Comment addition tests └── ...

##  Contributing

Contributions are welcome! Please:

Use pre-commit hooks
Write tests for new features
Follow Google-style docstrings
Keep the codebase clean and modular

## License

MIT License © Jaideep Sundaram