Skip to content

doc: overhaul permissions docs

Administrator requested to merge docs/perms-workings into main

Created by: bobheadxi

Attempts to fill in some mysteries of the internal workings of permissions sync that have been a huge source of confusion lately.

  • GitHub permissions clarifications
    • fix possible misconception about webhooks - webhooks don't improve the speed, they improve the relevancy of sync, i.e. are not a solution to slow sync times
    • add detail about token account needs equivalent access to repos
    • fix scopes (realized there's no such thing as read:repo and write:repo 🤦
  • Background permissions syncing is now the subsection to go to for everything about how background sync works. Added some details to most of the sections (especially "complete vs incremental sync") + created some new sections image
  • remove unnecessary detail in multi-codehost docs (all you need to do is log in from the relevant auth providers, and it's not specific to GH/GHE - cc @justdueck )

To review:

gh pr checkout 26475
sg run docsite

And go to http://localhost:5080/admin/repo/permissions#background-permissions-syncing

Merge request reports

Loading