Needed Scopes for Personal Access Tokens for Azure DevOps not sufficient

thunermay commented 2 weeks ago

Code of Conduct

[X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

Managing access for a migration from Azure DevOps https://docs.github.com/en/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#required-scopes-for-personal-access-tokens

What part(s) of the article would you like to see updated?

Required scopes for personal access tokens -> Personal access tokens for Azure DevOps

Additional information

The said scopes are not sufficient to generate an inventory report (gh ado2gh inventory-report). When giving the PAT full access on the ADO site, the generation worked. I'm sorry I don't have the time to figure out which scope is needed for this. This is the Error message without the needed scope:

[2024-07-03 15:37:59] [INFO] Generating orgs.csv...
[2024-07-03 15:37:59] [DEBUG] HTTP POST: https://dev.azure.com/REDACTED/_apis/Contribution/HierarchyQuery?api-version=5.0-preview.1
[2024-07-03 15:37:59] [DEBUG] HTTP BODY: {"contributionIds":["ms.vss-admin-web.organization-admin-overview-delay-load-data-provider"],"dataProviderContext":{"properties":{"sourcePage":{"routeValues":{"adminPivot":"organizationOverview"}}}}}
[2024-07-03 15:37:59] [DEBUG] RESPONSE (Unauthorized):
[2024-07-03 15:37:59] [ERROR] [HTTP ERROR 401] System.Net.Http.HttpRequestException: Response status code does not indicate success: 401 (Unauthorized).
   at System.Net.Http.HttpResponseMessage.EnsureSuccessStatusCode()
   at OctoshiftCLI.Services.AdoClient.SendAsync(HttpMethod httpMethod, String url, Object body)
   at OctoshiftCLI.Services.AdoClient.PostAsync(String url, Object body)
   at OctoshiftCLI.Services.AdoApi.GetOrgOwner(String org)
   at OctoshiftCLI.AdoToGithub.OrgsCsvGeneratorService.Generate(String adoPat, Boolean minimal)
   at OctoshiftCLI.AdoToGithub.Commands.InventoryReport.InventoryReportCommandHandler.Handle(InventoryReportCommandArgs args)
   at OctoshiftCLI.Extensions.CommandExtensions.RunHandler[TArgs,THandler](TArgs args, ServiceProvider sp, CommandBase`2 command)
   at OctoshiftCLI.Extensions.CommandExtensions.<>c__DisplayClass1_0`3.<<ConfigureCommand>b__0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Invocation.AnonymousCommandHandler.InvokeAsync(InvocationContext )
   at System.CommandLine.Invocation.InvocationPipeline.<>c__DisplayClass4_0.<<BuildInvocationChain>b__0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass17_0.<<UseParseErrorReporting>b__0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass12_0.<<UseHelp>b__0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass22_0.<<UseVersionOption>b__0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass19_0.<<UseTypoCorrections>b__0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c.<<UseSuggestDirective>b__18_0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass16_0.<<UseParseDirective>b__0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c.<<RegisterWithDotnetSuggest>b__5_0>d.MoveNext()
--- End of stack trace from previous location ---
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass8_0.<<UseExceptionHandler>b__0>d.MoveNext()

welcome[bot] commented 2 weeks ago

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

nguyenalex836 commented 2 weeks ago

@thunermay Thank you for opening an issue! I'll get this triaged for review ✨

vgrl commented 1 week ago

Hi @thunermay 👋 Thanks for opening this issue! After investigating your report, it appears the requirement for Full Access scope for inventory-report and integrate-boards is a known issue, and there's not much GitHub can currently do about it unless Azure DevOps changes their API's.

I have however passed along your experience to the internal GitHub team responsible for migrations, for consideration in future conversations about how to improve this feature and GitHub.

It sounds like updating our docs, by changing a sentence and adding another, may help other users learn of this requirement. I suggest, in the "Personal access tokens for Azure DevOps" section, we make the following changes.

Change the following sentence:

If you want to use the --integrate-boards or --rewire-pipelines flags when generating a migration script, you will also need Build (Read) scope.

to:

If you want to use the --rewire-pipelines flag when generating a migration script, you will also need Build (Read) scope. To use the inventory-report and --integrate-boards flags, you will need to grant full access to your personal access token.

You or anyone else is welcome to open a PR with a fix for this issue.

github / docs