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

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