Handle updated Jira API calls to permit Jira issue imports again

Ben Kingrequested to merge
benjaminking-jira-http-errors into master

What does this MR do and why?

As noted in #581103, we're currently facing a problem where customers that utilise Jira can't import projects into GitLab. This is due to a change in the Jira REST API which updates and removes some searchable paths we utilised. Some parts of the codebase have already been updated, but the Jira issue import feature is still broken.

Through a collaboration session with Claude and Duo Agent Platform, I have a (rough) basic proof-of-concept that is now updated to properly import issues again, through both Jira Cloud and Jira Server (Data Center). Further work will be required to ensure this is production ready.

What's "ADF" and why are we converting it back to text?

Atlassian has noted that in the v3 of the REST API, they use Atlassian Document Format in several fields, including description. As a result of this we need to convert the format that it presents into something usable in the import.

An example of what the description field looks like to use before it is converted:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "This is something important over here. "
        }
      ]
    }
  ]
}

I have found that Banzai::Filter::JiraImport::AdfToCommonmarkFilter exists in the codebase and seems to be able to do what we want, which is to convert this JSON structure into Markdown. The result of this is an almost accurate rendering of the original issue, though some formatting like underline doesn't come across. For example:

Jira Cloud original description Formatted to Markdown and imported
image.png image.png

For Jira Server/Data Center instances, as we still use the original REST API endpoint, we do not get nicely formatted content. This reflects the pre-existing state of the import:

image.png

Screenshots or screen recordings

Jira Cloud Demo Jira Server Demo
2025-12-02 13-40-46.mov 2025-12-02 13-39-14.mov

How to set up and validate locally

Before you begin, you should have at least a developer Atlassian account with a project for Jira Cloud. For Jira Server, you may need to deploy your own Jira Server instance, or contact me for temporary access to hit the REST API of my server. Ensure the issues on your deployment consists of a few issues in different states (Doing, Done), with descriptions and labels.

  1. Create a project.
  2. In the project's integration settings, set up your connection to either the Jira Cloud or Jira Server URL. Test Connection should come back successful.
  3. In the project's issues, attempt to import via selecting to Import from Jira.
  4. It will prompt you to select a project (if applicable) and user mapping. Select your project, and leave mapping alone.
  5. The import will begin. Go to the project's issues and confirm that all applicable issues have been brought across.

This should be repeated for both Jira Cloud and Jira Server.

Keep in mind the current limitations of the feature:

GitLab imports the following information directly:

  • The issue’s title, description, and labels.
  • You can also map Jira users to GitLab project members when preparing for the import.

Other Jira issue metadata that is not formally mapped to GitLab issue fields is imported into the GitLab issue’s description as plain text.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Ben King

Merge request reports