Skip to content

Commit b5e8592

Browse files
bmarkovicbmarkovic
committed
First working release, seems to do everything I know how to
1 parent fc3a5a7 commit b5e8592

File tree

10 files changed

+771
-374
lines changed

10 files changed

+771
-374
lines changed

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License
2+
3+
Copyright (c) 2018 Bojan Markovic http://bmarkovic.github.io
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎README.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# jira2gitlab
2+
3+
2018 Bojan Markovic
4+
<[email protected]>
5+
6+
Imports issues from JIRA to Gitlab.
7+
8+
> Note: Use at your own peril
9+
10+
## Installation
11+
12+
It is a Node.js CLI application. It uses modern ES features so the latest LTS
13+
(currently Node 10) is strongly recommended.
14+
15+
Provided that you already have Node on your system
16+
([otherwise see here](https://nodejs.org/en/download/package-manager/))
17+
you can simply pull dependencies with:
18+
19+
$ npm install
20+
21+
amd you're ready to go.
22+
23+
## Usage
24+
25+
The program is started with:
26+
27+
$ nodw . [go]
28+
29+
If you can't be bothered to deal with Node (I don't blame you) you can use the
30+
provided binary releases. The usage is similar except taht instead of the line
31+
above you use
32+
33+
$ jira2gitlab [go]
34+
35+
If you don't provide the `go` CLI parameter it will not attempt to write to the
36+
gitlab instance but will only dump all the downloaded content into the
37+
`payloads` directory. You can examine the JSON files, and `gitlab-issues.json`
38+
in particular, to see how the posted Gitlab issues will look before posting
39+
them to the Gitlab project.
40+
41+
If the file `config.json` is not present in the program directory it will exit
42+
with an error and dump a default `config.json` to the filesystem, that you can
43+
then edit with your required data. The configuration is commented below:
44+
45+
```javascript
46+
{
47+
"jira": { // JIRA config settings
48+
"url": "http://jira.attlasian.net", // JIRA instance base URL
49+
"project": "PROJ", // JIRA project key / short name
50+
"account": { // JIRA Authentication
51+
"username": "[email protected]", // JIRA username
52+
"password": "1234" // JIRA password
53+
}
54+
},
55+
"gitlab": { // Gitlab config settings
56+
"url": "https://gitlab.com", // Gitlab base URL
57+
"project": "namespace/project", // Gitlab namespaced project name
58+
"token": "" // Gitlab personal access token
59+
},
60+
"settings": { // jira2gitlab settings
61+
62+
"rejectUnauthorized": false, // Set to true to reject self-signed
63+
// certificates for either service
64+
65+
"ignoreDone": false, // Whether not to upload issues that
66+
// were closed in JIRA. Note that if
67+
// you decide to upload an issue it will
68+
// be opened due to Gitlab API
69+
// limitations
70+
71+
"sudo": true // Gitlab API sudo. Use this to post
72+
// issues to gitla
73+
}
74+
}
75+
```
76+
77+
## Notes
78+
79+
### User Matching
80+
81+
The program will try to match users if they exist in both JIRA and Gitlab
82+
instances, by email address. If no match is found the user field, if mandatory
83+
will be infered to belong to the token owner (see: Gitlab Personal Access
84+
Token).
85+
86+
For this to work fully (issues and comments appearing as if they were created
87+
by the actual JIRA author) all users must exist in both services, with same
88+
email adresses, and the user whose token is used on Gitlab must be a Gitlab
89+
admin.
90+
91+
Finally, the token must have sudo rights (chosen when generating token), and
92+
the `settings.sudo` config option must be set to `true`.
93+
94+
### Closed/Fixed issues
95+
96+
As of this writing there isn't a way to close an issue through the API that is
97+
known to me, nor to relay the clossed state for a newly created issue through
98+
it.
99+
100+
The `settings.ignoreDone` flag let's you configure whether you want to ignore
101+
the resolved issues (i.e. not copy them at all) or if you want them copied even
102+
if that means that the issue will be open in Gitlab.
103+
104+
Set the option to `true` if you don't want resolved issues copied over.
105+
106+
### Gitlab Personal Access Token
107+
108+
Gitlab API authentication uses a token which you can issue yourself by visiting
109+
110+
https://<gitlab_base_uri>/profile/personal_access_tokens
111+
112+
On that page you need to name the token, tick all the access restriction boxes
113+
and **copy the issued token string somewhere safe**, as AFAIK you cannot see it
114+
again after you close the page (but you can issue another one).
115+
116+
Ticking all access restriction boxes is important. Unless you are an Admin user
117+
of the Gitlab instance and
118+
119+
This string is what you need to paste into the `token` key in the config.
120+
121+
### Debug Mode
122+
123+
You can get very verbose output about the activities of the script by starting
124+
the script with `DEBUG` environment variable set to a positive numerical value:
125+
126+
$ DEBUG=1 node . go
127+
128+
The program uses [chalk](https://github.com/chalk/chalk) to colorize the output.
129+
If you want to preserve the colorized output (for example for future inspection
130+
with something like `less`) use the `FORCE_COLOR` environment variable:
131+
132+
$ DEBUG=1 FORCE_COLOR=1 node . go | tee jira2gitlab.log
133+
134+
Then you can replay the logfile with colors using e.g. `less jira2gitlab.log`
135+
136+
## License
137+
138+
Licensed under MIT License. See `LICENSE` file in repository root.
139+
140+
## Acknowledgment / Rationale
141+
142+
Some of the code is based on the information from the following
143+
[blog post](https://about.gitlab.com/2017/08/21/migrating-your-jira-issues-into-gitlab/),
144+
which, in turn, is originally from
145+
[here](https://medium.com/linagora-engineering/gitlab-rivals-winter-is-here-584eacf1fe9a)
146+
147+
Unfortunately, some of the original information is somewhat missleading and in
148+
case of Gitlab API in particular, often wrong. The code from this project is
149+
the working version of ideas presented in the post.
150+
151+
I've also chosen to use [`needle`](https://github.com/tomas/needle) over
152+
`axios` due to it's much terser and simpler support for binary file I/O and the
153+
fact that it doesn't needlessly translate to/from Node `http` idioms and API
154+
that it wraps, making me rely on it's own documentation less (and, as tradition
155+
dictates, almost everyone has made one AJAX lib for Node, and failed to
156+
document it apart from the "look how nice my API is" marketing).

0 commit comments

Comments
 (0)