Give a user-oriented view of permissions and changes

[BigLep]

Ideal

I think there should be some tooling that answers for person X:

1. what repos does X have permissions for
2. what permissions does X have on those repos,
3. why does X have those permissions (because part of a team, added directly to a repo, org owner/admin)

The current YAML file format is focused around repos and teams. I'm suggesting that we have a way to get a user-oriented view.

In a perfect world, the tooling could be fed the YAML file and return an entry per org member for their permission set. There's a potential JSON output example in libp2p/github-mgmt#12 (review).

You could then imagine running this diff before and after a change to show the diff. This makes it very clear for a user to understand how a given YAML change is impacting specific individuals.

Potential fallback?

While fully being able to simulate/analyze/determine Github's access permissions from a github-mgmt YAML would be ideal, a fallback is to list which roles/repos someone is gaining/losing access to.

Example:

@biglep
Removed from repos: repoName1/permissoinLevel1, repoName2/permissoinLevel2
Removed from teams: team1

That by itself will cut down on some of the confusion, but it will still need a disclaimer (e.g., "Even though your direct repo permissions have been removed, you may still have access through a team. Please check the full YAML file.").

Practical use-case

When doing permissions cleanup on an org, we want to tag users to notify them. When tagging them we need to make clear what is changing for them. Otherwise, they can easily misinterpret and assume that they are being removed from the org. I don't think we can assume the "lay person" to be up on the github-mgmt syntax and know how to quickly reason about the diff.

(libp2p/github-mgmt#12 (review) speaks to how there was confusion when folks were @mentioned and that they thought they were being removed from the org.)

Related

This came up in libp2p/github-mgmt#12 and ipld/github-mgmt#65