jira v3 description is not Atlassian ADF format

[lerminou]

Migrating from the v2 to the v3 format due to the atlassian deprecation and deletion of the previous API.

I followed the documentation here to set the description

https://prometheus.io/docs/alerting/latest/configuration/#jira_config

Both APIs have the same feature set. The difference is that V2 supports Wiki Markup for the issue description and V3 supports Atlassian Document Format (ADF). The default jira.default.description template only works with V2.

So I set the descrpition to a new template (without any variables just like their example)

https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/

And I got an error in the logs

level=ERROR source=dispatch.go:363 msg="Notify for alerts failed" component=dispatcher num_alerts=2 err="jira/jira[0]: notify retry canceled due to unrecoverable error after 1 attempts: failed to POST request to \"issue\": unexpected status code 400: {\"errorMessages\":[],\"errors\":{\"description\":\"La valeur de l'opération doit être un document Atlassian (voir le format de document Atlassian)\"}}"

I see in the code you try to unmarshal the description: https://github.com/prometheus/alertmanager/blob/main/notify/jira/jira.go#L167-L172

[lerminou]

According to my friend chatgpt, I tried a version directly in the fields instead of the description like this:

receivers:
- jira_configs:
  - api_url: https://company.atlassian.net/rest/api/3/
    fields:
      description:
        type: doc
        version: 1
        content:
          - type: paragraph
            content:
              - type: text
                text: "Alert triggered from Alertmanager"
      customfield_10002:
      - 1

And this way, the unmarshal is not performed and the alert is well created in jira But I haven"t the templating option.

[bensalah-nabil]

i have the same issue to use jira api with alertmanager latest version

alertmanager[2201489]: time=2025-10-03T21:00:13.082Z level=ERROR source=dispatch.go:360 msg="Notify for alerts failed" component=dispatcher num_alerts=1 err="jira/jira[0]: notify retry canceled due to unrecoverable error after 1 attempts: failed to look up existing issues: HTTP request to JIRA API: unexpected status code 410: {"errorMessages":["The requested API has been removed. Please migrate to the /rest/api/3/search/jql API. A full migration guideline is available at https://developer.atlassian.com/changelog/#CHANGE-2046"],"errors":{}}"

[heliapb]

Hi, I'm currently dealing with the same issue. Funny enough I tested a couple of month ago with V3 and it worked then, now with the same config doesn't work anymore. I'm trying to add custom fields as we need for the final implementation but doesn't seem to work. Does anyone managed to get around the the templating issue?

{"time":"2025-10-15T11:54:21.772735217Z","level":"ERROR","source":"dispatch.go:360","msg":"Notify for alerts failed","component":"dispatcher","num_alerts":1,"err":"jira-receiver/jira[0]: notify retry canceled due to unrecoverable error after 1 attempts: failed to look up existing issues: HTTP request to JIRA API: unexpected status code 410: {\"errorMessages\":[\"The requested API has been removed. Please migrate to the /rest/api/3/search/jql API. A full migration guideline is available at https://developer.atlassian.com/changelog/#CHANGE-2046\"],\"errors\":{}}"}

EDIT - I now now why it work before, based of https://github.com/andygrunwald/go-jira/issues/738 seems to be related to a deprecation on v2 that happen.

[cjedro]

@lerminou could you post your whole example config? Did you create your own {{ template "jira.default.description" . }} ?

regarding

receivers:
- jira_configs:
  - api_url: https://company.atlassian.net/rest/api/3/
    fields:
      description:
        type: doc
        version: 1
        content:
          - type: paragraph
            content:
              - type: text
                text: "Alert triggered from Alertmanager"
      customfield_10002:
      - 1

description should be at the top level of the jira_config, not under fields.

@heliapb @bensalah-nabil i dont think this is related to the old search api being removed. This is resolved in 0.29.0-rc0 release

[lerminou]

Hi @cjedro , yes exactly, I tried the default jira description from alertmanager, here: https://github.com/prometheus/alertmanager/blob/main/template/default.tmpl#L176 Which is not in a ADF format, so it's not working.

I tried myself to set another template based os the official documentation https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/

I tried to set the top level description , but as I said, the json in the top level description is unmarshalled and the final json is not in the good format. The description in the fields is valid, just like another custom field but it's a raw value, I can't use alertmanager variable inside it.

for example:

templates:
  - '/etc/alertmanager/templates/*.tmpl'

jira_configs:
  - api_url: https://company.atlassian.net/rest/api/3/
    api_version: 'v3'
    description: '{{ template "jira.v3.descriptioncustom" . }}'

with the template:

{{ define "jira.v3.descriptioncustom" }}
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "Hello "
        },
        {
          "type": "text",
          "text": "world",
          "marks": [
            {
              "type": "strong"
            }
          ]
        }
      ]
    }
  ]
}
{{- end }}

I also tried inlined directly with and without EOL

jira_configs:
  - api_url: https://company.atlassian.net/rest/api/3/
    api_version: 'v3'
    description: |-
      {
        "type": "doc",
        "version": 1,
       [...]

Sorry if i'm not clear

[holger-waschke]

I can confirm v3 endpoint with atlassian document format is broken.

comparing API endpoint v2 /rest/api/<2/3>/issue/{issueIdOrKey} https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-put vs v3 https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-put

The expected request body format changed, this need´s some rework on application side.

[holger-waschke]

I´ll come up with a PR trying to make the jira integration ADF compatible.