Work with Comments

Learn how to add plain text or Markdown comments to work items with Issues.addComment and how HAPI converts Markdown to Atlassian Document Format.

Jira stores comment content in Atlassian Document Format (ADF), a structured JSON format. With HAPI, you can write comments in Markdown instead of building ADF yourself.

Pattern for adding comments with HAPI

When you add a comment with HAPI, you can follow this basic pattern:

Import Issues from @scriptrunnerhq/hapi/issues.
Call Issues.addComment inside your script's default async function.
Provide the work item key and a comment body (supports markdown‑style formatting).

The following example shows this general pattern:

import * as Issues from '@scriptrunnerhq/hapi/issues'
 
export default async function () {
  await Issues.addComment('WORKITEM_KEY', {
    body: 'my comment with **markdown**',
  })
}

You can use the same Issues.addComment pattern to add any plain‑text or markdown‑formatted comment to a work item.

Markdown to ADF conversion

HAPI accepts Markdown for rich-text fields such as comments and descriptions, and automatically converts it to Atlassian Document Format (ADF), the format Jira stores. We recommend you use plain Markdown when building out your comments. For example:

await Issues.addComment('JRA-1', { body: 'Deployed **v2.1** — see the runbook.' }).

In-app example scripts

The following example is available in‑app:

Add a comment to a work item: Shows how to use Issues.addComment with a work item key and a markdown‑formatted body to add a comment to an existing work item.