Basic Usage Docs about gh-gei HOT 2 CLOSED

@dylan-smith

Can you update the last README.md with the following instruction?

To actually generate a script, you'll need to set an ADO_PAT as an environment variable with the following permissions:

To test, you can run disable-ado-repo command with the following format:

octoshift disable-ado-repo --ado-org <YOUR ADO organization name> --ado-team-project <Your ADO Project name> --ado-repo <Your repo name>

Make sure to enable your Azure DevOps Repo again before you start the migration.

Performing any of the commands that actually touch GitHub will need the GH_PAT environment variable with the following permissions:

For example, the following command with generate a Bash script file called migrate.sh with the commands to migrate all enabled repos from ADO to your GitHub Organization.

octoshift generate-script --github-org <Your GitHub Organization> --ado-org <Your ADO organization> --output migrate.sh

WARNING - 11/06/21: As of now, the script will generate a command starting with ./octoshift, which currently points to the current directory. You need to change those lines to octoshift to point to the environment level.

Running that generated file, for example migrate.sh after chmod with chmod +x migrate.sh will start the migration process. However, before start doing so, you have to install the Azure Pipeline App in your GitHub Profile and connect with Azure DevOps project. Otherwise, you will get this error:

[WARNING] CANNOT FIND GITHUB APP SERVICE CONNECTION IN ADO ORGANIZATION: xxxx. You must install the Pipelines app in GitHub and connect it to any Team Project in this ADO Org first

from gh-gei.

We'll need to condense this down into something easier for customers to consume, but here's the detailed info on what scopes are needed for which commands:

generate-script
ADO: Build (Read)
ADO: Code (Read)
ADO: Service Connections (Read)

generate-script (--repos-only)
ADO: Build (Read) -- REMOVING THIS in v0.5
ADO: Code (Read)

migrate-repo
ADO: Code (Read)
GH: Repo (all)
GH: read:org
** ADO: Identity (Read)
** ADO: Work Item (Read)

add-team-to-repo
GH: Repo (All)

configure-autolink
GH: Repo (All)

create-team
GH: Repo (All)

lock-ado-repo
ADO: Code (Read)
ADO: Identity (Read)
ADO: Security (Manage)

disable-ado-repo
ADO: Code (Read, write & manage)

rewire-pipeline
ADO: Build (Read & execute)

share-service-connection
ADO: Full Access

integrate-boards
ADO: Full Access (for GetGithubHandle API)
GH: Repo (All)

grant-migrator-role
GH: read:org

revoke-migrator-role
GH: read:org

from gh-gei.