jira

Talk to Jira Cloud or Server/Data Center directly via a bundled Node.js script -- no SDK, no build step.

Prerequisites

• Node.js 18+ (for native fetch).
• Jira credentials, depending on deployment type:
  • Cloud -- an Atlassian account email and an API token from https://id.atlassian.com/manage-profile/security/api-tokens.
  • Server/Data Center -- a Personal Access Token generated from the user's Jira profile's Personal Access Tokens page (not id.atlassian.com -- that's Cloud-only). No email needed.
• Server/Data Center only, if the instance uses a self-signed or internal CA certificate: either the internal CA's certificate file (to set NODE_EXTRA_CA_CERTS, the proper fix) or willingness to accept disabled TLS verification (allowInsecureTls, a last resort). See "Self-signed or internal CA certificates" below.

Quick start

1. Make sure Node.js 18+ is available (node --version).
2. Configure credentials -- see "Setup" below.
3. Run echo '{}' | node scripts/jira.mjs whoami to confirm the credentials resolve and the Jira instance is reachable. If it fails with a "credentials not found" error, the script is not interactive -- it won't prompt for input. Ask the user whether their Jira is Cloud or Server/Data Center, then for their base URL and either a Cloud API token (with account email, generated at https://id.atlassian.com/manage-profile/security/api-tokens) or a Server/DC Personal Access Token (generated from their Jira profile's Personal Access Tokens page, no email needed). Write ~/.jira-credentials.json yourself (see "Setup" below for the exact shape) and retry.
4. Run whatever action you need (see "Running an action" below for the shape, and references/actions.md for every action's exact payload).
5. For anything that changes Jira (create/update/transition/comment/assign/attach), follow "Safety -- always confirm before mutating" below before calling it.

Setup

Credentials resolve from environment variables first, then ~/.jira-credentials.json. Two deployment types are supported, selected by deploymentType (JIRA_DEPLOYMENT_TYPE in env vars) -- it defaults to "cloud" when omitted:

Cloud (deploymentType: "cloud", the default):

• JIRA_BASE_URL -- e.g. https://yourcompany.atlassian.net
• JIRA_EMAIL -- the Atlassian account email
• JIRA_API_TOKEN -- an API token from https://id.atlassian.com/manage-profile/security/api-tokens
• JIRA_PROJECT_KEY -- optional default project (any action can override with its own project/projectKey field)

Server/Data Center (deploymentType: "server"):

• JIRA_BASE_URL -- your company's Jira URL, e.g. https://jira.yourcompany.com
• JIRA_API_TOKEN -- a Personal Access Token, generated from your Jira profile's Personal Access Tokens page (not id.atlassian.com -- that's Cloud-only). No email needed.
• JIRA_PROJECT_KEY -- optional default project, same as Cloud

These are different token types tied to different Jira deployments -- a Cloud API token and a Server/DC Personal Access Token are not interchangeable, and using the wrong deploymentType for a given token will fail auth (401/403).

Or create ~/.jira-credentials.json, e.g. for Cloud:

{ "baseUrl": "https://yourcompany.atlassian.net", "email": "you@example.com", "apiToken": "...", "projectKey": "PROJ" }

or for Server/Data Center:

{ "baseUrl": "https://jira.yourcompany.com", "apiToken": "...", "deploymentType": "server", "projectKey": "PROJ" }

Verify setup by running the whoami action (see below) before doing anything else.

Self-signed or internal CA certificates

If whoami (or any action) fails with a TLS/certificate error against a Server/Data Center instance on an internal domain, the instance's certificate is likely signed by an internal or self-signed CA that Node doesn't trust by default. Two options, in order of preference:

• Set NODE_EXTRA_CA_CERTS to the internal CA's certificate file. This is a standard Node.js environment variable, not specific to this skill, and Node only reads it once at process startup -- setting it in ~/.jira-credentials.json would have no effect, since the credentials file is read after the process has already started. It must exist as a real environment variable before the skill's node process launches, which in practice means setting it persistently at the OS level (a one-time setup step, not something to redo per session):
  • Windows: setx NODE_EXTRA_CA_CERTS "C:\path\to\internal-ca.pem", then restart any terminal/app (including Claude Code) that should pick it up -- setx only affects new processes started after it runs, not the current session.
  • macOS/Linux: add export NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem to your shell profile (~/.zshrc, ~/.bashrc, etc.), then restart your terminal/app. This properly verifies the certificate chain, unlike the option below.
• Set allowInsecureTls (JIRA_ALLOW_INSECURE_TLS=true in env vars, or "allowInsecureTls": true in ~/.jira-credentials.json) only if you can't obtain the CA certificate. This disables TLS certificate verification for this skill's requests -- insecure, last resort.

Running an action

node scripts/jira.mjs <action>

The JSON payload is piped via stdin, not passed as an argument -- this avoids shell-quoting problems with multi-line markdown. Example:

echo '{"issueType":"Bug","summary":"Login button unresponsive"}' | node scripts/jira.mjs create-issue

On success the script prints a JSON result to stdout and exits 0. On failure it prints {"error": "..."} to stderr and exits 1.

See references/actions.md for every action's full payload/response shape and examples.

Choosing a project for create-issue

create-issue's project field is optional and falls back to the configured default (JIRA_PROJECT_KEY / projectKey) when omitted -- but if the user works across more than one project on this Jira site, don't rely on that silently. Before calling create-issue, if the target project isn't already clear from the request or the conversation so far (e.g. they gave an explicit key, or the conversation has been scoped to one project throughout), ask which project to create the issue in. If you're not sure what projects exist, offer to run list-projects first so the user can pick from real options instead of guessing a key. This applies to every issue type -- Epic, Story, Bug, Task, etc. -- not just some of them, since a silently-wrong project is the risk regardless of issue type.

Safety -- always confirm before mutating

Before calling any of create-issue, update-issue, transition-issue, add-comment, set-assignee, or attach-file, show the user exactly what will change (issue key/summary and the specific change) and get explicit confirmation. These calls hit a real Jira instance and are not easily reversible from here.

Read-only actions -- get-issue, search-issues, list-transitions, list-comments, list-projects, list-issue-types, list-fields, whoami -- can run without confirmation.

Known limitations

• No delete-issue action -- delete issues manually in the Jira UI.
• Description/comment markdown supports headings, paragraphs, bullet/numbered lists, bold/italic, inline code, fenced code blocks, and links -- converted to Atlassian Document Format on Cloud, Jira wiki markup on Server/Data Center. Tables, panels, mentions, and emoji are not supported -- content in those forms round-trips as best-effort plain text. Headings and fenced code blocks are recognized even when glued directly to adjacent text (no blank line needed). Bullet/numbered lists still need a blank line separating them from surrounding paragraphs, and nested lists are not supported -- flatten them into a single list or separate top-level lists instead. On Server/Data Center, the wiki-markup conversion round-trips content this skill itself wrote reliably; wiki markup a person hand-authored directly in Jira's web editor may not match this subset and falls back to best-effort plain text.
• One-shot actions only -- this is not a continuous or bidirectional sync of any kind.