search

github / gh-gei

Migration CLI for GitHub to GitHub migrations
MIT License
301 stars 81 forks source link

Improve documentation of advanced ADO-specific functionality #532

Open samueljmello opened 1 year ago

samueljmello commented 1 year ago

Description

I don't so much know if this is a bug, as it is a lack of documentation. Trying to utilize the ado2gh generate-script command with --rewire--pipelines requires a service connection to the GitHub app "azure pipelines" to exist. What isn't documented is that the connection name in ADO needs to be the GitHub organization name you are going to be migrating into. I couldn't find that documented anywhere and only realized it looking at the file AdoApi.cs line 183.

But that brings me to a larger problem of documentation around the ad2gh offering in general. It's pretty scarce (or possibly just spread-out?) and customers who are trying to use this could really use a little more direct assistance.

Reproduction Steps

  1. Create a GitHub PAT

  2. Install the "Azure Pipelines" app to your organization in GitHub

  3. Create an ADO PAT

  4. Create the "Service Connection" in ADO (name it "github")

  5. Attempt to run ado2gh generate-script with your parameters including --rewire-pipelines

  6. The script will say:

    CANNOT FIND GITHUB APP SERVICE CONNECTION IN ADO ORGANIZATION...

  7. Rename the "Service Connection" in ADO to be the same as the organization in GitHub

  8. Attempt to run the script again. This time it will succeed.

samueljmello commented 1 year ago

Was referencing here for documentation: https://docs.github.com/en/early-access/github/migrating-with-github-enterprise-importer/running-a-migration-with-github-enterprise-importer/running-a-migration-to-github-enterprise-cloud

It seems very incomplete.

That is referenced by README.md in this repo.

samueljmello commented 1 year ago

Another thought I had would be to update the share-service-connection command to validate the name of the connection. Customer used that and found that it just said "the connection already exists", despite generate-script not being able to see it.

It's either that or require a new flag (--service-connection-id) when using --rewire-pipelines, as that will be clearer for the user to understand.

dylan-smith commented 1 year ago

You are correct about the behavior. We definitely need to do a better job in our documentation around this.

Taking another pass over our docs, in particular ADO -> GH docs is something that I'm hoping to do soon, there's alot of room for improvement there.