feat: enhance migration scripts with detailed error handling and usage instructions (#100)

* feat: enhance migration scripts with detailed error handling and usage instructions

* fix: update error messages to specify classic PAT

Author: joshjohanning

gh-cli/get-most-recent-migration-id-for-repository.sh

@@ -13,12 +13,54 @@ org="$1"
 repo="$2"
 return_only_id=${3:-false}
 
-migrations=$(gh api -X GET /orgs/$org/migrations -F per_page=100 --jq '.[] | {id: .id, repositories: .repositories.[].full_name, state: .state, created_at: .created_at}')
+# Make the API call with error handling
+migrations=$(gh api -X GET /orgs/$org/migrations -F per_page=100 --jq '.[] | {id: .id, repositories: .repositories.[].full_name, state: .state, created_at: .created_at}' 2>&1)
+exit_code=$?
+
+if [ $exit_code -ne 0 ]; then
+  if echo "$migrations" | grep -q "Authorization failed\|HTTP 403"; then
+    echo "Error: Authorization failed (HTTP 403)" >&2
+    echo "" >&2
+    echo "This endpoint requires a classic Personal Access Token (PAT) instead of OAuth CLI token." >&2
+    echo "Please export your classic PAT as GH_TOKEN:" >&2
+    echo "  export GH_TOKEN=your_classic_personal_access_token" >&2
+    echo "" >&2
+    echo "For more information, visit:" >&2
+    echo "https://docs.github.com/migrations/using-ghe-migrator/exporting-migration-data-from-githubcom" >&2
+    exit 1
+  elif echo "$migrations" | grep -q "Not Found\|HTTP 404"; then
+    echo "Error: Organization not found or no access to migrations (HTTP 404)" >&2
+    echo "" >&2
+    echo "This could mean:" >&2
+    echo "- The organization '$org' doesn't exist" >&2
+    echo "- You don't have access to view migrations for this organization" >&2
+    echo "" >&2
+    echo "Note: This endpoint requires a classic Personal Access Token (PAT)." >&2
+    echo "Make sure you have exported your classic PAT as GH_TOKEN:" >&2
+    echo "  export GH_TOKEN=your_classic_personal_access_token" >&2
+    exit 1
+  else
+    echo "Error: Failed to retrieve migrations" >&2
+    echo "$migrations" >&2
+    exit 1
+  fi
+fi
 
 if [ "$return_only_id" = "false" ]; then
   most_recent_migration=$(echo "$migrations" | jq -s -r --arg repo "$org/$repo" 'map(select(.repositories == $repo)) | sort_by(.created_at) | last')
 else
   most_recent_migration=$(echo "$migrations" | jq -s -r --arg repo "$org/$repo" 'map(select(.repositories == $repo)) | sort_by(.created_at) | last | .id')
 fi
 
+# Check if we found a migration for this repository
+if [ "$most_recent_migration" = "null" ] || [ -z "$most_recent_migration" ]; then
+  echo "Error: No migrations found for repository $org/$repo" >&2
+  echo "" >&2
+  echo "This could mean:" >&2
+  echo "- No migrations exist for this repository" >&2
+  echo "- The repository name is incorrect" >&2
+  echo "- You don't have access to migrations for this repository" >&2
+  exit 1
+fi
+
 echo "$most_recent_migration"

gh-cli/unlock-repository-migration-by-id.sh

@@ -4,10 +4,10 @@
 # you need to get the migration id first; ./get-most-recent-migration-id-for-repository.sh joshjohanning-org test-repo-export
 
 # Note: Use this other script to automatically look up the migration id for the repository: 
-# ./unlock-migrated-repository.sh joshjohanning-org test-repo-export
+# ./unlock-repository-migration.sh joshjohanning-org test-repo-export
 
-if [ -z "$2" ]; then
-  echo "Usage: $0 <org> <migration-id>"
+if [ -z "$3" ]; then
+  echo "Usage: $0 <org> <repo> <migration-id>"
   echo "Example: ./unlock-repository-migration-by-id.sh joshjohanning-org test-repo-export 4451412"
   exit 1
 fi
@@ -16,4 +16,41 @@ org="$1"
 repo="$2"
 id="$3"
 
-gh api -X DELETE /orgs/$org/migrations/$id/repos/$repo/lock
+echo "Attempting to unlock repository $org/$repo with migration ID: $id"
+
+# Capture the API response and check for errors
+response=$(gh api -X DELETE /orgs/$org/migrations/$id/repos/$repo/lock 2>&1)
+exit_code=$?
+
+if [ $exit_code -ne 0 ]; then
+  # Check for specific error patterns
+  if echo "$response" | grep -q "Authorization failed\|HTTP 403"; then
+    echo "Error: Authorization failed (HTTP 403)"
+    echo ""
+    echo "This endpoint requires a classic Personal Access Token (PAT) instead of OAuth CLI token."
+    echo "Please export your classic PAT as GH_TOKEN:"
+    echo "  export GH_TOKEN=your_classic_personal_access_token"
+    echo ""
+    echo "For more information, visit:"
+    echo "https://docs.github.com/migrations/using-ghe-migrator/exporting-migration-data-from-githubcom"
+    exit 1
+  elif echo "$response" | grep -q "Not Found\|HTTP 404"; then
+    echo "Error: Migration or repository lock not found (HTTP 404)"
+    echo ""
+    echo "This could mean:"
+    echo "- The migration ID ($id) is incorrect"
+    echo "- The repository is not locked"
+    echo "- You don't have access to this migration"
+    echo ""
+    echo "Note: This endpoint requires a classic Personal Access Token (PAT)."
+    echo "Make sure you have exported your classic PAT as GH_TOKEN:"
+    echo "  export GH_TOKEN=your_classic_personal_access_token"
+    exit 1
+  else
+    echo "Error: Failed to unlock repository"
+    echo "$response"
+    exit 1
+  fi
+fi
+
+echo "Successfully unlocked repository $org/$repo"

gh-cli/unlock-repository-migration.sh

@@ -12,6 +12,19 @@ fi
 org="$1"
 repo="$2"
 
+# Get the migration ID (error handling is done in the called script)
 id=$(./get-most-recent-migration-id-for-repository.sh $org $repo true)
+exit_code=$?
 
-gh api -X DELETE /orgs/$org/migrations/$id/repos/$repo/lock
+# Check if the migration ID script failed
+if [ $exit_code -ne 0 ]; then
+  # Error messages already printed by the called script
+  exit $exit_code
+fi
+
+# If we reach here, the migration ID was found successfully
+echo "Migration ID found: $id"
+echo "Delegating to unlock-repository-migration-by-id.sh..."
+
+# Delegate to the other script with proper error handling
+./unlock-repository-migration-by-id.sh "$org" "$repo" "$id"