create-jira-release

name	create-jira-release
description	Create or update a Jira fix version (release) from a release name, release date, ticket list, and description. Assigns tickets to the fix version. Use when batching DWTA work items into a Jira release, or when another skill needs to create the Jira side of a release workflow.

Create Jira release

Creates or updates a Jira fix version (release) such as Release 4. In Jira this is the fix version name (shown as the release title in the UI) and releaseDate. Today Confluence holds the main release note; Jira releases batch tickets. This skill is composable — other skills (e.g. create-release-note-in-confluence) can call it to create the Jira release first.

Parameters

Parameter	Required	Jira field	Example
Release name (--release-name)	Yes for create	name	Release 5
Release date (--release-date)	Yes for create	releaseDate	2026-05-20
Ticket list (--tickets)	Yes	(assigns fixVersion)	DWTA-154,DWTA-155,DWTA-157
Description	Yes	description	Markdown file or inline text
Project key (--project)	No (default DWTA)	projectId	DWTA
Version ID / URL (--version)	Yes for update	—	38223 or release URL

--name is an alias for --release-name.

Optional on update only:

Parameter	Default	Purpose
--release-date	(unchanged)	Set a new release date on an existing fix version

Other optional flags:

Parameter	Default	Purpose
--description-format	markdown	Input format: markdown, wiki, text, html
--released	false	Mark fix version as released
--related-work-url	(none)	Link a Confluence page (or URL) in Jira Related work
--related-work-title	Release notes	Title shown for the Related work link
--related-work-category	Documentation	Related work category in Jira
--dry-run	—	Validate only; no Jira writes

Release date format: YYYY-MM-DD (ISO date, no time component).

Description format

Jira fix version descriptions are a plain text API field. They do not accept Confluence storage HTML or ADF. Wiki markup is converted for storage but may display as plain text in the Jira UI (including tables).

Input	Handling
Markdown (recommended)	Converted to Jira wiki markup (h2., *bold*, [text|url], lists)
Wiki	Sent as-is
Text	Sent as-is
HTML	Stripped to plain text (structure preserved with line breaks)

Callers should author descriptions in markdown so future release-note layouts can reuse the same source file. When the Confluence release note skill matures, it can read the same markdown and render the Confluence template separately.

Related work (optional formatted link)

The Give this section a name rich text block on the Jira release page cannot be set via API. To surface formatted release notes on the release page, link a Confluence page as Related work instead (Atlassian’s supported pattern).

Pass --related-work-url when you already have a Confluence page URL (typically after publishing the release note):

bash .cursor/skills/create-jira-release/scripts/create-release.sh \
  .tmp/jira-releases/38223 \
  --version 38223 \
  --release-date 2026-05-13 \
  --tickets "DWTA-189" \
  --description-file .tmp/jira-releases/38223/description.md \
  --related-work-url "https://eaflood.atlassian.net/wiki/spaces/WTPG/pages/6518114167" \
  --related-work-title "DWTA - Release 4"

Or link separately:

bash .cursor/skills/create-jira-release/scripts/link-related-work.sh \
  38223 \
  "https://eaflood.atlassian.net/wiki/spaces/WTPG/pages/6518114167" \
  --title "DWTA - Release 4"

Skips duplicate URLs already linked to the version.

When publishing a Confluence release note first, use create-release-note-in-confluence with --link-jira-release instead (see that skill).

Workflow

1. Prepare description

Write a markdown file, for example .tmp/jira-releases/new/description.md:

## Summary

Batch of ext-test fixes for waste movement APIs.

## Services

- waste-movement-backend
- waste-movement-external-api

## Notes

See Confluence release note for deployment details.

2. Check for existing release (create only)

bash .cursor/skills/create-jira-release/scripts/check-existing-release.sh \
  DWTA "Release 5"

• Exit 0 — safe to create
• Exit 1 — release name already exists; use --version to update instead

3. Create release

mkdir -p .tmp/jira-releases/new

bash .cursor/skills/create-jira-release/scripts/create-release.sh \
  .tmp/jira-releases/new \
  --project DWTA \
  --release-name "Release 5" \
  --release-date 2026-05-20 \
  --tickets "DWTA-154,DWTA-155,DWTA-157" \
  --description-file .tmp/jira-releases/new/description.md

4. Update existing release

Use when adding tickets or refreshing the description on an existing fix version:

mkdir -p .tmp/jira-releases/38223

bash .cursor/skills/create-jira-release/scripts/create-release.sh \
  .tmp/jira-releases/38223 \
  --version 38223 \
  --release-date 2026-05-13 \
  --tickets "DWTA-189" \
  --description-file .tmp/jira-releases/38223/description.md

Ticket assignment adds the fix version; it does not remove other fix versions from an issue.

5. Review output

File	Contents
manifest.json	Version ID, URLs, tickets, formatted description
description-source.txt	Original input
description-jira.txt	Wiki/plain text sent to Jira
assignments.json	Per-ticket assign results
related-work.json	Related work link result (when --related-work-url used)

Requires ATLASSIAN_USER and ATLASSIAN_TOKEN. See atlassian-credentials.md.

Ask for user confirmation before creating or updating a release unless the caller skill already obtained it.

Scripts

Script	Purpose
create-release.sh	Create or update fix version, format description, assign tickets
check-existing-release.sh	Detect duplicate release name in project
assign-issues.sh	Add fix version to ticket keys
link-related-work.sh	Add a Related work link to the Jira release page
format-description.py	Convert markdown/html/text to Jira description
resolve-project-id.sh	Resolve project key to numeric ID

Environment

Variable	Default	Purpose
JIRA_PROJECT_KEY	DWTA	Default project key
JIRA_RELATED_WORK_CATEGORY	Documentation	Category for Related work links

Examples

/create-jira-release --release-name "Release 5" --release-date 2026-05-20 --tickets DWTA-154,DWTA-155 --description "Ext-test batch"
/create-jira-release --version 38223 --release-date 2026-05-13 --tickets DWTA-189 --description-file description.md

Dry run:

bash .cursor/skills/create-jira-release/scripts/create-release.sh \
  .tmp/jira-releases/new \
  --project DWTA \
  --release-name "Release 5" \
  --release-date 2026-05-20 \
  --tickets "DWTA-154,DWTA-155" \
  --description-text "Draft release summary" \
  --dry-run

Important constraints

• Release name and date are required for create — maps to Jira fix version name and releaseDate
• Never create a duplicate release name — run check-existing-release.sh first
• Never write to Jira without user confirmation (unless a parent skill already confirmed)
• Use markdown for descriptions — best fit for future Confluence release note layout
• Do not send Confluence HTML to Jira — it will not render
• If any script fails, stop immediately — report the exact error
• Jira releases batch tickets; formatted release notes live in Confluence and can be linked via Related work
• Related work is optional — omit --related-work-url if no Confluence page exists yet

Related skills

• get-jira-release — read release metadata and work items after creation
• create-release-note-in-confluence — Confluence release note from a Jira release
• get-jira-ticket — ticket details for release contents