jira-versions

The Atlassian MCP and acli cannot manage versions. Use jira-api
(~/.local/bin/jira-api). It calls the Jira Cloud REST API v3 with curl.

Setup

• JIRA_EMAIL comes from the environment (Claude and Codex set it). Never prefix it on
  the command line. When unset, stop and say so.
• Set JIRA_SITE when the site is not the jira-api default.
• The token comes from JIRA_API_TOKEN or pass show api/jira.
• Check auth: jira-api GET /myself (expect HTTP 200). Its accountId is
  the current user.

Project facts

Read the project key and the version-name format from the repository's
AGENTS.md, AGENTS_PROJECT.md, or skill config. Get projectId from
GET /project/<KEY> (.id).

Commands

Every command is jira-api <METHOD> <path> [json].

• List versions: GET /project/<KEY>/versions
• Read one: GET /version/<id>
• Create:
  POST /version '{"name":"<name>","projectId":<id>,"description":"Created <YYYY-MM-DD> at the request of <name>."}'
• Rename or edit: PUT /version/<id> '{"name":"...","description":"..."}'
• Release:
  PUT /version/<id> '{"released":true,"releaseDate":"<YYYY-MM-DD>","driver":"<accountId>"}'
  (driver: the current user's accountId).
• Archive: PUT /version/<id> '{"archived":true}'
• Delete: DELETE /version/<id> (irreversible).

Output ends with HTTP <code>. 201 means created, 200 means ok.

Move a ticket or MR to a version

1. For an MR/PR number, find the ticket key in its title, branch, or
   description: glab api "projects/:id/merge_requests/<iid>" or
   gh pr view <n> --json title,headRefName,body.
2. Make sure the target version exists (GET /project/<KEY>/versions).
   If not, create it first.
3. Read the ticket's fixVersions. Remove only the unreleased source version.
   Add the target and keep all other versions. To take a ticket out of the
   release, remove only the named version and add none.
4. Write the new list with the Atlassian MCP editJiraIssue
   (fields: {"fixVersions": [{"name": "<name>"}, ...]}). This field replaces
   the full list.
5. If the project labels MRs/PRs by release, change the label. Get the label
   format from the project's release skill or docs. GitLab:
   glab api --method PUT "projects/:id/merge_requests/<iid>" -f "add_labels=<label>" -f "remove_labels=<old>".
   GitHub: gh pr edit <n> --add-label <label> --remove-label <old>.
   Omit removal when the source label is absent or equals the target label.
   Other platforms are unsupported: tell the user and skip this step.
6. Read the ticket and any changed MR/PR again to check the result.

Rules

• Before moving a ticket, check which MR/PR is merged. Merged work stays in
  the version it shipped in.
• Creating or editing a version is visible to the whole team. Delete needs
  user approval. A user request to release a version authorizes the release only, not a delete.