Is the API insane with respect to collaborators or am I confused?

I am trying to write some tooling to manage repository collaborators. The collaborators api is giving me an intense headache, and I’m just looking for someone to sanity check that I’m not missing something obvious.

When adding a collaborator to a repository, permission is a string that can be one pull , push , admin , maintain , or triage.

When listing collaborators in a repository, permissions is a dictionary that has the keys pull, push, maintain, admin, and triage.

When getting repository permissions for an individual user, we get both a permission and a role_name. I’m not sure what the list of valid values for these attributes looks like, but it includes write . I’m assuming it’s the names list here.

For PUT /repos/{owner}/{repo}/collaborators/{username} vs GET /repos/{owner}/{repo}/collaborators/{username}/permission, is the correspondence
simply:

Grant permission name Get permission name
Pull Read
Triage Triage
Push Write
Maintain Maintain
Admin Admin

?

And for PUT /repos/{owner}/{repo}/collaborators/{username} vs GET /repos/{owner}/{repo}/collaborators, is the correspondence:

Grant permission name List permission attributes
Pull pull
Triage pull, triage
Push pull, triage, push
Maintain pull, triage, push, maintain
Admin pull, triage, push, maintain, admin

?

Will the permissions dictionary aver have a different set of true
attributes than in the above table (can someone have maintain and
pull without triage and push)? It doesn’t make sense, but it’s
not clear why the list endpoint returns a single value instead of this
dictionary.

Thanks!

Hi @larsks
As you say there are some differences across the various API’s as to what the the various roles are called. This may in some part be due to legacy, things changing over time and desire to avoid changing impacting APIs already in existence. You may bump into some further examples in the REST/GRAPHQL and nuances around whether the two newer roles (Triage and Maintain) are represented in all APIs.

It is in fact a repository role you are assigning to a user/team and each role has the permissions listed in the GitHub permissions table in the docs link you provided.
In order or last to most permissioned role
Read (pull)
Triage
Write (push)
Maintain
Admin

You will also see from the permission table that each subsequent roles has all permissions of roles that precede it.
If using GitHub Cloud I think the free Free, Pro and Team plans may not include Triage and Maintain roles.
For Enterprise plan there is also the option for a limited number of custom roles, that inherit from one of the roles but allowing you to add one or more specific permissions as well to the custom role. I haven’t test myself how this gets represented in all the APIs though

This post was flagged by the community and is temporarily hidden.