Import Jira Issues MVC
Release Notes
features:
primary:
- name: "Import Jira issues into GitLab"
available_in: [starter, premium, ultimate]
documentation_link: ''
image_url: ''
reporter: kokeefe
stage: plan
categories:
- 'Issue Tracking'
issue_url: 'https://gitlab.com/gitlab-org/gitlab/issues/208315'
description: |
Migrating from Jira to GitLab has never been easier. Now you can import issues from your Jira project directly to your GitLab project.
Proposal
- For each JIRA issue in the JIRA project, create a corresponding issue in the GitLab project, with these mappings:
- JIRA issue summary -> GitLab issue title
- JIRA issue description -> GitLab issue description
- Simplified text handling/conversion
- GitLab issue author := GitLab user who activates this import process.
- Add import meta-data (timestamp, original author, Jira issue Key, etc.) to newly created GitLab issue (append to description or add comment)
- All other fields and attributes in the GitLab issue are set to as if it was created in the GitLab web UI with nothing beyond the above selected. E.g. the issue is in open state and there are no labels associated
Important
This will be the first of several "plan" specific importers we will need to build in the foreseeable future. I would architect this in a somewhat generic manner where the core import logic is somewhat isolated and we use vendor specific adapters to extend the base service. No need to over-engineer, but it is worth keeping in mind...
Implementation details
- This should support both Jira Server and Jira Cloud APIs
- User will be required to provide their Jira email address, API token, instance URL, and ID or project key. The key is case sensitive
- They must have
Browse
Project permissions andRead
App permissions in the Jira project they want to import
- They must have
- User must be a GitLab admin or owner
- Importing can be initiated when creating a project or via an existing project (~"group::import" to define where this ought to be located)
Implementation Breakdown
I don't think we need to use the REST API. We will be running these in Sidekiq and those have access to the whole Rails app. So we could create service classes to do this like we do in
lib/gitlab/github_import/importer/issue_importer.rb
. That would save us some overhead of another HTTP call. Also, just wanted to add that we already have thejira-ruby
gem installed. And we could use that to access Jira's REST API.
Full Notes: #208315 (comment 296151907)
-
1. Entry point experience -- direct to setup Jira Service Integration if not already configured -
2.1 Use installed jira-ruby
gem to access REST API to pull issues (handle pagination -- currently 100 issues per page) -
2.2 Parse data and map it to a GitLab like data structure. -
2.3 Make use of Sidekiq / service classes to create the issues -
2.4 Provide some status update mechanism on the progress of the import process -
3. Update usage ping to collect usage metrics
Each of these tasks can be worked independently and at the same time with some overlap of 1 and 2.4 if we would store credentials in the same jira_issue_imports
table
Permissions and Security
-
Admin
orOwner
only
Documentation
- Yes, we will need documentation
Availability & Testing
- We will need to write an end-to-end integration test that verifies Jira API compatibility at all times. i.e. if the Jira API changes, we should fail the build because there is a potential it will break this feature.
What does success look like, and how can we measure that?
Success Metrics
We should track the following usage metrics:
- Count of the number of times the importer is used
- Count of issues imported via the Jira importer
Acceptance Criteria
-
The proposal is satisfied -
Documentation -
Use GitLab-UI -
Usage ping updated to collect usage metrics -
Tests sufficiently implemented to prevent feature failure due to changes in external APIs we do not control
What is the type of buyer?
- For this initial MVC, we are targeting GitLab Starter. As we iterate to support importing epics, this will branch into different tiers such as GitLab Premium