jps-jira-utils 0.10.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
• 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

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 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
├── 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_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