gh-missue -- Migrate Like a Boss!

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:

• Migrate issues, their labels and their comments in correct order.
• WIP Migrate originally closed issues as closed or opened.
• List any/all issues in any puplic repository
• List or migrate only issues selected by their status: [all, open, closed]
• Migrate issues selected by their issue numbers, like 1,5-7,12
• List all available issue labels for any repository
• List all repos R/W access availability info using your current access token.
• Copy all available issue labels for any repository, including: name, color, description.
• Use 2 different types of GitHub authentication: (none, OAuth2 token)
  (The GitHub Authentication API has discontinued allowing the use of username/password.)
• Test your current GitHub request status showing your: rate limit, remaining requests, quota refresh time.
• Test your authentication token

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.)
• Does not replace the highly useful GitHub CLI tools 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.

ClickMe! How to do a PR from CLI

There are 3 different ways to issue a native GitHub PR, depending on gh or hub.

• Using curl with the API
• Using gh
• Using 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.

---

Screenshots!

_{(FFS always include a screenshot in your GitHub repo!)}

---

Dependencies

This tool depends on:

1. docopt -- For amazingly cool command line option handling
2. octokit -- For GitHub API access

Installation

Automatic install:

We are now in the public repo, under missue.

gem install missue

Manual install:

1. 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

2. 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.

3. 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"

Usage

Click To See Usage!

$ 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

---

How to Run

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>):

1. 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.
2. First copy all the issue labels with:
   ./gh-missue.rb -c <source_repo> <target_repo>
3. 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

---

Bugs and Warnings

• 🔴 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.

Contribution

Feel free to post issues and PR's related to this tool. Feel free to fork, break, fix and contribute. Enjoy!

---

References:

• Ruby in 20 minutes
• Installing Ruby on Rail on RPi3
• How to write a Gemfile
• The GitHub CLI tool gh
• The GitHub CLI tool 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

---

Credits

Most grateful thanks to:

• Xanewok - for adding original author & issue link functionality

---

License

A license to 💖!