A complete GitHub issue migration CLI tool written in Ruby -- Migrate Like a Boss!
MIT License
A complete GitHub issue migration CLI tool written in Ruby.
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:
WIP
Migrate originally closed issues as closed or opened.[all, open, closed]
1,5-7,12
name, color, description
.Q: What does it not do?
gh
and hub
.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. Unfortunately, the new gh
tool only copies (transfer) one issue at the time, and with no additional control.
For any GitHub CLI usage, it is highly recommended to also install either gh
or hub
.
Both these tools allow you to do native GitHub Pull Requests.
There are 3 different ways to issue a native GitHub PR, depending on gh
or hub
.
#------------------------------------------------
# Using 'curl'
#------------------------------------------------
curl -X POST -H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/octocat/hello-world/pulls \
-d '{"head":"head","base":"base"}'
#------------------------------------------------
# Using 'gh' CLI
#------------------------------------------------
# Doing a simple PR using gh:
gh pr create --title "PR Title" --body "PR Body"
# To autofill the title and body of a pull request from your commits:
gh pr create --fill
# To specify branches
# where:
# -B, --base <branch> : The branch into which you want your code merged
# -H, --head <branch> : The branch that contains commits for your pull request (default: current branch)
gh pr create --base develop --head MYUSER:my-branch
#------------------------------------------------
# Using 'hub' CLI
#------------------------------------------------
# open a pull request for the branch you've just pushed
hub pull-request
# specify title and body
hub pull-request -m "PR Title" -m "PR Body"
# creates a pull request with explicit base and head branches
hub pull-request --base OWNER:master --head MYUSER:my-branch
# open a pull request with title & body from a file
hub pull-request --copy -F prepared-message.md
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.
(FFS always include a screenshot in your GitHub repo!)
This tool depends on:
Automatic install:
We are now in the public repo, under missue
.
gem install missue
Manual install:
To make this run, you need to:
(a) Have Ruby installed.
You can Manually install the WITHOUT DEVKIT
version of Ruby from here, or use:
winget install ruby
(b) gem install octokit
(c) gem install docopt
(d) Clone this repo:
git clone https://github.com/E3V3A/gh-missue.git
You also have to create a personal authentication token for your GitHub account. This is needed to be able to push the new issues and labels into your own repos. It also avoid you getting rate-limited by a large number of requests in short time. Learn how to do this here.
Run and test the app with:
# check version:
ruby.exe -v
# Set your GITHUB_OAUTH_TOKEN as an environment variable (here in Powershell)
$env:GITHUB_OAUTH_TOKEN = 'YOUR_40_CHAR_OATH2_TOKEN'
# List the current open issues (and labels) for this repo:
ruby.exe .\missue.rb -l open "YOUR_40_CHAR_OATH2_TOKEN" "E3V3A/gh-missue"
# Same as above, but with some more Warnings & Debug output:
ruby.exe -W2 .\missue.rb -d -l open "YOUR_40_CHAR_OATH2_TOKEN" "E3V3A/gh-missue"
# Check your current gitHub API Rate Limits:
ruby.exe .\missue.rb -r "YOUR_40_CHAR_OATH2_TOKEN"
$ ruby.exe .\bin\missue.rb -h
Description:
gh-missue is a Ruby program that bulk migrate issues from one github repository to another.
Please note that you can only migrate issues to your own repo, unless you have an OAuth2
authentication token. You can also list all the open or closed issues and PR's along with
the colored labels. It also include the original author's name and URL of the issues copied.
Usage:
missue.rb [-c | -n <ilist> | -t <itype>] <source_repo> <target_repo>
missue.rb [-c | -n <ilist> | -t <itype>] <oauth2_token> <source_repo> <target_repo>
missue.rb [-c | -n <ilist> | -t <itype>] <username> <password> <source_repo> <target_repo>
missue.rb [-d] -l <itype> [<oauth2_token>] <repo>
missue.rb -n <ilist>
missue.rb -t <itype>
missue.rb [-d] -r [<oauth2_token>]
missue.rb -d
missue.rb -v
missue.rb -h
Options:
-c - only copy all issue labels from <source> to <target> repos, including name, color and description
-l <itype> <repo> - list available issues of type <itype> (all,open,closed) and all labels in repository <repo>
-t <itype> - specify what type (all,open,closed) of issues to migrate. [default: open]
-r - show current rate limit and authentication method for your IP
-d - show debug info with full option list, raw requests & responses etc.
-n <ilist> - only migrate issues with comma separated numbers given by the list. Can include a range.
-h, --help - show this help message and exit
-v, --version - show version and exit
Examples:
missue.rb -r
missue.rb -l open E3V3A/gh-missue
missue.rb -t closed "E3V3A/TESTO" "USERNAME/REPO"
missue.rb -n 1,4-5 "E3V3A/TESTO" "USERNAME/REPO"
Dependencies:
missue.rb depends on the following gem packages: octokit, docopt.
Bugs or Issues?
Please report bugs or issues here:
https://github.com/E3V3A/gh-missue
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>
):
name, color, description
tags,./gh-missue.rb -c <source_repo> <target_repo>
./gh-missue.rb -t open <source_repo> <target_repo>
<source_repo>
../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 labels, 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!
References:
gh
hub
Essential GitHub API documents:
[1] https://developer.github.com/v3/issues/ [2] https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting [3] https://docs.github.com/en/rest/overview/media-types#request-specific-version [4] Some ideas for Labels-used-for-issues
Most grateful thanks to:
A license to 💖!