A complete GitHub issue migration CLI tool written in Ruby.
STATUS: | Version | Date | Maintained? |
---|---|---|---|
Working | 1.0.1 |
2018-04-10 | YES |
Q: What does gh-missue
do?
The primary use is for migrating selected issues from any one repository to another. But it can do much more. You can also:
- Migrate issues, their labels and their comments in correct order.
- List any/all issues in any puplic repository
- List or migrate only issues selected by their status:
[all, open, closed]
- List all available issue labels for any repository
- Copy all available issue labels for any repository, including:
name, color, description
. - Use 3 different types of GitHub authentication: (none, OAuth2 token, username/password)
- Test your current GitHub request status showing your: rate limit, ramining requests, quota refresh time.
- Test your authentication token
- Learn about Ruby CLI options
- Decide to keep originally closed issues as closed or opened.
- Use the included class in your own tools
Q: What does it not do?
- Does not close issues on source repository after move
- Does not copy time-stamps. The new time is when the issue was moved.
- Does not copy issue-author. You will be the new author of all moved issues.
- Does not copy comment-authors. You will be the new author of all moved issue comments.
- Does not copy PR's. (But script can be easily modified to do so.)
Q: Why is this needed?
Sometimes, the structure of your project changes so drastically that it would break your repository. You need an easy way to start from scratch and just commit everything to a new repository. But, you've got all these valuable issues in the old repository on Github.
Q: Why are you using Ruby?
I have never used Ryby until a few evenings ago. I came across an old library to migrate issues on github. However, it was half broken and extremely limited. But using a library sucked and I wanted a proper CLI that could handle large request rates. I decided to hack into it. Ruby is a nice and suprisingly robust language and it is still alive. Not surprsingly it is used by GitHub themselves.
You can read more about Why Ruby isn't dead
: here and
here and
here.
Q: Will I continue to support this tool?
Sure, if it is broken, but I will not spend any more time for new features. So if you wanna add something please send me a PR.
This tool depends on:
- To make this run, you need to:
(a) have Ruby installed
(b) gem install GitHubs own "octokit" library
(c) gem install the option parser "docopt" - You should also consider creating a personal authentication token on GitHub,
to avoid getting rate-limited by a large number of requests in short time.
Installing Ruby on a RPi3
Installing Ruby on a Raspbian OS can be slightly tricky. There are essentailly 2 methods to do this.
- Installing the APK package called
Ryby3
.. - Installing Ruby from sources
I strongly recommend to use the first option, unless you plan to use Ruby a lot in the future, and to save a lot of time.
Installing the native Ruby package:
sudo apt-get install ruby2.3
sudo gem install bundler
Installing the gem dependecies:
sudo gem install octokit
sudo gem install docopt
# maybe I missed some others?
Installing gh-missue
git clone https://github.com/E3V3A/gh-missue.git
cd gh-missue
bundle install
There are several ways to run this tool. Please refer to the built-in help for details.
To show help, use the command option -h
, like this: ./gh-missue.rb -h
.
To copy all the open issues from one repository (<source_repo>
) to another (<target_repo>
):
- If you want your issues to also copy the issue labels and including the
name, color, description
tags,
you have to make sure the target repo does not already have any issue labels. If it does,
you need to remove them first, using the github web page under labels settings. - First copy all the issue labels with:
./gh-missue.rb -c <source_repo> <target_repo>
- Then copy all the open issues with:
./gh-missue.rb -t open <source_repo> <target_repo>
- If you omit creating all labels, the individual issue labels used, will still be created, but without color or description.
- If you hit a rate limit, you will need to insert your personal access token, before
<source_repo>
.
You can check your current rate limit with:./gh-missue.rb -r
๐ด If you need to copy more than 30 issues/hour, you will need to create a personal access token.
(Because the unauthenticated request limit is 60, and each copy operation need 2 requests.)
- If you are only migrating labels (with the
-c
option), make sure the labels doesn't already exist in the target repo, or you will have a failure. I.e. there are some default lables, that you need to remove from your target repo!
โน๏ธ For other bugs, issues, details and updates, please refer to the issue tracker.
Feel free to post issues and PR's related to this tool. Feel free to fork, break, fix and contribute. Enjoy!
Recommended similar tools
- github-issues-import and mod (Python)
- github-issue-mover (Dart)
- go-github-issues-mover (Go)
- offline-issues (JS) -- To read issues offline
References:
Essential GitHub API documents:
Labels-used-for-issues
https://developer.github.com/v3/issues/
https://developer.github.com/v3/issues/labels/
https://developer.github.com/v3/issues/labels/#get-a-single-label
https://developer.github.com/v3/issues/#list-issues-for-a-repository
https://developer.github.com/v3/#abuse-rate-limits
https://developer.github.com/v3/#rate-limiting
https://developer.github.com/v3/rate_limit/
https://developer.github.com/v4/guides/resource-limitations/
https://developer.github.com/v3/guides/best-practices-for-integrators/#dealing-with-rate-limits
https://developer.github.com/v3/#increasing-the-unauthenticated-rate-limit-for-oauth-applications
Most grateful thanks to:
- --- - for clarifying and fixing XXXX