### 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 the first iteration will require the user to: 1. Create a project or chose an existing one 1. Set up the existing JIRA integration for that Project, and 1. Start the import by specifying a JIRA project in a form on the Jira Import view * 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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-project-projectIdOrKey-get) * They must have `Browse` Project permissions and `Read` App permissions in the Jira project they want to import - User must be a GitLab admin or owner - Importing can be initiated when creating a project or via an existing project (gitlab~11353826 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 the `jira-ruby` gem installed. And we could use that to access Jira's REST API. Full Notes: https://gitlab.com/gitlab-org/gitlab/issues/208315#note_296151907 - [x] 1. Entry point experience -- direct to setup Jira Service Integration if not already configured - [x] 2.1 Use installed `jira-ruby` gem to access REST API to pull issues (handle pagination -- currently 100 issues per page) - [x] 2.2 Parse data and map it to a GitLab like data structure. - [x] 2.3 Make use of Sidekiq / service classes to create the issues - [x] 2.4 Provide some status update mechanism on the progress of the import process - [x] 3. [Update usage ping to collect usage metrics](https://about.gitlab.com/handbook/product/feature-instrumentation/#usage-ping) 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 <!-- What permissions are required to perform the described actions? Are they consistent with the existing permissions as documented for users, groups, and projects as appropriate? Is the proposed behavior consistent between the UI, API, and other access methods (e.g. email replies)?--> - `Admin` or `Owner` only ### Documentation <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html Add all known Documentation Requirements here, per https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements If this feature requires changing permissions, this document https://docs.gitlab.com/ee/user/permissions.html must be updated accordingly. --> - Yes, we will need documentation - Document the version of jira cloud/server api supported or tested on ? ### Availability & Testing <!-- This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier. What risks does this change pose to our availability? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance. * Unit test changes * Integration test changes * End-to-end test change See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-planning --> - 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? <!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. --> #### 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 - [x] The proposal is satisfied - [x] Documentation - [x] Use GitLab-UI - [x] [Usage ping updated to collect usage metrics](https://about.gitlab.com/handbook/product/feature-instrumentation/#usage-ping) - [x] 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~2933322. As we iterate to support importing epics, this will branch into different tiers such as gitlab~2278657 ### Working UX