jira-to-docs

Generate polished release notes from Jira Cloud issues. The tool fetches completed issues by date range or sprint, uses OpenAI to classify them, rewrite descriptions, and produce narrative summaries, then outputs both Markdown and HTML files.

Prerequisites

You will need:

1. Python 3.10 or newer -- check by running:

   python3 --version

   If you don't have Python installed, download it from python.org or use your system's package manager (e.g. brew install python on macOS).

2. uv (a fast Python package manager) -- install it by running:

   curl -LsSf https://astral.sh/uv/install.sh | sh

   After installing, restart your terminal so the uv command is available.

3. A Jira Cloud account with an API token. You can create one at: https://id.atlassian.com/manage-profile/security/api-tokens

4. An OpenAI API key (optional but recommended). Get one at: https://platform.openai.com/api-keys

   Without this, the tool still works using --skip-llm mode -- you just won't get the AI-generated narratives and rewritten descriptions.

Setup

1. Clone the repository and navigate into it:

   git clone <repository-url>
   cd jira-to-docs

2. Install dependencies:

   uv sync

   This reads pyproject.toml, creates a virtual environment automatically, and installs everything. You do not need to create a virtual environment yourself.

3. Create your configuration file. Copy the example and fill in your values:

   cp .env.example .env

   Then open .env in any text editor and fill in:

   JIRA_URL=https://your-domain.atlassian.net
   JIRA_EMAIL=your-email@example.com
   JIRA_API_TOKEN=your-api-token
   JIRA_PROJECT=MYPROJECT
   OPENAI_API_KEY=sk-...
   

   • JIRA_URL -- your Atlassian site URL (no trailing slash)
   • JIRA_EMAIL -- the email address you log into Jira with
   • JIRA_API_TOKEN -- the API token you created in step 3 of Prerequisites
   • JIRA_PROJECT -- your Jira project key (e.g. PROJ). This is the prefix that appears on your tickets like PROJ-123. Optional if you always pass --project on the command line.
   • OPENAI_API_KEY -- your OpenAI API key. Leave blank if you plan to use --skip-llm.

   Important: The .env file contains secrets. Do not commit it to version control.

Usage

All commands are run with uv run, which automatically uses the correct virtual environment.

Generate release notes by sprint (recommended)

uv run jira-to-docs --sprint "Sprint 7"

You can specify multiple sprints:

uv run jira-to-docs --sprint "Sprint 5" "Sprint 6" "Sprint 7"

Generate release notes by date range

uv run jira-to-docs --start-date 2026-02-01 --end-date 2026-02-25

Skip AI processing

If you don't have an OpenAI API key or want faster output without AI-generated narratives:

uv run jira-to-docs --sprint "Sprint 7" --skip-llm

All options

Option	Description
--sprint	One or more sprint names to query
--start-date	Start of date range (YYYY-MM-DD)
--end-date	End of date range (YYYY-MM-DD)
--project	Jira project key (overrides .env)
--output-dir	Where to save files (default: output/)
--statuses	Done statuses to look for (default: Done)
--llm-model	OpenAI model to use (default: gpt-5.2)
--skip-llm	Disable AI features, use basic categorization

Note: Use either --sprint or --start-date/--end-date, not both.

Output

The tool generates two files in the output/ directory (or wherever --output-dir points):

• Markdown (.md) -- suitable for pasting into Confluence, GitHub, Slack, etc.
• HTML (.html) -- open in any browser for a styled, shareable view

Each file contains two sections:

1. Release Highlights -- AI-generated narrative summaries of new features, bug fixes, and infrastructure changes
2. Team Internal Summary -- a metrics overview table plus per-sprint tables with ticket IDs, descriptions, details, links, types, and reporters

Troubleshooting

"Missing Jira credentials" error

Make sure your .env file exists in the project root and has JIRA_URL, JIRA_EMAIL, and JIRA_API_TOKEN filled in. Double-check there are no extra spaces around the = signs.

"No issues found"

• Verify your project key is correct (--project or JIRA_PROJECT in .env)
• Check that the sprint name matches exactly what's in Jira (case-sensitive)
• Make sure the issues have been moved to "Done" status (or adjust with --statuses)

LLM errors

If the OpenAI call fails (invalid key, rate limit, etc.), the tool automatically falls back to basic heuristic mode and prints a warning. Your release notes will still be generated, just without the AI-written narratives.

"command not found: uv"

Restart your terminal after installing uv, or run the install command from the Prerequisites section again.