git.marmaro.de Git - mantis2gitlab/blob - README.md

   1 # Mantis2GitLab
   2
   3 Script for importing Mantis issues into (a new project in) GitLab.  The created GitLab issues will have the same
   4 issue numbers are the corresponding Mantis issues.  Please do not use this script against a GitLab project that
   5 has GitLab issue.
   6
   7 The script performs the following:
   8
   9  * Reads configuration file and Mantis SVN export
  10  * Fetches GitLab Project and Members
  11  * Fetches existing issues from GitLab Project
  12  * For each Mantis Issue
  13    * If a corresonding GitLab issue exists, its Title, Description, Labels and Closed status are updated
  14    * Otherwise
  15      * If there is a "gap" in Mantis issue numbers, "Skipped Mantis Issue" GitLab issue(s) are created
  16      * A new GitLab issue is created with an appropriate Title, Description, Labels and Closed status
  17
  18 ## Install
  19
  20 ```
  21 npm install -g nonplus/mantis2gitlab
  22 ```
  23
  24 ## Usage
  25
  26 ```
  27 m2gl -i options
  28 ```
  29
  30 ## Options
  31
  32 ```
  33   -i, --input      CSV file exported from Mantis (Example: issues.csv)               [required]
  34   -c, --config     Configuration file (Example: config.json)                         [required]
  35   -g, --gitlaburl  GitLab URL hostname (Example: https://gitlab.com)                 [required]
  36   -p, --project    GitLab project name including namespace (Example: mycorp/myproj)  [required]
  37   -t, --token      An admin user's private token (Example: a2r33oczFyQzq53t23Vj)     [required]
  38   -s, --sudo       The username performing the import (Example: bob)                 [required]
  39   -f, --from       The first issue # to import (Example: 123)
  40 ```
  41
  42 ## Config File
  43
  44 In order to correctly map Mantis attributes you should create a JSON file and specify it with the **-c** switch.
  45
  46 ### Users
  47
  48 This section maps Mantis `username` (Reporter, Assigned To, etc.) to a corresponding GitLab user name.
  49
  50 ```
  51 {
  52   "users": {
  53     "mantisUserName1": {
  54       "gl_username": "GitLabUserName1"
  55     },
  56     "mantisUserName2": {
  57       "gl_username": "GitLabUserName2"
  58     }
  59   }
  60 }
  61 ```
  62
  63 ### Mantis URL (optional)
  64
  65 This setting defines the URL to the old mantis installation.  When specified, Mantis cases imported in GitLab
  66 will contain a back-link to their corresponding Mantis issue.
  67
  68 ```
  69 {
  70   "mantisUrl": "https://www.oldserver.com/mantis"
  71 }
  72 ```
  73
  74 ### Category Labels (optional)
  75
  76 This section maps Mantis Categories to corresponding GitLab labels.
  77
  78 ```
  79 {
  80   "category_labels": {
  81     "Admin UI": "area:Admin",
  82     "Voter UI": "area:Voter",
  83     "Server": "area:Service"
  84     }
  85 }
  86 ```
  87
  88 ### Priority Labels (optional)
  89
  90 This section maps Mantis Priorities to corresponding GitLab labels.
  91 Note that the numeric priorities are used when exporting from SQL.
  92
  93 ```
  94 {
  95   "priority_labels": {
  96     "20": "priority:low",
  97     "low": "priority:low",
  98     "40": "priority:high",
  99     "high": "priority:high",
 100     "50": "priority:urgent",
 101     "urgent": "priority:urgent",
 102     "60": "priority:immediate",
 103     "immediate": "priority:immediate"
 104   }
 105 }
 106 ```
 107
 108 ### Severity Labels (optional)
 109
 110 This section maps Mantis Severities to corresponding GitLab labels.
 111 Note that the numeric severities are used when exporting from SQL.
 112
 113 ```
 114 {
 115   "severity_labels": {
 116         "10": "severity:feature",
 117         "feature": "severity:feature",
 118         "20": "severity:trivial",
 119         "trivial": "severity:trivial",
 120         "30": "severity:text",
 121         "text": "severity:text",
 122         "40": "severity:tweak",
 123         "tweak": "severity:tweak",
 124         "50": "severity:minor",
 125         "minor": "severity:minor",
 126         "60": "severity:major",
 127         "major": "severity:major",
 128         "70": "severity:crash",
 129         "crash": "severity:crash",
 130         "80": "severity:block",
 131         "block": "severity:block"
 132   }
 133 }
 134 ```
 135
 136 ### Closed Statuses (optional)
 137
 138 This section maps which Mantis Statuses indicate that the issue is closed.
 139 Note that the numeric severities are used when exporting from SQL.
 140
 141 ```
 142 {
 143   "closed_statuses": {
 144         "80": true,
 145         "resolved": true,
 146         "90": true,
 147         "closed": true
 148   }
 149 }
 150 ```
 151
 152 ## Exporting From Mantis
 153
 154 The input to this script is a CSV file with the following columns:
 155
 156   * `Id` - Will create a corresponding GitLab *Issue*
 157   * `Summary` - Will create a corresponding GitLab *Title*
 158   * `Category` - Will create a corresponding GitLab *Label* from `config.category_labels[Category]`
 159   * `Priority` - Will create a corresponding GitLab *Label* from `config.priority_labels[Priority]`
 160   * `Severity` - Will create a corresponding GitLab *Label* from `config.severity_labels[Severity]`
 161   * `Created` - Will be included in the *Description* header
 162   * `Updated` - Will be included in the *Description* header, if different from `Created`
 163   * `Reporter` - Will be included in the *Description* header
 164   * `Assigned To` - Will be included in the *Description* header
 165   * `Description` - Will be included in the *Description*
 166   * `Info` - Will be appended the *Description*
 167   * `Notes` - Will be split on `"$$$$"` and appended the *Description*
 168
 169 ### Exporting from Mantis UI
 170
 171 You can export a summary of the Mantis issues from the _View Issues_ page by clicking on the _Export CSV_ button.
 172
 173 **Note:** This export will only include a subset of the issues and is not the recommended approach.
 174
 175 ### Exporting from database
 176
 177 The following SQL query pulls all the supported columns from the Mantis database. Make sure you specify the correct `PROJECT_NAME`:
 178
 179 ```
 180 SELECT
 181         bug.id as Id,
 182         project.name as Project,
 183         bug.category as Category,
 184         bug.summary as Summary,
 185         bug.priority as Priority,
 186         bug.severity as Severity,
 187         bug.status as Status,
 188         bug.date_submitted as Created,
 189         bug.last_updated as Updated,
 190         reporter.username as Reporter,
 191         handler.username as "Assigned To",
 192         bug_text.description as Description,
 193         bug_text.additional_information as Info,
 194         GROUP_CONCAT(
 195                                 CONCAt('*', bugnote.date_submitted, ' - ', note_reporter.username, '*
 196
 197 ', bugnote_text.note)
 198                                 ORDER BY bugnote.Id
 199                                 SEPARATOR '$$$$'
 200                         ) as Notes
 201 FROM
 202         mantis_bug_table as bug
 203         JOIN mantis_project_table project ON bug.project_id = project.id
 204         JOIN mantis_bug_text_table bug_text ON bug.bug_text_id = bug_text.id
 205         JOIN mantis_user_table as reporter ON bug.reporter_id = reporter.id
 206         LEFT OUTER JOIN mantis_user_table as handler ON bug.handler_id = handler.id
 207         LEFT OUTER JOIN mantis_bugnote_table as bugnote ON bugnote.bug_id = bug.id
 208         LEFT OUTER JOIN mantis_bugnote_text_table as bugnote_text ON bugnote.bugnote_text_id = bugnote_text.id
 209         LEFT OUTER JOIN mantis_user_table as note_reporter ON bugnote.reporter_id = note_reporter.id
 210 WHERE
 211         project.name = 'PROJECT_NAME'
 212 GROUP BY bug.id
 213 ORDER BY bug.id
 214 ```
 215
 216 ## Notes
 217 - Make sure the input CSV file only includes issues for the project you want to import.
 218 - In version 6.4.3, GitLab API does not support setting creation date of issues. So all imported issues will have a creation time of now.
 219 - In version 6.4.3, GitLab API fails to import issues with very long titles.
 220 - In version 6.4.3, GitLab does not allow issues to be deleted. So be careful when importing issues into an active project.
 221 - Milestones are not currently supported.
 222
 223 ## Version History
 224 + **1.0**
 225         + Initial release
 226
 227 ## Author
 228 **Stepan Riha**
 229
 230 + http://github.com/nonplus
 231
 232 ## Copyright and License
 233
 234 Based on https://github.com/soheilpro/youtrack2gitlab
 235
 236 Copyright 2015 Stepan Riha
 237
 238 Licensed under the The MIT License (the "License");
 239 you may not use this work except in compliance with the License.
 240 You may obtain a copy of the License in the LICENSE file, or at:
 241
 242 http://www.opensource.org/licenses/mit-license.php
 243
 244 Unless required by applicable law or agreed to in writing, software
 245 distributed under the License is distributed on an "AS IS" BASIS,
 246 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 247 See the License for the specific language governing permissions and
 248 limitations under the License.