Jira actions: Extension pack or legacy pack?

Glean provides two separate Jira action packs, each with different capabilities, supported deployments, and payload formats. Choosing the wrong pack — or mixing them up — is the most common source of Jira action failures.

The two packs at a glance

	Jira Extension Actions	Legacy Jira Actions
Where to find it	Admin console → Actions → "Jira Extension Actions"	Admin console → Actions → "Jira"
Deployment support	Jira Cloud only	Jira Cloud + Server + Data Center
Status	Beta	GA
Payload format for rich text fields	ADF (Atlassian Document Format)	Plain text / rest/api/2
Rich text support	Bold, italic, code blocks, tables, @mentions	Plain text only
@mention support	Native Atlassian account ID mentions	Not supported
Action count	15+ actions (create, edit, search, comment, JSM)	4 core actions
Multi-instance support	One pack per Jira instance	One pack per Jira instance

ADF (Atlassian Document Format)

Atlassian Document Format (ADF) is a structured JSON schema that Jira Cloud uses internally to represent rich text in fields like description, comment, and other rich-text custom fields. Instead of sending a plain string, the action sends a JSON object:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "This is a " },
        { "type": "text", "text": "bold", "marks": [{ "type": "strong" }] },
        { "type": "text", "text": " comment." }
      ]
    }
  ]
}

Why use ADF

Jira Cloud's REST API v3 (used by the Extension Actions pack) requires ADF for all rich text fields. Sending a plain string to a description or comment field on Jira Cloud v3 will either:

• Fail silently — the field is saved as empty.
• Throw a 400 error — the API rejects the payload entirely.

The legacy Jira Actions pack uses REST API v2, which accepts plain strings — this is why it works on Server and Data Center but can't produce rich formatted output on Cloud.

Choose the right Jira pack

Use Jira Extension Actions if:

• Your Jira deployment is Cloud.
• You need formatted comments (code blocks, tables, mentions).
• You're building agents that create or update tickets with structured content.
• You need @mention to notify specific team members.

Use Legacy Jira Actions if:

• Your Jira deployment is Server or Data Center.
• You need GA-stable actions with no beta risk.
• You only need plain text descriptions and comments.

Important

Don't enable both packs simultaneously for the same Jira instance unless you're intentionally migrating. Having both active causes the agent to pick unpredictably between them, leading to inconsistent formatting behavior.

ADF in practice: what the LLM sends

When a user asks Glean to "create a Jira ticket with a code block in the description," the LLM constructs an ADF payload automatically using Glean's Jira skill. You don't need to write ADF manually — the LLM handles the conversion.

However, the LLM only produces correct ADF if:

1. The Jira Extension Actions pack is enabled (not the legacy pack).
2. The action is enabled for the correct surface (Agents and/or Chat).
3. The field being written to is a rich text field in Jira (type: doc).

For plain text fields (type: string), ADF isn't required and shouldn't be used — the action handles this distinction automatically.

Common issues and fixes

Comment posts as plain text with no formatting

Cause: The legacy Jira Actions pack is active instead of Extension Actions.

Fix: Switch to the Jira Extension Actions pack. Verify under Admin console → Actions that "Jira Extension Actions" is enabled and "Jira" (legacy) is disabled for the same instance.

@mention appears as plain text

For example, @john.doe shows as text instead of a real mention.

Cause: The legacy pack doesn't support ADF mentions. The Extension Actions pack resolves @mentions to Atlassian account IDs automatically.

Fix: Use the Jira Extension Actions pack.

400 error when creating or commenting on a Jira Cloud ticket

Cause: A plain text string was sent to a REST API v3 rich text field.

Fix: Confirm the Extension Actions pack is enabled. If the error persists, check whether the target field is a custom field of type string — those require plain text and reject ADF.

Action works in an agent but not on Jira Server/DC

Cause: The Extension Actions pack is Cloud only.

Fix: Use the legacy Jira Actions pack for Server/DC deployments. Rich formatting isn't available on Server/DC.

Setting up Jira Extension Actions

1. Navigate to Glean Admin console.
2. Click Platform → Actions.
3. Click Add action pack and search for Jira Extension Actions.
4. Complete OAuth authentication using a Jira Cloud admin account.
5. Under Edit settings, enable the specific actions you need for Agents and/or Chat.
6. Disable the legacy Jira pack for the same instance to avoid conflicts.

For multi-instance setups (more than one Jira Cloud org), add one Jira Extension Actions pack per instance and name them clearly (for example, "Jira Extension — Engineering" and "Jira Extension — Support").

For any further questions or issues, reach out to the Glean support team.