#GraphQL client to migrate issues from Github to Sourcehut

This tool will migrate all issues from a github repository (private or public) to a Sourcehut todo.sr.ht ticket tracker.

#Requirements and installation

You need a Github personal access token (create one here).

Note about scopes of the Github access token for this client:

• For public code repositories you don't need any scopes, just create an empty personal access token
• For private code repositories you need to tick the repo checkbox

You need a Sourcehut personal access token (create one from here).

Note about scopes of the Sourcehut access token:

• For todo.sr.ht should have the following scopes: PROFILE,TRACKERS,TICKETS,ACLS,EVENTS,SUBSCRIPTIONS

#Build

From sources:

git clone --single-branch --depth=1 https://git.sr.ht/~jman/github-migrate-tool
cd github-migrate-tool
cargo build [ --release ]

#Build statically linked binary

Two options:

• Using cargo cross, (Docker/Podman under the hood) and vendoring openssl:

  RUSTFLAGS='-C target-feature=+crt-static' cross build [ --release ]
  

• With musl libc:

  sudo apt install musl
  rustup target install x86_64-unknown-linux-musl
  cargo build --target x86_64-unknown-linux-musl [ --release ]
  

#Usage

Before starting the migration, you might want to temporarily disable notifications on the destination issue tracker (which by default sends an email for every new ticket).

For big migrations, consider using the import tracker dump function of todo.sr.ht.

cargo run -- -n <repo_name> -o <repo_owner> -t <srht_tracker_id>

# Example:
export GITHUB_TOKEN=xxx
export SRHT_TOKEN=yyy
cargo run -- -n Hello-World -o octocat -t 1234

• -l / --only-labels: Only migrate labels from the Github repository
• -n / --gh-repo-name <GH_REPO_NAME>: Github name repository (can also be private)
• -o / --gh-repo-owner <GH_REPO_OWNER>: Github owner repository (can also be an organization)
• -s / --strip-authors: strip original authors from issues and comments and replace them with the Github @ghost user.
• -t / --tracker-id <TRACKER_ID>: Destination tracker of todo.sr.ht. Tracker must be existing.
• -v / --verbose: verbose output

Notes:

• Labels import is idempotent (running this command twice will not create duplicates) and labels are migrated in a case sensitive fashion ("bug" is not equal as "Bug").
• Issues import is NOT idempotent: if you import the same Github issue twice, you will create 2 separated todo.sr.ht tickets. Duplicates must be manually handled - or purge the tracker before import.
• Sourcehut tickets Id will not match Github issues Id: a Github issue will always receive a new Sourcehut ticket Id.
• References in issue comments pointing to other issues from the same Github repository will be converted to the corresponding Sourcehut ticket id.
• This tool does not migrate Github pull requests, projects, discussions or milestones.
• Due to this issue, comments author and date cannot be imported yet. Comments will appear created by the Sourceut tracker owner (your Sourcehut user) and the date of creation will be the date of creation in Sourcehut. An annotation with the original author and creation date is added to the comment body.

#Testing

Run cargo test and cargo insta test.

#GraphQL references

GraphQL Github explorer: https://docs.github.com/en/graphql/overview/explorer or use Insomnia.

Reference: https://docs.github.com/en/graphql/reference/queries

GraphQL documentation: https://graphql.org/learn/schema/#type-system

Github GraphQL schema and endpoint.

todo.sr.ht GraphQL schema and endpoint.

#Insomnia client

To test the GraphQL APIs of both services, you can use the Insomnia client: download it from here. Being an Electron application, on Wayland run it with:

./insomnia --enable-features=UseOzonePlatform --ozone-platform=wayland --incognito

#TODO

• Implement some basic book-keeping to avoid creating the same issues on subsequent migrations

#Similar projects

• gh-sh-issues: a Python script to export issues, Pull-requests, labels from Github and import them into todo.sr.ht via GraphQL API. Converts references to issues/PRs/discussions.
• gh2shrt: a Go script to export issues and labels from Github and save them to a file suitable for import into todo.sr.ht