Basic Usage Docs

[dylan-smith]

Create some basic docs on how to use the CLI tooling. Especially what PAT scopes are needed in order to run the various commands.

I've been testing with All Orgs + Full Access for the ADO PAT, and similarly broad scopes for the GH PAT.

The scopes needed will be diff for diff commands (e.g. generate-script only does ADO reads, but obviously some other commands are writing stuff).

There's another issue #20 to code in some explicit tests for the right permissions, this issue represents just figuring out what's needed and documenting it.

[bryantson]

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

ADO PAT Permission	Scopes
Build	Read
Code	Full & Status
Graph	Read & Manage
Identity	Read
Service Connections	Read
User Profile	Read

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:

GitHub PAT Permission	Scopes
Repo	Full
Org	admin

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

[dylan-smith]

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